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

Macros

#define MBS_ASCII_ENABLED   ( 1 )
 If MODBUS ASCII support is enabled.
 
#define MBS_RTU_ENABLED   ( 1 )
 If MODBUS RTU support is enabled.
 
#define MBS_TCP_ENABLED   ( 0 )
 If MODBUS TCP support is enabled.
 
#define MBS_UDP_ENABLED   ( 0 )
 If MODBUS TCP support is enabled.
 
#define MBS_SERIAL_RTU_MAX_INSTANCES   ( 2 )
 Number of serial RTU instances supported.
 
#define MBS_SERIAL_ASCII_MAX_INSTANCES   ( 2 )
 Number of serial ASCII instances supported.
 
#define MBS_SERIAL_API_VERSION   ( 1 )
 Choose the API of the serial read/write callbacks. There are two different versions. More...
 
#define MBS_SERIAL_APIV2_RTU_TIMEOUT_MS   ( 20 )
 Serial timeout for RTU frame reception if the serial API version 2 is used. More...
 
#define MBS_SERIAL_DROPFRAME_TIMEOUT_CB   ( 0 )
 Normally a frame is processed within the frame receive callback. This function allows processing non local frames within the timer callback. More...
 
#define MBS_RTU_NEEDS_INTHDL   ( 1 )
 Makes the MODBUS handle available internal within the frame handlers.
 
#define MBS_SERIAL_APIV2_RTU_DYNAMIC_TIMEOUT_MS(ulBaudRate)   ( MBS_SERIAL_APIV2_RTU_TIMEOUT_MS )
 Serial timeout for RTU frame reception computed dynamically on the baudrate. Only usef in V2 serial API. More...
 
#define MBS_TCP_MAX_INSTANCES   ( 1 )
 Number of TCP instances supported.
 
#define MBS_UDP_MAX_INSTANCES   ( 1 )
 Number of TCP instances supported.
 
#define MBS_TCP_MAX_CLIENTS   ( 2 )
 Number of TCP clients allowed.
 
#define MBS_ASCII_TIMEOUT_SEC   ( 1 )
 The character timeout value for Modbus ASCII. More...
 
#define MBS_ASCII_BACKOF_TIME_MS   ( 5 )
 Backof time milliseconds for MODBUS SERIAL to introduce an additional delay after the frame has been received and before the reply is sent. More...
 
#define MBS_ENABLE_FULL_API_CHECKS   ( 1 )
 If the API should check arguments for errors. More...
 
#define MBS_NCUSTOM_FUNCTION_HANDLERS   ( 2 )
 Number of custom function handlers which are supported.
 
#define MBS_FUNC_READ_INPUT_REGISTERS_ENABLED   ( 1 )
 If the Read Input Registers function should be enabled.
 
#define MBS_FUNC_READ_HOLDING_REGISTERS_ENABLED   ( 1 )
 
#define MBS_FUNC_WRITE_SINGLE_REGISTER_ENABLED   ( 1 )
 If the Write Single Register function should be enabled.
 
#define MBS_FUNC_WRITE_MULTIPLE_REGISTERS_ENABLED   ( 1 )
 If the Read Input Registers function should be enabled.
 
#define MBS_FUNC_READWRITE_MULTIPLE_REGISTERS_ENABLED   ( 1 )
 If the Read/Write Multiple Registers function should be enabled.
 
#define MBS_FUNC_READ_DISCRETE_ENABLED   ( 1 )
 If the Read Discrete function should be enabled.
 
#define MBS_FUNC_READ_COILS_ENABLED   ( 1 )
 If the Read Coils function should be enabled.
 
#define MBS_FUNC_WRITE_SINGLE_COIL_ENABLED   ( 1 )
 If the Write Single Coil function should be enabled.
 
#define MBS_FUNC_WRITE_MULTIPLE_COILS_ENABLED   ( 1 )
 If the Write Multiple Coils function should be enabled.
 
#define MBS_FUNC_REPORT_SLAVE_ID_ENABLED   ( 0 )
 If the Report Slave ID function should be enabled.
 
#define MBS_RTU_WAITAFTERSEND_ENABLED   ( 0 )
 If the RTU layer should wait some time before enabling the receiver. More...
 
