FieldTalk Modbus Slave C++ Library Library version 2.11.0

- Introduction
- Chapters
- Modules
- Classes

- Class List
- Class Hierarchy
- Class Members

Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
MbusRtuOverTcpSlaveProtocol Class Reference
IP based Protocols

This class realises the Encapsulated Modbus RTU slave protocol. More...

## Public Member Functions
| MbusRtuOverTcpSlaveProtocol ()
| Instantiates an Encapsulated Modbus RTU server object. More...
int | startupServer ()
| Puts the Modbus server into operation. More...
int | startupServer (const char *const hostName)
| Puts the Modbus server into operation. More...
void | shutdownServer ()
| Shuts down the Modbus server. More...
int | setConnectionTimeOut (long masterTimeOut)
| Configures connection time-out. More...
long | getConnectionTimeOut ()
| Returns the connection time-out setting. More...
void | installMasterDisconnectCallBack (void(*f)(void *userData, const char *masterIpAddrSz, DisconnectReason reason), void *userData)
| This function installs a callback handler to be called in the event of a master disconnection. More...
int | addDataTable (int slaveAddr, MbusDataTableInterface *dataTablePtr)
| Associates a protocol object with a Data Provider and a Modbus slave ID. More...
int | getConnectionStatus ()
| Checks if a Modbus master is polling periodically. More...

## Static Public Member Functions
static const TCHAR * | getPackageVersion ()
| Returns the library version number. More...

## Protected Member Functions
int | readHeader (int sockIdx)
| Sub-routine to read and validate the Modbus/TCP header. More...
int | readPayload (int sockIdx, int result)
| Sub-routine to read and validate the Modbus/TCP payload. More...
void | terminateSocket (int sockIdx, DisconnectReason reason)
| Sub-routine to manage termination of connection. More...

## Protocol Configuration
int | setTimeout (long timeOut)
| Configures master activity time-out supervision. More...
long | getTimeout ()
| Returns the currently set master activity time-out value. More...
void | disableExceptionReplies ()
| Supress exception replies to be sent. More...
void | enableExceptionReplies ()
| Enables exception replies after they have been turned off. More...

## Transmission Statistic Functions
unsigned long | getTotalCounter ()
| Returns how often a message transfer has been executed. More...
void | resetTotalCounter ()
| Resets total message transfer counter.
unsigned long | getSuccessCounter ()
| Returns how often a message transfer was successful. More...
void | resetSuccessCounter ()
| Resets successful message transfer counter.

## TCP/IP Server Management Functions
int | isStarted ()
| Returns whether server has been started up. More...
int | setPort (unsigned short portNo)
| Sets the TCP port number to be used by the protocol. More...
void | installIpAddrValidationCallBack (int(*f)(const char *masterIpAddrSz))
void | installIpAddrValidationCallBack (int(*f)(void *userData, const char *masterIpAddrSz), void *userData)
| This function installs a callback handler for validating a master's IP address. More...
void | installMasterPollNotifyCallBack (int(*f)(const char *masterIpAddrSz))
void | installMasterPollNotifyCallBack (int(*f)(void *userData, const char *masterIpAddrSz), void *userData)
| This function installs a callback handler to be called everytime a master polls this slave and allows a forced closure of the master connection by returning 0. More...
unsigned short | getPort ()
| Returns the TCP port number used by the protocol. More...

## TCP/IP Server Management Functions
int | serverLoop ()
| Modbus slave server loop. More...

## Detailed Description

This class realises the Encapsulated Modbus RTU slave protocol.

It provides functions to start-up and to execute the server engine. This server engine can handle multiple master connections and is implemented as a single threaded TCP server. Upon receipt of a valid master query the server engine calls Data Provider methods to exchange data with the user application. For a more detailed description which Modbus data and control functions have been implemented in the server engine seesection Server Functions common to all Modbus Protocol Flavours.

See also
  Server Functions common to all Modbus Protocol Flavours, IP based Protocols
  MbusDataTableInterface, MbusRtuSlaveProtocol

## Constructor & Destructor Documentation

## ◆ MbusRtuOverTcpSlaveProtocol()

MbusRtuOverTcpSlaveProtocol | ( |  | ) |

Instantiates an Encapsulated Modbus RTU server object.

The association with a Data Provider is done after construction using the addDataTable method.

References MasterInfo::protocol, and MasterInfo::RTU_OVER_TCP.

## Member Function Documentation

## ◆ serverLoop()

int serverLoop | ( |  | ) |
| virtual

Modbus slave server loop.

This server loop must be called continuously. It must not be blocked. The server has to be started before calling the serverLoop() method.

In most cases the server loop is executed in an infinite loop in its own thread:

while (notTerminated) {
mbusProtocol.serverLoop();
}

Returns
  FTALK_SUCCESS on success or error code. See Error Management for a list of error codes.

Reimplemented from MbusTcpSlaveProtocol.

References FTALK_FILEDES_EXCEEDED, FTALK_IO_ERROR, FTALK_SUCCESS, and MAX_CONNECTIONS.

## ◆ startupServer() [1/2]

