• Libraries
  • Shop
  • Doc
  • Free Modbus
  • Support
  • Login
FieldTalk Modbus Slave C++ Library  Library version 2.10.0
  • Introduction
  • Chapters
  • Modules
  • Classes
  • Class List
  • Class Hierarchy
  • Class Members
Public Types | Public Member Functions | Static Public Member Functions | List of all members
MbusRtuSlaveProtocol Class Reference
Serial Protocols

This class realises the server-side of the Modbus RTU slave protocol. More...

Public Types

enum  { SER_DATABITS_7 = 7, SER_DATABITS_8 = 8 }
 
enum  { SER_STOPBITS_1 = 1, SER_STOPBITS_2 = 2 }
 
enum  { SER_PARITY_NONE = 0, SER_PARITY_EVEN = 2, SER_PARITY_ODD = 1 }
 

Public Member Functions

 MbusRtuSlaveProtocol ()
 Instantiates a Modbus RTU protocol server object. More...
 
int startupServer (const TCHAR *const portName, long baudRate, int dataBits, int stopBits, int parity)
 Puts the Modbus RTU server into operation and opens the associated serial port with specific port parameters. More...
 
int serverLoop ()
 Modbus slave server loop. More...
 
int setFrameTolerance (long frameToleranceMs)
 Configures the tolerance the RTU protocol engine should apply for the detection of inter-frame gaps. More...
 
void shutdownServer ()
 Shuts down the Modbus server. More...
 
int isStarted ()
 Returns whether server has been started up. More...
 
virtual int enableRs485Mode (int rtsDelay)
 Enables RS485 mode. 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.
 

Detailed Description

This class realises the server-side of the Modbus RTU slave protocol.

It provides functions to start-up and to execute the server engine which includes opening and closing of the serial port. 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 see section Server Functions common to all Modbus Protocol Flavours.

It is possible to instantiate multiple instances for establishing multiple connections on different serial ports, however they must be executed in separate threads.

See also
Server Functions common to all Modbus Protocol Flavours, Serial Protocols
MbusDataTableInterface, MbusAsciiSlaveProtocol, MbusTcpSlaveProtocol

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
inherited
Enumerator
SER_DATABITS_7 

7 data bits

SER_DATABITS_8 

8 data bits

◆ anonymous enum

anonymous enum
inherited
Enumerator
SER_STOPBITS_1 

1 stop bit

SER_STOPBITS_2 

2 stop bits

◆ anonymous enum

anonymous enum
inherited
Enumerator
SER_PARITY_NONE 

No parity.

SER_PARITY_EVEN 

Even parity.

SER_PARITY_ODD 

Odd parity.

Constructor & Destructor Documentation

◆ MbusRtuSlaveProtocol()

MbusRtuSlaveProtocol ( )

Instantiates a Modbus RTU protocol server object.

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

References MasterInfo::protocol, and MasterInfo::RTU.

Member Function Documentation

◆ startupServer()

int startupServer ( const TCHAR *const  portName,
long  baudRate,
int  dataBits,
int  stopBits,
int  parity 
)
virtual

Puts the Modbus RTU server into operation and opens the associated serial port with specific port parameters.

This function opens the serial port and initialises the server engine.

Parameters
portNameSerial port identifier (e.g. "COM1", "/dev/ser1" or "/dev/ttyS0")
baudRateThe port baudRate in bps (typically 1200 - 115200, maximum value depends on UART hardware)
dataBitsMust be SER_DATABITS_8 for RTU
stopBitsSER_STOPBITS_1: 1 stop bit, SER_STOPBITS_2: 2 stop bits
paritySER_PARITY_NONE: no parity, SER_PARITY_ODD: odd parity, SER_PARITY_EVEN: even parity
Note
The Modbus standard requires two stop bits if no parity is chosen. This library is not enforcing this but it is a recommended configuration.
Returns
FTALK_SUCCESS on success or error code. See Error Management for a list of error codes.

Reimplemented from MbusSerialServerBase.

References FTALK_ILLEGAL_ARGUMENT_ERROR, MbusSerialServerBase::SER_DATABITS_8, and MbusSerialServerBase::startupServer().