#define MBS_ASCII_WAITAFTERSEND_ENABLED   ( 0 )
 If the ASCII layer should wait some time before enabling the receiver. More...
 
#define MBS_ENABLE_STATISTICS_INTERFACE   ( 0 )
 Enable statistics interface.
 
#define MBS_ENABLE_PROT_ANALYZER_INTERFACE   ( 0 )
 Enable protocol analyzer.
 
#define MBS_ENABLE_SER_DIAG   ( 0 )
 Enable serial diagnosis functions.
 
#define MBS_REGISTER_CB_NEEDS_INT_HANDLE   ( 0 )
 If the MODBUS stack handle is passed to lower layers.
 
#define MBS_CALLBACK_ENABLE_CONTEXT   ( 0 )
 If the MODBUS handle should be passed to the callback functions.
 
#define MBP_ADVA_STARTUP_SHUTDOWN_ENABLED   ( 0 )
 If we want advanced startup/shutdown locking. More...
 
#define MBS_ENABLE_DEBUG_FACILITY   ( 0 )
 If debugging code should be built into the MODBUS stack.
 
#define MBS_SERIAL_RTU_DYNAMIC_WAITAFTERSEND_TIMEOUT_MS(ulBaudRate)   MB_INTDIV_CEIL( 1000UL * 11UL, ulBaudRate )
 The timeout to wait when wait after send timeouts are used in RTU transmission mode. More...
 
#define MBS_SERIAL_ASCII_DYNAMIC_WAITAFTERSEND_TIMEOUT_MS(ulBaudRate)   MB_INTDIV_CEIL( 1000UL * 10UL, ulBaudRate )
 The timeout to wait when wait after send timeouts are used in ASCII transmission mode. More...
 
#define MBS_TRACK_SLAVEADDRESS   ( 0 )
 If the slave ID of a request should be tracked. More...
 
#define MBS_ENABLE_GATEWAY_MODE   ( 0 )
 If the MODBUS slave should support gateway mode. More...
 
#define MBS_POLL_SINGLE_CYCLE   ( 0 )
 If enabled eMBSPoll internally executes any required poll cycles to fully process a pending frame. More...
 
#define MBS_TCP_IGNORE_UNIT_ID   ( 0 )
 Ignore MBAP unit ID field in TCP slave.
 
#define MBS_IS_EVALUATION_BUILD   ( 0 )
 If this is an evaluation build.
 

Detailed Description

Macro Definition Documentation

#define MBP_ADVA_STARTUP_SHUTDOWN_ENABLED   ( 0 )

If we want advanced startup/shutdown locking.

Advanced startup/shutdown locking might be necessary if the MODBUS stack should be embedded as a DLL and the porting layers needs specials hooks for startup, i.e. when the first instance is created and when the last instance is shut down. If for the first time an MODBUS serial or TCP init function is called the stack calls vMBPLibraryLoad( ). If the stack is shutdown the function calls vMBPLibraryUnload( ). Because the init and the close functions could be mixed due to threading a second locking primitive MBP_ENTER_CRTICIAL_INIT and MBP_EXIT_CRITICAL_INIT have to be provided. They default to empty macros but should be defined. for safe startup/shutdown behaviour is this can not be enforced by the application.

#define MBS_ASCII_BACKOF_TIME_MS   ( 5 )

Backof time milliseconds for MODBUS SERIAL to introduce an additional delay after the frame has been received and before the reply is sent.

Warning
Don't change the default unless you now exactly what you are doing.
Note
If a MODBUS slave has sent a respond the MASTER stack waits this configured time. This can be necessary because otherwise the MASTER could send a new query (depends on the application) but the slave is still not ready (For example it needs some time to switch its RS485 transceiver from write to read).
#define MBS_ASCII_TIMEOUT_SEC   ( 1 )

The character timeout value for Modbus ASCII.

The character timeout value is not fixed for Modbus ASCII and is therefore a configuration option. It should be set to the maximum expected delay time of the network.

#define MBS_ASCII_WAITAFTERSEND_ENABLED   ( 0 )

If the ASCII layer should wait some time before enabling the receiver.

This function is most useful for toggling the driver enable lines of RS485 transceivers if there is no support in the UART for doing this.

#define MBS_ENABLE_FULL_API_CHECKS   ( 1 )

If the API should check arguments for errors.