int startupServer | ( |  | ) |
| inline virtual inherited

Puts the Modbus server into operation.

The server accepts connections on any interface.

This function opens a TCP/IP socket, binds the configured TCP port to the Modbus/TCP protocol and initialises the server engine.

Note
  If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root privilege!

Returns
  FTALK_SUCCESS on success or error code. See Error Management for a list of error codes.

Reimplemented from MbusIpServerBase.

References MbusIpServerBase::startupServer().

## ◆ startupServer() [2/2]

int startupServer | ( | const char *const | hostName | ) |
| virtual inherited

Puts the Modbus server into operation.

The server accepts connections only on the interfaces which match the supplied hostname or IP address. This method allows to run different servers on multiple interfaces (so called multihomed servers).

This function opens a TCP/IP socket, binds the configured TCP port to the Modbus/TCP protocol and initialises the server engine.

Note
  If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root privilege!

Parameters

  hostName | String with IP address for a specific host interface or NULL if connections are accepted on any interface

Returns
  FTALK_SUCCESS on success or error code. See Error Management for a list of error codes.

Implements MbusIpServerBase.

References FTALK_LISTEN_FAILED, FTALK_OPEN_ERR, FTALK_PORT_ALREADY_BOUND, FTALK_PORT_NO_ACCESS, FTALK_PORT_NOT_AVAIL, FTALK_SUCCESS, FTALK_TCPIP_CONNECT_ERR, MAX_CONNECTIONS, and MbusTcpSlaveProtocol::shutdownServer().

## ◆ shutdownServer()

void shutdownServer | ( |  | ) |
| virtual inherited

Shuts down the Modbus server.

This function closes all TCP/IP connections to MODBUS/TCP masters and releases any system resources associated with the connections.

Reimplemented from MbusIpServerBase.

References MAX_CONNECTIONS, and MbusIpServerBase::shutdownServer().

## ◆ setConnectionTimeOut()

int setConnectionTimeOut | ( | long | masterTimeOut | ) |
| inherited

Configures connection time-out.

This allows to detect broken TCP connections. The TCP connection is closed if a valid request is not received within the configured time period. A value of 0 disables the time-out. Default value is 0 (disabled).

Remarks
  The time-out value is a minimum value only and the actual time may be longer. How precise it is followed depends on the operating system used, its scheduling priority and its system timer resolution.

Parameters

  masterTimeOut | Timeout value in ms (Range: 0 - 3600000), 0 disables time-out

Return values

  FTALK_SUCCESS | Success
  FTALK_ILLEGAL_ARGUMENT_ERROR | Argument out of range
  FTALK_ILLEGAL_STATE_ERROR | Server already running

References FTALK_ILLEGAL_ARGUMENT_ERROR, FTALK_ILLEGAL_STATE_ERROR, FTALK_SUCCESS, and MbusIpServerBase::isStarted().

## ◆ getConnectionTimeOut()

long getConnectionTimeOut | ( |  | ) |
| inline inherited

Returns the connection time-out setting.

Returns
  Timeout value in ms

## ◆ installMasterDisconnectCallBack()

void installMasterDisconnectCallBack | ( | void(*)(void *userData, const char *masterIpAddrSz, DisconnectReason reason) | f,
|  | void * | userData
| ) |  |
| inherited

This function installs a callback handler to be called in the event of a master disconnection.

A void pointer argument can be used to pass additional data, for example a reference to the data table object or the protocol instance.

This routine can be used to implement custom time-out mechanisms.

Parameters

  f | Callback function pointer
  userData | A void pointer which is passed as argument to the callback.

## ◆ readHeader()

int readHeader | ( | int | sockIdx | ) |
| protected inherited

Sub-routine to read and validate the Modbus/TCP header.

Parameters

  sockIdx | Index of socket within the connectionSocketArr

Returns
  -1 for error, 0 for graceful socket disconnect or payload data length

## ◆ readPayload()

int readPayload | ( | int | sockIdx,
|  | int | dataLen
| ) |  |
| protected inherited

Sub-routine to read and validate the Modbus/TCP payload.

Parameters

  sockIdx | Index of socket within the connectionSocketArr
  dataLen | Length of the payload (read from MPAB header)

Returns
  -1 for error, 0 for graceful socket disconnect

References MasterInfo::transactionId.

## ◆ terminateSocket()

void terminateSocket | ( | int | sockIdx,
|  | DisconnectReason | reason
| ) |  |
| protected inherited

Sub-routine to manage termination of connection.

Parameters

  sockIdx | Index of socket within the connectionSocketArr
  reason | A enum indicating why the termination occured

## ◆ isStarted()

int isStarted | ( |  | ) |
| virtual inherited

Returns whether server has been started up.

Return values

  true | = started
  false | = shutdown

Implements MbusSlaveServer.

## ◆ setPort()

int setPort | ( | unsigned short | portNo | ) |
| inherited

Sets the TCP port number to be used by the protocol.

Remarks
  Usually the port number remains unchanged and defaults to 502. In this case no call to this function is necessary. However if the port number has to be different from 502 this function must be called before starting the server with startupServer().

