MbusUdpSlaveProtocol Class Reference

This class realises a Modbus server using MODBUS over UDP protocol variant. More...

Public Member Functions
	MbusUdpSlaveProtocol ()
	Instantiates a MODBUS/UDP protocol 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	serverLoop ()
	Modbus slave server loop. 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...

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))
	This function installs a callback handler for validating a master's IP address. More...
void	installMasterPollNotifyCallBack (void(*f)(const char *masterIpAddrSz))
	This function installs a callback handler to be called everytime a master polls this slave. More...
unsigned short	getPort ()
	Returns the TCP port number used by the protocol. More...

Detailed Description

This class realises a Modbus server using MODBUS over UDP protocol variant.

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 UDP 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

Constructor & Destructor Documentation

MbusUdpSlaveProtocol()

MbusUdpSlaveProtocol

(

)

Instantiates a MODBUS/UDP protocol server object.

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

References MasterInfo::protocol, and MasterInfo::UDP.

Member Function Documentation

startupServer() [1/2]

int startupServer ( )

inlinevirtual

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

Puts the Modbus server into operation.

The server accepts communication 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 UDP listening socket, binds the configured TCP port to the Modbus/UDP 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. Multihomeing does not work for aliased IP addresses.

Returns

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

Implements MbusIpServerBase.

References FTALK_OPEN_ERR, FTALK_PORT_ALREADY_BOUND, FTALK_PORT_NO_ACCESS, FTALK_PORT_NOT_AVAIL, FTALK_SUCCESS, FTALK_TCPIP_CONNECT_ERR, and shutdownServer().

shutdownServer()

void shutdownServer ( )

virtual

Shuts down the Modbus server.

This function closes the UDP listeners and releases any system resources associated with the connections.

Reimplemented from MbusIpServerBase.

References MbusIpServerBase::shutdownServer().

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.

Implements MbusIpServerBase.

References FTALK_IO_ERROR, FTALK_SUCCESS, and MasterInfo::transactionId.

isStarted()

int isStarted ( )

virtualinherited

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(*)(const char *masterIpAddrSz)  f )

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

Returns

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

installMasterPollNotifyCallBack()

void installMasterPollNotifyCallBack ( void(*)(const char *masterIpAddrSz)  f )

inherited

This function installs a callback handler to be called everytime a master polls this slave.

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

Parameters

f	Callback function pointer

getPort()

unsigned short getPort ( )

inlineinherited

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 ( )

inlineinherited

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 ( )

inlineinherited

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 ( )

inlineinherited

Returns how often a message transfer has been executed.

Returns

Counter value

getSuccessCounter()

unsigned long getSuccessCounter ( )

inlineinherited

Returns how often a message transfer was successful.

Returns

Counter value

getPackageVersion()

const TCHAR * getPackageVersion ( )

staticinherited

Returns the library version number.

Returns

Version string