This has a small performance impact and one might not use this on very small systems.

#define MBS_ENABLE_GATEWAY_MODE   ( 0 )

If the MODBUS slave should support gateway mode.

If enabled the MODBUS slave processes all slave requests. This can be used to implement request forwarding to other devices.

#define MBS_FUNC_READ_HOLDING_REGISTERS_ENABLED   ( 1 )

brief If the Read Holding Registers function should be enabled.

#define MBS_POLL_SINGLE_CYCLE   ( 0 )

If enabled eMBSPoll internally executes any required poll cycles to fully process a pending frame.

This macro should be enabled if eMBSPoll is not called often enough. It makes sure that a frame is fully processed, i.e. parsed, callbacks executed and response sent.

#define MBS_RTU_WAITAFTERSEND_ENABLED   ( 0 )

If the RTU layer should wait some time before enabling the receiver.

This function is most useful for toggling the driver enable lines of RS485 transceivers if there is no support in the UART for doing this.

#define MBS_SERIAL_API_VERSION   ( 1 )

Choose the API of the serial read/write callbacks. There are two different versions.

  • API V1: This API uses the callback types pbMBPSerialTransmitterEmptyAPIV1CB and pvMBPSerialReceiverAPIV1CB. These type of callback are preferred because they can be used to implement the strict timeouts for MODBUS RTU. The drawback is that they can not be implemented on every platform (Windows, Linux, ...).
  • API V2: This API uses the callback types pbMBPSerialTransmitterEmptyAPIV2CB and pvMBPSerialReceiverAPIV2CB. Instead of single bytes this API can transfer multiple bytes at the same time. Using this API makes it impossible to implement the strict MODBUS timeouts but they have a better performance on some platforms and the porting layer is easier to implement.
#define MBS_SERIAL_APIV2_RTU_DYNAMIC_TIMEOUT_MS (   ulBaudRate)    ( MBS_SERIAL_APIV2_RTU_TIMEOUT_MS )

Serial timeout for RTU frame reception computed dynamically on the baudrate. Only usef in V2 serial API.

This function should return the timeout to use for end of frame transmission. You should set this to match the internal buffer size of your serial device. For example if you can buffer 32 bytes and the speed is 9600 you would return approx. 11/9600 * 32 + 5ms where the 5ms is an additional safety margin and 11/9600 is for 8 databits, 1 stopbit and parity.

#define MBS_SERIAL_APIV2_RTU_TIMEOUT_MS   ( 20 )

Serial timeout for RTU frame reception if the serial API version 2 is used.

Most operating systems using the API version 2 do not support very tight timeouts. Therefore we do not use the t3.5 timers in MODBUS RTU but use a higher timeout. The best value depend on the operating system and its realtime characteristics as well as the serial driver interface.

#define MBS_SERIAL_ASCII_DYNAMIC_WAITAFTERSEND_TIMEOUT_MS (   ulBaudRate)    MB_INTDIV_CEIL( 1000UL * 10UL, ulBaudRate )

The timeout to wait when wait after send timeouts are used in ASCII transmission mode.

This macro should be defined if the default wait after send timeouts are not useful. It is only used when either MBS_ASCII_WAITAFTERSEND_ENABLED is defined.

#define MBS_SERIAL_DROPFRAME_TIMEOUT_CB   ( 0 )

Normally a frame is processed within the frame receive callback. This function allows processing non local frames within the timer callback.

Normally frames are processed within the RTU callbacks. This can be problematic in case of RTU because it implies that the slave must handle all frames, even not then ones sent to itself. This function checks in the callback if the request is either a broadcast or for the slave. If not it drops it silently.

#define MBS_SERIAL_RTU_DYNAMIC_WAITAFTERSEND_TIMEOUT_MS (   ulBaudRate)    MB_INTDIV_CEIL( 1000UL * 11UL, ulBaudRate )

The timeout to wait when wait after send timeouts are used in RTU transmission mode.

This macro should be defined if the default wait after send timeouts are not useful. It is only used when either MBS_RTU_WAITAFTERSEND_ENABLED is defined.

#define MBS_TRACK_SLAVEADDRESS   ( 0 )

If the slave ID of a request should be tracked.

If enabled this macro allows the register callback functions to get the slave address for this MODBUS request.