Note
  If the configured TCP port is below IPPORT_RESERVED (usually 1024), the process has to run with root or administrator privilege!
  This parameter must be set before starting the server in order to come into effect.

Parameters

  portNo | Port number the server shall listen on

Return values

  FTALK_SUCCESS | Success
  FTALK_ILLEGAL_STATE_ERROR | Server already running

References FTALK_ILLEGAL_STATE_ERROR, FTALK_SUCCESS, and MbusIpServerBase::isStarted().

## ◆ installIpAddrValidationCallBack()

void installIpAddrValidationCallBack | ( | int(*)(void *userData, const char *masterIpAddrSz) | f,
|  | void * | userData
| ) |  |
| inherited

This function installs a callback handler for validating a master's IP address.

Pass a pointer to a function with checks a master's IP address and either accepts or rejects a master's connection.

Parameters

  f | Callback function pointer
  userData | A void pointer which is passed as argument to the callback.

Returns
  Returns 1 to accept a connection or 0 to reject it.

## ◆ installMasterPollNotifyCallBack()

void installMasterPollNotifyCallBack | ( | int(*)(void *userData, const char *masterIpAddrSz) | f,
|  | void * | userData
| ) |  |
| inherited

This function installs a callback handler to be called everytime a master polls this slave and allows a forced closure of the master connection by returning 0.

This routine can be used to implement custom time-out mechanisms.

Parameters

  f | Callback function pointer
  userData | A void pointer which is passed as argument to the callback.

Returns
  Returns 1 to process the poll or 0 to reject and drop the connection.

## ◆ getPort()

unsigned short getPort | ( |  | ) |
| inline inherited

Returns the TCP port number used by the protocol.

Returns
  Port number used by the protocol

## ◆ addDataTable()

int addDataTable | ( | int | slaveAddr,
|  | MbusDataTableInterface * | dataTablePtr
| ) |  |
| inherited

Associates a protocol object with a Data Provider and a Modbus slave ID.

Parameters

  slaveAddr | Modbus slave address for server to listen on (-1 - 255). 0 is regarded as a valid value for a MODBUS/TCP server address. A value of -1 means the server disregards the slave address and listens to all slave addresses. 0 or -1 is only valid for MODBUS/TCP!
  dataTablePtr | Modbus data table pointer. Must point to a Data Provider object derived from the MbusDataTableInterface class. The Data Provider is the interface between your application data and the Modbus network.

Returns
  FTALK_SUCCESS on success or error code. See Error Management for a list of error codes.

References FTALK_ILLEGAL_ARGUMENT_ERROR, and FTALK_SUCCESS.

## ◆ getConnectionStatus()

int getConnectionStatus | ( |  | ) |
| inline inherited

Checks if a Modbus master is polling periodically.

Return values

  true | = A master is polling at a frequency higher than the master transmit time-out value
  false | = No master is polling within the time-out period

Note
  The master transmit time-out value must be set > 0 in order for this function to work.

## ◆ setTimeout()

int setTimeout | ( | long | timeOut | ) |
| inherited

Configures master activity time-out supervision.

The slave can monitor whether a master is actually polling or not. This function sets the activity time-out to the specified value. A value of 0 disables the time-out, which stops time-out notifications being sent to the Data Provider. Default value is 1000 ms.

Remarks
  The time-out value is a minimum value only and the actual time may be longer. How precise it is followed depends on the operating system used, its scheduling priority and its system timer resolution.

Note
  The time-out does not check whether a master is sending valid frames. The transmission of characters is sufficient to avoid the time-out.

Parameters

  timeOut | Timeout value in ms (Range: 0 - 100000), 0 disables time-out

Return values

  FTALK_SUCCESS | Success
  FTALK_ILLEGAL_ARGUMENT_ERROR | Argument out of range

References FTALK_ILLEGAL_ARGUMENT_ERROR, and FTALK_SUCCESS.

## ◆ getTimeout()

long getTimeout | ( |  | ) |
| inline inherited

Returns the currently set master activity time-out value.

Returns
  Timeout value in ms

## ◆ disableExceptionReplies()

void disableExceptionReplies | ( |  | ) |
| inherited

Supress exception replies to be sent.

With this option only positive replies are sent to the master. All failure replies are silently discarded. This option can be useful if redundant Modbus devices are used. In this scenario supressing the reply would trigger a swap-over of the redundant devices.

## ◆ enableExceptionReplies()

void enableExceptionReplies | ( |  | ) |
| inherited

Enables exception replies after they have been turned off.

Sending exception replies in case of slave failures is the normal mode of operation.

## ◆ getTotalCounter()

unsigned long getTotalCounter | ( |  | ) |
| inline inherited

Returns how often a message transfer has been executed.

Returns
  Counter value

## ◆ getSuccessCounter()

unsigned long getSuccessCounter | ( |  | ) |
| inline inherited

Returns how often a message transfer was successful.

Returns
  Counter value

## ◆ getPackageVersion()

const TCHAR * getPackageVersion | ( |  | ) |
| static inherited

Returns the library version number.

Returns
  Version string