MODBUS Configuration
[MODBUS Master]

Detailed Description

Most modules in the protocol stack are completly optional and can be excluded. This is specially important if target resources are very small and program memory space should be saved.

If the default options are not suitable the file mbmconfig.h should be created. This file can then be used to customization.

Define Documentation

#define MBM_ASCII_BACKOF_TIME_MS ( 2 )

Backof time milliseconds for MODBUS ASCII 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 read (For example it needs some time to switch its RS485 transceiver from write to read).

#define MBM_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 MBM_ASCII_WAITAFTERSEND_ENABLED ( 0 )

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

#define MBM_DEFAULT_RESPONSE_TIMEOUT ( 500 )

Default respose timeout.

#define MBM_ENABLE_DEBUG_FACILITY ( 0 )

If debugging code should be built into the MODBUS stack.

#define MBM_ENABLE_DEBUG_FACILITY_HEAVY ( 0 )

If heavy (memory intensive) debugging code should be built into the MODBUS stack.

#define MBM_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 MBM_ENABLE_PROT_ANALYZER_INTERFACE ( 0 )

If the protocol analyzer should be enabled.
The protocol analyser allows the user to supply to custom callbacks which are called by the stack whenever a new frame is sent or received. These protocol callbacks are maded from the different implementation layers (RTU, ASCII or TCP) and include the MODBUS PDU as well as the encapsulating elements.

#define MBM_ENABLE_STATISTICS_INTERFACE ( 0 )

If the statistics interface should be enabled.
The statistics interface allows to gather additional statistics from the MODBUS stacks. This includes

Number of received frames (valid)
Number of sent frames
Timeout errors
Number of checksum errors
Total number of bytes sent
Total number of bytes received.

#define MBM_FUNC_RD_FILES_ENABLED ( 1 )

If the Read File Record function should be enabled.

#define MBM_FUNC_RD_HOLDING_ENABLED ( 1 )

If the Read Holding Registers function should be enabled.

#define MBM_FUNC_RD_INPUT_REGS_ENABLED ( 1 )

If the Read Input Registers function should be enabled.

#define MBM_FUNC_RDWR_MUL_REGS_ENABLED ( 1 )

If the Read/Write Multiple Registers function should be enabled.

#define MBM_FUNC_READ_COILS_ENABLED ( 1 )

If the Read Coils function should be enabled.

#define MBM_FUNC_READ_DISC_INPUTS_ENABLED ( 1 )

If the Read Discrete Inputs function should be enabled.

#define MBM_FUNC_READWRITE_RAWPDU_ENABLED ( 1 )

If a function for rending raw frames should be enabled.

#define MBM_FUNC_REPORT_SLAVEID_ENABLED ( 1 )

If the Report Slave ID function should be enabled.

#define MBM_FUNC_WR_FILES_ENABLED ( 1 )

If the Write File Record function should be enabled.

#define MBM_FUNC_WR_MUL_REGS_ENABLED ( 1 )

If the Read Input Registers function should be enabled.

#define MBM_FUNC_WR_SINGLE_REG_ENABLED ( 1 )

If the Write Single Register function should be enabled.

#define MBM_FUNC_WRITE_COILS_ENABLED ( 1 )

If the Write Coils function should be enabled.

#define MBM_FUNC_WRITE_SINGLE_COIL_ENABLED ( 1 )

If the Write Single Coil function should be enabled.

#define MBM_RTU_WAITAFTERSEND_ENABLED ( 0 )

If the RTU layer should at least wait 3,5 times the character timeout before enabling the receiver.

#define MBM_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 MBM_SERIAL_APIV2_RTU_DYNAMIC_TIMEOUT_MS ( ulBaudRate ) ( MBM_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 MBM_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.

Note:
You should set this value equal to the buffer size of your serial driver (For example 8, 16 or 32 bytes) and the minimum speed you use. As an example suppose you use 19200 baud as the slowest communication speed and a FIFO buffer of 8 bytes. The minimum value for the timeout is 11/19200 * 8 = 4,5ms. To add a margin we would use 10ms.

#define MBM_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 MBM_SERIAL_ASCII_MAX_INSTANCES ( 2 )

Numer of serial ASCII instances supported.

#define MBM_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 MBM_SERIAL_RTU_MAX_INSTANCES ( 2 )

