API  2.2
TSmarT Software Library
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Slave

Modules

 Slave Configuration
 

Typedefs

typedef void * xMBSHandle
 A handle to a MODBUS slave instance.
 
typedef eMBException(* peMBSCoilCB )(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs, eMBSRegisterMode eRegMode) MB_CDECL_SUFFIX
 Callback function if a coil register is read or written by the protocol stack. More...
 
typedef eMBException(* peMBSDiscreteInputCB )(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs) MB_CDECL_SUFFIX
 Callback function if an discrete register is read by the protocol stack. More...
 
typedef eMBException(* peMBSRegisterInputCB )(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs) MB_CDECL_SUFFIX
 Callback function if an input register is read by the protocol stack. More...
 
typedef eMBException(* peMBSRegisterHoldingCB )(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs, eMBSRegisterMode eRegMode) MB_CDECL_SUFFIX
 Callback function if a holding register is read or written by the protocol stack. More...
 
typedef eMBException(* peMBSCustomFunctionCB )(UBYTE *pubMBPDU, USHORT *pusMBPDULength) MB_CDECL_SUFFIX
 Callback function for custom function codes.If a custom MODBUS function code should be implemented a callback function can be registered. The function is called by the MODBUS stack whenever such a function is encountered. More...
 
typedef eMBException(* peMBSGatewayCB )(UBYTE ubSlaveAddress, UBYTE *pubMBPDU, USHORT *pusMBPDULength) MB_CDECL_SUFFIX
 Callback function for gateway mode. More...
 
typedef eMBException(* peMBSSerialDiagCB )(eMBSSerialDiagQueryType_t eQueryType, UBYTE *pubMBPDU, USHORT *pusMBPDULength, const USHORT usMBPDULengthMax) MB_CDECL_SUFFIX
 This function is used by the serial diagnosis function codes to request device specific information. More...
 

Enumerations

enum  eMBSRegisterMode { MBS_REGISTER_WRITE, MBS_REGISTER_READ }
 If a register is written or read by the stack. More...
 
enum  eMBSSerialDiagQueryType_t
 Objects used in the peMBSSerialDiagCB callbacks. More...
 

Functions

eMBErrorCode eMBSGetRequestSlaveAddress (xMBSHandle xHdl, UBYTE *pubAddress)
 Retrieve the current slave address for this request. More...
 
eMBErrorCode eMBSGetStatistics (xMBSHandle xHdl, xMBStat *pxMBSCurrentStat)
 Retrieve the current slave statistics. More...
 
eMBErrorCode eMBSResetStatistics (xMBSHandle xHdl)
 Clears the current statistic counters. More...
 
eMBErrorCode eMBSRegisterProtAnalyzer (xMBSHandle xHdl, void *pvCtxArg, pvMBAnalyzerCallbackCB pvMBAnalyzerCallbackFN)
 Register an protocol analyzer. More...
 
eMBErrorCode eMBSRegisterFunctionCB (xMBSHandle xHdl, UBYTE ubFuncIdx, peMBSCustomFunctionCB peFuncCB)
 Register a new custom function for MODBUS function code ubFuncIdx. More...
 
eMBErrorCode eMBSRegisterCoilCB (xMBSHandle xHdl, peMBSCoilCB peMBSCoilsCB)
 Register a function callback for coils. More...
 
eMBErrorCode eMBSRegisterDiscreteCB (xMBSHandle xHdl, peMBSDiscreteInputCB peDiscInputCB)
 Register a function callback for discrete inputs. More...
 
eMBErrorCode eMBSRegisterInputCB (xMBSHandle xHdl, peMBSRegisterInputCB peRegInputCB)
 Register a function callback for input registers. More...
 
eMBErrorCode eMBSRegisterHoldingCB (xMBSHandle xHdl, peMBSRegisterHoldingCB peRegHoldingCB)
 Register a function callback for holding registers. More...
 
eMBErrorCode eMBSRegisterSerialDiagCB (xMBSHandle xHdl, peMBSSerialDiagCB peMBSSerDiagCB)
 Register function callback for gateway mode. More...
 
eMBErrorCode eMBSRegisterGatewayCB (xMBSHandle xHdl, peMBSGatewayCB peGatewayCB)
 Register function callback for serial diagnosis functions. More...
 
eMBErrorCode eMBSClose (xMBSHandle xHdl)
 Close the stack. More...
 