◆ 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 MbusSlaveServer.

References FTALK_IO_ERROR, and FTALK_SUCCESS.

◆ setFrameTolerance()

int setFrameTolerance ( long  frameToleranceMs)

Configures the tolerance the RTU protocol engine should apply for the detection of inter-frame gaps.

Modbus RTU uses inter-frame gaps (silence periods) to mark start and end of Modbus packets.

Warning
For strict Modbus compliance this should be set to 0.
Remarks
There are cases were longer silence periods may appear in the data stream due to the hardware used (USB dongles) or the device driver or the scheduling of the operating system. This value can then be increased to compensate. In a point-to-point communication system (eg RS-232) this value can be safley increased. However in a multi-point system were other slave devices are on the line, this value should be set to the lowest possible value in order to maintain interoperability with other Modbus equipment.
Note
A protocol must be closed in order to configure it.
Parameters
frameToleranceMsAdditional tolerance time for inter-frame silence detection in ms (Range: 0 - 20)
Return values
FTALK_SUCCESSSuccess
FTALK_ILLEGAL_ARGUMENT_ERRORArgument out of range

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

◆ shutdownServer()

void shutdownServer ( )
virtualinherited

Shuts down the Modbus server.

This function also closes any associated communication resources like serial ports or sockets.

Implements MbusSlaveServer.

◆ isStarted()

int isStarted ( )
virtualinherited

Returns whether server has been started up.

Return values
true= started
false= shutdown

Implements MbusSlaveServer.

◆ enableRs485Mode()

int enableRs485Mode ( int  rtsDelay)
virtualinherited

Enables RS485 mode.

In RS485 mode the RTS signal can be used to enable and disable the transmitter of a RS232/RS485 converter. The RTS signal is asserted before sending data. It is cleared after the transmit buffer has been emptied and in addition the specified delay time has elapsed. The delay time is necessary because even the transmit buffer is already empty, the UART's FIFO will still contain unsent characters.

Warning
The use of RTS controlled RS232/RS485 converters should be avoided if possible. It is difficult to determine the exact time when to switch off the transmitter with non real-time operating systems like Windows and Linux. If it is switched off to early characters might still sit in the FIFO or the transmit register of the UART and these characters will be lost. Hence the slave will not recognize the message. On the other hand if it is switched off too late then the slave's message is corrupted and the master will not recognize the message.
Remarks
The delay value is indicative only and not guaranteed to be maintained. How precise it is followed depends on the operating system used, it's scheduling priority and it's system timer resolution.
Note
This mode must be set before starting the server in order to come into effect.
Parameters
rtsDelayDelay time in ms (Range: 0 - 100000) which applies after the transmit buffer is empty. 0 disables this mode.
Return values
FTALK_SUCCESSSuccess
FTALK_ILLEGAL_ARGUMENT_ERRORArgument out of range
FTALK_ILLEGAL_STATE_ERRORProtocol is already open

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

◆ addDataTable()

int addDataTable ( int  slaveAddr,
MbusDataTableInterface *  dataTablePtr 
)
inherited

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

Parameters
slaveAddrModbus 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!
dataTablePtrModbus 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
timeOutTimeout value in ms (Range: 0 - 100000), 0 disables time-out
Return values
FTALK_SUCCESSSuccess
FTALK_ILLEGAL_ARGUMENT_ERRORArgument 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
  • MbusRtuSlaveProtocol
  • FieldTalk Modbus Slave C++ Library Library version 2.10.0
Speak to the Experts
Modbus Organization Member logo

We are member of the Modbus Organization, Inc.

Buy with Confidence
30-day money back guarantee All our FieldTalk web sales are backed by a 30-day Money Back Guarantee.
We Accept
Bank VISA MasterCard PayPal
Customer Info
  • Info & Contact
  • Customer Login
  • Terms of Service
  • Terms of Sale
  • Privacy Policy
© 2005-2025 proconX Pty Ltd. All rights reserved. proconX and FieldTalk are trademarks of proconX Pty Ltd.
All other trademarks and registered trademarks appearing on www.modbusdriver.com are the property of their respective owners.