If MODBUS ASCII support is enabled. If MODBUS RTU support is enabled. If MODBUS TCP support is enabled. Numer of serial RTU instances supported.

#define MBM_TCP_MAX_INSTANCES ( 1 )

Numer of TCP instances supported.

#define MBM_TCP_PURGE_BEFORE_SEND ( 1 )

Purge TCP sockets before next write.
If enabled the client socket is purged before the next master transaction is started. This avoids problems in case of a previous timeout with data that is delivered late.

#define MBM_TIMEOUT_MODE_AFTER_TRANSMIT ( 0 )

Activate transmit timeout only after the transmit has been sent.
This function polls the transmit state machine and only decrements the timeout when the stack is not transmitting data. This is useful when the baudrate is low as in this case transmitting could already take more time than the timeout.

#define MBM_UDP_MAX_INSTANCES ( 1 )

Numer of UDP instances supported.

#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.


Defines
#define	MBM_SERIAL_RTU_MAX_INSTANCES ( 2 )
#define	MBM_SERIAL_ASCII_MAX_INSTANCES ( 2 )
#define	MBM_SERIAL_API_VERSION ( 1 )
#define	MBM_SERIAL_APIV2_RTU_TIMEOUT_MS ( 20 )
#define	MBM_SERIAL_APIV2_RTU_DYNAMIC_TIMEOUT_MS(ulBaudRate) ( MBM_SERIAL_APIV2_RTU_TIMEOUT_MS )
#define	MBM_TCP_MAX_INSTANCES ( 1 )
#define	MBM_UDP_MAX_INSTANCES ( 1 )
#define	MBM_DEFAULT_RESPONSE_TIMEOUT ( 500 )
#define	MBM_ASCII_TIMEOUT_SEC ( 1 )
#define	MBM_ASCII_BACKOF_TIME_MS ( 2 )
#define	MBM_FUNC_RD_HOLDING_ENABLED ( 1 )
#define	MBM_FUNC_WR_SINGLE_REG_ENABLED ( 1 )
#define	MBM_FUNC_RD_INPUT_REGS_ENABLED ( 1 )
#define	MBM_FUNC_WR_MUL_REGS_ENABLED ( 1 )
#define	MBM_FUNC_RDWR_MUL_REGS_ENABLED ( 1 )
#define	MBM_FUNC_READ_DISC_INPUTS_ENABLED ( 1 )
#define	MBM_FUNC_READ_COILS_ENABLED ( 1 )
#define	MBM_FUNC_WRITE_SINGLE_COIL_ENABLED ( 1 )
#define	MBM_FUNC_WRITE_COILS_ENABLED ( 1 )
#define	MBM_FUNC_READWRITE_RAWPDU_ENABLED ( 1 )
#define	MBM_FUNC_REPORT_SLAVEID_ENABLED ( 1 )
#define	MBM_FUNC_RD_FILES_ENABLED ( 1 )
#define	MBM_FUNC_WR_FILES_ENABLED ( 1 )
#define	MBM_ENABLE_FULL_API_CHECKS ( 1 )
#define	MBM_RTU_WAITAFTERSEND_ENABLED ( 0 )
#define	MBM_ASCII_WAITAFTERSEND_ENABLED ( 0 )
#define	MBP_ADVA_STARTUP_SHUTDOWN_ENABLED ( 0 )
#define	MBM_ENABLE_STATISTICS_INTERFACE ( 0 )
#define	MBM_ENABLE_PROT_ANALYZER_INTERFACE ( 0 )
#define	MBM_ENABLE_DEBUG_FACILITY ( 0 )
#define	MBM_ENABLE_DEBUG_FACILITY_HEAVY ( 0 )
#define	MBM_SERIAL_RTU_DYNAMIC_WAITAFTERSEND_TIMEOUT_MS(ulBaudRate) MB_INTDIV_CEIL( 1000UL * 11UL, ulBaudRate )
#define	MBM_SERIAL_ASCII_DYNAMIC_WAITAFTERSEND_TIMEOUT_MS(ulBaudRate) MB_INTDIV_CEIL( 1000UL * 10UL, ulBaudRate )
#define	MBM_TCP_PURGE_BEFORE_SEND ( 1 )
#define	MBM_TIMEOUT_MODE_AFTER_TRANSMIT ( 0 )

MODBUS Configuration [MODBUS Master]

Detailed Description

Defines

Define Documentation

MODBUS Configuration
[MODBUS Master]