eMBErrorCode eMBSPoll (xMBSHandle xHdl)
 The main polling loop of the MODBUS stack. More...
 
eMBErrorCode eMBSSerialInit (xMBSHandle *pxHdl, eMBSerialMode eMode, UBYTE ubSlaveAddress, UBYTE ubPort, ULONG ulBaudRate, eMBSerialParity eParity)
 Create a new instances for a serial MODBUS slave instance using either ASCII or RTU transmission mode. More...
 
eMBErrorCode eMBSSerialInitExt (xMBSHandle *pxHdl, eMBSerialMode eMode, UBYTE ubSlaveAddress, UBYTE ubPort, ULONG ulBaudRate, eMBSerialParity eParity, UCHAR ucStopBits)
 Create a new instances for a serial MODBUS slave instance using either ASCII or RTU transmission mode. More...
 
eMBErrorCode eMBSTCPInit (xMBSHandle *pxHdl, CHAR *pcBindAddress, USHORT usTCPPort)
 Create a new MODBUS TCP slave instance. More...
 
eMBErrorCode eMBSTCPSetGatewayMode (xMBSHandle xHdl, BOOL bEnable)
 Enable gateway mode where the MODBUS TCP slave answers on all addresses. More...
 
eMBErrorCode eMBSUDPInit (xMBSHandle *pxHdl, CHAR *pcBindAddress, USHORT usUDPPort)
 Create a new MODBUS UDP slave instance. More...
 

Detailed Description

Typedef Documentation

typedef eMBException( * peMBSCoilCB)(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs, eMBSRegisterMode eRegMode) MB_CDECL_SUFFIX

Callback function if a coil register is read or written by the protocol stack.

The callback may read or write up to 2000 coils where the first coil is address by the parameter usAddress. If the coils are read by the protocol stack the first coil should be written to the buffer pubRegBuffer where the first 8 coils should be written to pubRegBuffer[0], the second 8 coils to pubRegBuffer[1], ... If the total amount is not a multiple of 8 the missing coils should be set to zero.
If the coils are written by the protocol stack, which is indicated by the argument eRegMode set to eMBSRegisterMode::MBS_REGISTER_WRITE , then the callback should update its coils with the values supplied in pubRegBuffer. The enconding is the same as above.

An example of Coil access callback:

* eMBException eMyRegCoilCB(UBYTE * pubRegBuffer, USHORT usAddress, USHORT usNRegs, eMBSRegisterMode eRegMode) {
* USHORT i;
* // Map address to pin
* for (i=0 ; i<usNRegs ; i++) {
* switch (usAddress) {
* case 0x0000:
* if (eRegMode == MBS_REGISTER_WRITE) {
* // Read new coil value from pubRegBuffer and write to coil at address 0x0000
* else {
* // Read coil at address 0x0000 and write to pubRegBuffer
* }
* break;
* case ...
* break;
* default:
* return MB_PDU_EX_ILLEGAL_DATA_ADDRESS;
* }
* }
* return MB_PDU_EX_NONE;
* }
*
Parameters
pubRegBufferIf the values are read by the stack the callback should update the buffer. Otherwise the callback can read the new status of the coils from this buffer.
usAddressAddress of first coil.
usNRegsNumber of coils.
eRegModeIf set to eMBSRegisterMode::MBS_REGISTER_READ the coils are read by the protocol stack. In case of eMBSRegisterMode::MBS_REGISTER_WRITE the protocol stack needs to know the current value of the coil register.
Returns
If the callback returns eMBException::MB_PDU_EX_NONE a response is sent back to the master. Otherwise an appropriate exception frame is generated.
typedef eMBException( * peMBSCustomFunctionCB)(UBYTE *pubMBPDU, USHORT *pusMBPDULength) MB_CDECL_SUFFIX

Callback function for custom function codes.If a custom MODBUS function code should be implemented a callback function can be registered. The function is called by the MODBUS stack whenever such a function is encountered.

Parameters
pubMBPDUThe MODBUS request sent by the MODBUS master which is pusMBPDULength bytes long. The response should be written into the same buffer and the length of the response should be written to pubMBPDULength. It must not exceed the size of 243 bytes.
pubMBPDULenLength of the MODBUS PDU.
Returns
If the function returns eMBException::MB_PDU_EX_NONE a response is sent to the master with a length of pusMBPDULength and the contents of pubMBPDU. Otherwise an exception frame is generated.
typedef eMBException( * peMBSDiscreteInputCB)(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs) MB_CDECL_SUFFIX

Callback function if an discrete register is read by the protocol stack.

The callback may request up to 2000 discrete inputs where the first input to be returned is usAddress. The status of the discrete inputs should be written to the buffer pubRegBuffer where the first 8 registers should be written to pubRegBuffer[0], the second 8 registers to pubRegBuffer[1]. If the total amount is not a multiple of 8 missing values should be set to zero.

An example of Discrete input access callback:

* eMBException eMyDiscreteInputCB(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs) {
* USHORT i;
* // Map address to pin
* for (i=0 ; i<usNRegs ; i++) {
* switch (usAddress) {
* case 0x0000:
* // Read input at address 0x0000 and write to pubRegBuffer
* break;
* case ...
* break;
* default:
* return MB_PDU_EX_ILLEGAL_DATA_ADDRESS;
* }
* }
* return MB_PDU_EX_NONE;
* }
*
Parameters
pubRegBufferBuffer where the status of the registers should be written to.
usAddressFirst discrete input to be returned.
usNRegsNumber of registers requested.
Returns
If the callback returns eMBException::MB_PDU_EX_NONE a response is sent back to the master. Otherwise an appropriate exception frame is generated.
typedef eMBException( * peMBSGatewayCB)(UBYTE ubSlaveAddress, UBYTE *pubMBPDU, USHORT *pusMBPDULength) MB_CDECL_SUFFIX

Callback function for gateway mode.

The argument pubMBPDU contains the complete MODBUS protocol data unit.

An example of Gateway Callback function, assuming there are two tasks (one for the TCP part and the other for the RTU part):

* eMBException eMyGatewayCB(UBYTE ubSlaveAddress, UBYTE * pubMBPDU, USHORT * pusMBPDULength) {
* xMsgSlaveRequest xSlaveRequest;
* xMsgSlaveResponse xSlaveResponse;
* eMBException eException = MB_PDU_EX_NONE;
* // Get the request parameters
* xSlaveRequest.ubSlaveAddress = ubSlaveAddress;
* xSlaveRequest.pubMBPDU = pubMBPDU;
* xSlaveRequest.pusMBPDULength = pusMBPDULength;
* // Send to RTOS queue
* if (pdTRUE == xQueueSend(xGatewayRequestQueueHdl, &xSlaveRequest, portMAX_DELAY)) {
* // Wait answer from queue
* if (pdTRUE == xQueueReceive(xGatewayResponseQueueHdl, &xSlaveResponse, portMAX_DELAY)) {
* if (MB_ENOERR == xSlaveResponse.eStatus) {
* eException = MB_PDU_EX_NONE;
* }
* else {
* eException = eMBErrorcodeToException(xSlaveResponse.eStatus);
* }
* }
* else {
* eException = MB_PDU_EX_GATEWAY_PATH_UNAVAILABLE;
* }
* }
* else {
* eException = MB_PDU_EX_SLAVE_BUSY;
* }
* return eException;
* }
*
Parameters
ubSlaveAddressThe slave address for which the request was intended.
pubMBPDUThe MODBUS request sent by the MODBUS master which is pusMBPDULength bytes long. The response should be written into the same buffer and the length of the response should be written to pubMBPDULength. It must not exceed the size of 243 bytes.
pubMBPDULenLength of the MODBUS PDU.
typedef eMBException( * peMBSRegisterHoldingCB)(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs, eMBSRegisterMode eRegMode) MB_CDECL_SUFFIX

Callback function if a holding register is read or written by the protocol stack.

If the MODBUS slave stack needs to now the value of holding registers it executes this callback with eRegisterMode = MBS_REGISTER_READ. The callback function should then store the current values of the registers starting at usAddress up to usAddress + usNRegs (not including the last one) into the buffer pubRegBuffer. The 16 bit registers values must be stored in big endian format.
If the values should be updated the function is called with eRegisterMode set to MBS_REGISTER_WRITE. The register values are passed in the buffer pubRegBuffer and it is the applications responsibility to use these values. The first register is stored in pubRegBuffer[0] - pubRegBuffer[1] where the high byte comes first (big endian).

An example of Coil access callback:

* eMBException eMyRegHoldingCB(UBYTE * pubRegBuffer, USHORT usAddress, USHORT usNRegs, eMBSRegisterMode eRegMode) {
* USHORT i;
* // Map address to registers
* for (i=0 ; i<usNRegs ; i++) {
* switch (usAddress) {
* case 0x0000:
* if (eRegMode == MBS_REGISTER_WRITE) {
* // Read new register value from pubRegBuffer and write to register at address 0x0000
* else {
* // Read register at address 0x0000 and write to pubRegBuffer
* }
* break;
* case ...
* break;
* default:
* return MB_PDU_EX_ILLEGAL_DATA_ADDRESS;
* }
* }
* return MB_PDU_EX_NONE;
* }
*
Parameters
pubRegBufferA pointer to an internal buffer. If registers are read then exactly 2 * usNRegs bytes must be written to this buffer. If registers are written the application can read up to 2 * usNRegs from this buffer.
usAddressThe address of the first register which should be returned. Registers start at zero.
usNRegsThe number of registers to read.
eRegModeIf the registers are read or written.
Returns
If the callback returns eMBException::MB_PDU_EX_NONE a response is sent back to the master. Otherwise an appropriate exception frame is generated.
typedef eMBException( * peMBSRegisterInputCB)(UBYTE *pubRegBuffer, USHORT usAddress, USHORT usNRegs) MB_CDECL_SUFFIX

Callback function if an input register is read by the protocol stack.

If the MODBUS slave stack needs to now the values of input registers this callback function must store the current value of the registers starting atusAddress to usAddress + usNRegs (not including the last one) into the buffer pubRegBuffer. The 16 bit registers values must be stored in big endian format.

An example of Discrete input access callback:

* eMBException eMyRegInputCB(UBYTE * pubRegBuffer, USHORT usAddress, USHORT usNRegs) {
* USHORT i;
* // Map address to pin
* for (i=0 ; i<usNRegs ; i++) {
* switch (usAddress) {
* case 0x0000:
* // Read register at address 0x0000 and write to pubRegBuffer
* break;
* case ...
* break;
* default:
* return MB_PDU_EX_ILLEGAL_DATA_ADDRESS;
* }
* }
* return MB_PDU_EX_NONE;
* }
*
Parameters
pubRegBufferA pointer to an internal buffer. Exactly 2 * usNRegs bytes must be written to this buffer.
usAddressThe address of the first register which should be returned. Registers start at zero.
usNRegsThe number of registers to read.
Returns
If the callback returns eMBException::MB_PDU_EX_NONE a response is sent back to the master. Otherwise an appropriate exception frame is generated.
typedef eMBException( * peMBSSerialDiagCB)(eMBSSerialDiagQueryType_t eQueryType, UBYTE *pubMBPDU, USHORT *pusMBPDULength, const USHORT usMBPDULengthMax) MB_CDECL_SUFFIX

This function is used by the serial diagnosis function codes to request device specific information.

This function is used for the MODBUS requests

  • Report Slave ID
  • Read Device Identification

When ever an object is need the callback function is called. It should then store the request data in the buffer pointed to by pubMBPDU. The number of bytes stored should be stored in pusMBPDULength. The function is not allowed to write more than usMBPDULengthMax bytes.

Parameters
eQueryTypeType of object requested.
pubMBPDUBuffer where object should be stored. If called with NULL the function should only check if it has an object for this type and return MB_PDU_EX_NONE if it has and MB_PDU_EX_ILLEGAL_DATA_ADDRESS if not.
pusMBPDULengthBytes written to the buffer.
usMBPDULengthMaxMaximum number of bytes which can be stored in this buffer.
Returns
eMBException::MB_PDU_EX_NONE if request information was stored. eMBException::MB_PDU_EX_ILLEGAL_DATA_ADDRESS if no such object exists. eMBException::MB_PDU_EX_ILLEGAL_DATA_VALUE if usMBPDULengthMax is not large enough to hold the data.

Enumeration Type Documentation

If a register is written or read by the stack.

Enumerator
MBS_REGISTER_WRITE 

The application values should be updated from the values passed to the callback function.

MBS_REGISTER_READ 

The application should store the current register values into the buffer passed to the callback function.

Objects used in the peMBSSerialDiagCB callbacks.

These codes are used to identifiy different objects used for the report slave id and device identificiation calls.

Function Documentation

eMBErrorCode eMBSClose ( xMBSHandle  xHdl)

Close the stack.

Shutdown the slave stack. This function waits until all pending MODBUS requests have been answered and then operation is stop. All resources are returned to the porting layer.

Parameters
xHdlA handle for a MODBUS slave instances.
Returns
eMBErrorCode::MB_ENOERR if the stack has been shut down.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSGetRequestSlaveAddress ( xMBSHandle  xHdl,
UBYTE *  pubAddress 
)

Retrieve the current slave address for this request.

This function can only be called during a register callback. It then returns the slave address for this request in pubAddress.

Parameters
xHdlA valid MODBUS slave handle.
pubAddressOn return slave address is stored in this variable.
Returns
eMBErrorCode::MB_EINVAL if called not within a callback. Otherwise eMBErrorCode::MB_ENOERR;
eMBErrorCode eMBSGetStatistics ( xMBSHandle  xHdl,
xMBStat pxMBSCurrentStat 
)

Retrieve the current slave statistics.

This function populates the argument pxMBSCurrentStat with the current internal counters.

Parameters
xHdlA valid MODBUS slave handle.
pxMBSCurrentStatA pointer to an (potentially unitialized) xMBStat datastructure. When the return value is eMBErrorCode::MB_ENOERR this data structure holds a copy of the internal counters.
Returns
eMBErrorCode::MB_ENOERR if successful. In case of an invalid argument the function returns eMBErrorCode::MB_EINVAL.
eMBErrorCode eMBSPoll ( xMBSHandle  xHdl)

The main polling loop of the MODBUS stack.

This function must be called periodically. The timer interval required is given by the application but a good starting point is somewhere around 50ms. Internally the function checks if any events have happened and if yes processes them.

Note
Most customers do not need to implement the handling of eMBErrorCode::MB_EILLSTATE. But for example if a PPP connection which might break is used a possible fallback would shut down the stack, reopen the connection and then start the stack again.
Parameters
xHdlThe handle to poll.
Returns
If the handle is not valid the function returns eMBErrorCode::MB_EINVAL. If an internal error occurred in the porting layer the function returns eMBErrorCode::MB_EILLSTATE and this protocol instance should be closed. Otherwise the function returns eMBErrorCode::MB_ENOERR.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSRegisterCoilCB ( xMBSHandle  xHdl,
peMBSCoilCB  peMBSCoilsCB 
)

Register a function callback for coils.

Parameters
xHdlA handle to a MODBUS slave instance.
peMBSCoilsCBA pointer to a function. This function is called whenever a coil is read or written. Use NULL to remove the previous callback.
Returns
eMBErrorCode::MB_ENOERR if the input callback has been set or removed. eMBErrorCode::MB_EINVAL if the handle is not valid.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSRegisterDiscreteCB ( xMBSHandle  xHdl,
peMBSDiscreteInputCB  peDiscInputCB 
)

Register a function callback for discrete inputs.

Parameters
xHdlA handle to a MODBUS slave instance.
peDiscInputCBA pointer to a function. This function is called whenever a discrete register is read. Use NULL to remove the previous callback.
Returns
eMBErrorCode::MB_ENOERR if the input callback has been set or removed. eMBErrorCode::MB_EINVAL if the handle is not valid.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSRegisterFunctionCB ( xMBSHandle  xHdl,
UBYTE  ubFuncIdx,
peMBSCustomFunctionCB  peFuncCB 
)

Register a new custom function for MODBUS function code ubFuncIdx.

Note
Custom registered functions have precedence over internal function handlers. Therefore it is possible to implement your own function for handling input, holding, discrete and coil registers.
Parameters
xHdlA handle to a MODBUS slave instance.
ubFuncIdxMODBUS function code for which the handle should be registered.
peFuncCBA callback function which is called by the stack whenever such a function is processed. Use NULL to remove a previous callback.
Returns
eMBErrorCode::MB_ENOERR if the function code has been registered or removed. eMBErrorCode::MB_EINVAL if the handle is invalid or the function code is not within the allowed range of 1 - 127.
eMBErrorCode eMBSRegisterGatewayCB ( xMBSHandle  xHdl,
peMBSGatewayCB  peGatewayCB 
)

Register function callback for serial diagnosis functions.

Parameters
xHdlA handle to a MODBUS slave instance.
peGatewayCBA pointer to a function. This function is called when the gateway mode is enabled and a new frame is received which has a different slave address than this stack instance. In TCP mode these are all slave addresses different from 0 and 255. In RTU mode these are all slave addresses different from the slave address set by eMBSSerialInit.
Returns
eMBErrorCode::MB_ENOERR if the input callback has been set or removed. eMBErrorCode::MB_EINVAL if the handle is not valid.
eMBErrorCode eMBSRegisterHoldingCB ( xMBSHandle  xHdl,
peMBSRegisterHoldingCB  peRegHoldingCB 
)

Register a function callback for holding registers.

Parameters
xHdlA handle to a MODBUS slave instance.
peRegHoldingCBA pointer to a function. This function is called whenever the value of a holding register is written or read. Use NULL to remove a previous callback.
Returns
eMBErrorCode::MB_ENOERR if the input callback has been set or removed. eMBErrorCode::MB_EINVAL if the handle is not valid.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSRegisterInputCB ( xMBSHandle  xHdl,
peMBSRegisterInputCB  peRegInputCB 
)

Register a function callback for input registers.

Parameters
xHdlA handle to a MODBUS slave instance.
peRegInputCBA pointer to a function. This function is called whenever the value of an input register is required. Use NULL to remove a previous callback.
Returns
eMBErrorCode::MB_ENOERR if the input callback has been set or removed. eMBErrorCode::MB_EINVAL if the handle is not valid.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSRegisterProtAnalyzer ( xMBSHandle  xHdl,
void *  pvCtxArg,
pvMBAnalyzerCallbackCB  pvMBAnalyzerCallbackFN 
)

Register an protocol analyzer.

If a protocol analyzer has been registered a callback is made whenever a frame has been sent or received.

Parameters
xHdlA valid MODBUS slave handle.
pvMBAnalyzerCallbackFNA valid pointer to a callback handler or NULL if the analyzer should be removed.
pvCtxArgA user defined context. Can be NULL.
Returns
eMBErrorCode::MB_ENOERR if the analyzer has been added or removed. eMBErrorCode::MB_EINVAL in case of an invalid MODBUS handle.
eMBErrorCode eMBSRegisterSerialDiagCB ( xMBSHandle  xHdl,
peMBSSerialDiagCB  peMBSSerDiagCB 
)

Register function callback for gateway mode.

Parameters
xHdlA handle to a MODBUS slave instance.
peMBSSerDiagCBA pointer to a function. This function is called when the stack requests some diagnosis information which can only be supplied by the application (For example vendor information for report slave id).
Returns
eMBErrorCode::MB_ENOERR if the input callback has been set or removed. eMBErrorCode::MB_EINVAL if the handle is not valid.
eMBErrorCode eMBSResetStatistics ( xMBSHandle  xHdl)

Clears the current statistic counters.

Parameters
xHdlA valid MODBUS slave handle.
Returns
eMBErrorCode::MB_ENOERR if successful. In case of an invalid argument the function returns eMBErrorCode::MB_EINVAL.
eMBErrorCode eMBSSerialInit ( xMBSHandle pxHdl,
eMBSerialMode  eMode,
UBYTE  ubSlaveAddress,
UBYTE  ubPort,
ULONG  ulBaudRate,
eMBSerialParity  eParity 
)

Create a new instances for a serial MODBUS slave instance using either ASCII or RTU transmission mode.

Note that after the stack has been created function pointers for input, holding, coil and discrete registers have to be provided. They can be set by calling any of the functions:

  • eMBSRegisterHoldingCB
  • eMBSRegisterInputCB
  • eMBSRegisterDiscreteCB
  • eMBSRegisterCoilCB
Note
In RTU mode 11 bits are used for each data byte. The coding system is 8bit binary.
  • 1 start bit.
  • 8 data bits with LSB sent first.
  • 1 bit for parity (Even, Odd)
  • 1 or 2 stop bits (Two stopbits if no parity is used).

In ASCII mode 10 bits are used. The coding system uses the hexadecimal ASCII characters 0-8 and A-F. One hexadecimal characters contains 4-bits of data.

  • 1 start bit
  • 7 data bits with LSB sent first.
  • 1 bit for parity (Even, Odd)
  • 1 or 2 stop bits (Two stopbits if no parity is used).
Parameters
pxHdlA pointer to a MODBUS handle. If the function returns eMBErrorCode::MB_ENOERR the handle is updated to hold a new and valid slave handle. This handle should never be modified by the user.
eModeThe serial transmission mode to use. Either MB_RTU or MB_ASCII.
ubSlaveAddressThe slave address. Only frames sent to this address or to the broadcast address are handled. Valid slave addresses are in the range 1 - 247.
ubPortThe serial port to use. The meaning of this value depends on the porting layer.
ulBaudRateThe baudrate. For example 38400.
eParityThe parity to use.
Returns
eMBErrorCode::MB_ENOERR if a new SLAVE has been created. Otherwise one of the following error codes is returned.
  • eMBErrorCode::MB_EINVAL If any of the arguments are not valid.
  • eMBErrorCode::MB_EPORTERR If the porting layer returned an error.
Examples:
modbus_slave_rtu.c.
eMBErrorCode eMBSSerialInitExt ( xMBSHandle pxHdl,
eMBSerialMode  eMode,
UBYTE  ubSlaveAddress,
UBYTE  ubPort,
ULONG  ulBaudRate,
eMBSerialParity  eParity,
UCHAR  ucStopBits 
)

Create a new instances for a serial MODBUS slave instance using either ASCII or RTU transmission mode.

Parameters
pxHdlA pointer to a MODBUS handle. If the function returns eMBErrorCode::MB_ENOERR the handle is updated to hold a new and valid slave handle. This handle should never be modified by the user.
eModeThe serial transmission mode to use. Either MB_RTU or MB_ASCII.
ubSlaveAddressThe slave address. Only frames sent to this address or to the broadcast address are handled. Valid slave addresses are in the range 1 - 247.
ubPortThe serial port to use. The meaning of this value depends on the porting layer.
ulBaudRateThe baudrate. For example 38400.
ucStopBitsNumber of stop bits to use.
eParityThe parity to use.
Returns
eMBErrorCode::MB_ENOERR if a new SLAVE has been created. Otherwise one of the following error codes is returned.
  • eMBErrorCode::MB_EINVAL If any of the arguments are not valid.
  • eMBErrorCode::MB_EPORTERR If the porting layer returned an error. Identical to eMBSSerialInit but allows to set the number of stop bits.
eMBErrorCode eMBSTCPInit ( xMBSHandle pxHdl,
CHAR *  pcBindAddress,
USHORT  usTCPPort 
)

Create a new MODBUS TCP slave instance.

This function tries to create a new MODBUS TCP slave listening on the address pcBindAddress and on port usTCPPort.

Parameters
pxHdlA pointer to a handle. On return this handle is updated to point to a valid internal handle. The handle should never be modified by the user.
pcBindAddressAddress to bind to. For example "0.0.0.0".
usTCPPortThe TCP port to bind to. Default port should be 502.
Returns
eMBErrorCode::MB_ENOERR if a new SLAVE has been created. Otherwise one of the following error codes is returned.
  • eMBErrorCode::MB_EINVAL If any of the arguments are not valid.
  • eMBErrorCode::MB_EPORTERR If the porting layer returned an error.
eMBErrorCode eMBSTCPSetGatewayMode ( xMBSHandle  xHdl,
BOOL  bEnable 
)

Enable gateway mode where the MODBUS TCP slave answers on all addresses.

Addresses 0 and 255 are MODBUS requests targeted to this slave. Other addresses from 1 - 247 should be forwarded to the appropriate clients.

eMBErrorCode eMBSUDPInit ( xMBSHandle pxHdl,
CHAR *  pcBindAddress,
USHORT  usUDPPort 
)

Create a new MODBUS UDP slave instance.

This function tries to create a new MODBUS UDP slave listening on the address pcBindAddress and on port usUDPPort.

Parameters
pxHdlA pointer to a handle. On return this handle is updated to point to a valid internal handle. The handle should never be modified by the user.
pcBindAddressAddress to bind to. For example "0.0.0.0".
usUDPPortThe UDP port to bind to. Default port should be 502.
Returns
eMBErrorCode::MB_ENOERR if a new SLAVE has been created. Otherwise one of the following error codes is returned.
  • eMBErrorCode::MB_EINVAL If any of the arguments are not valid.
  • eMBErrorCode::MB_EPORTERR If the porting layer returned an error.