MBLogic
for an open world in automation
Help - Modbus/RTU Generic Client Protocol
Overview
The Modbus/RTU Generic client support is experiment at this time and is subject to change. This is currently a beta version.
Modbus/RTU
The Modbus/RTU (http://www.modbus.org) generic client implements a single serial Modbus/RTU master that can read/write data to one or more Modbus/RTU slaves, in a point-multipoint scheme (using a direct RS232 connection or a RS485 bus). Each slave can be polled by one or more commands.
The commands are sent sequentially (in alphabetical order), with a time spacing defined by ‘cmdtime’, and when last command for the list is sent, the client wait ‘repeattime’ to start again the sequence with the first command.
To optimize the use of the serial channel, when a command reaches a pre-defined quantity (5) of consecutive failed queries, the client declares this command as “faulted” and retries are suspended for this command until a valid response is received and the command is returned to the normal (Ok) state.
This version does not implement serial handshaking (neither hardware or software).
The client makes the proper conversion for the exchange of data (for example, a “0” binary coil converts to “0” in a input register, and an non-zero value in a holding register converts to “1” in an input status), either between the client and the MBLogic server, or between the client and the slaves (field devices).
The implementation covers the following files (contained in /genclient directory):
- mbrtuclient.py
- mbrtuconfig.py
- mbrtumsg.py
This generic client has been tested with typical Modbus/RTU emulators (MOD_RSsim v3.6, and ModSim32 v4.A).
Standard Parameters
The following are the standard generic client parameters for this generic client.
| Item | Value | Description |
|---|---|---|
| protocol | modbusrtu | Selects Modbus/RTU protocol |
| type | genericclient | Selects genericclient |
| clientfile | mbrtuclient.py -d 1 | Specifies the name of the file used to implement the client. The parameter "-d" will specify a start-up delay in seconds. |
Example:
protocol = modbusrtu type = genericclient clientfile = mbrtuclient.py -d 1
Client Parameters
The following are the client parameters.
| Item | Description | Valid Values |
|---|---|---|
| serialport | The serial port to use. This must be a valid serial port name. E.g. "/dev/ttyS0". | See "serial port names" below. |
| baudrate | This must be one of the following valid baud rates | 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200, 128000, 256000 |
| parity | This must be one of the following valid parity values: | even, odd, mark, space, none (or e, o, m, s, n) |
| bytesize | This must be one of the following valid data bits size: | 7, 8 |
| stopbits | This must be one of the following valid stop bits value. | 1, 2 |
| statisticstable | Command's statistical table index/offset (inside inpreg group of writetable). | An integer between 0 and the maximum size of the input registers for "writetable". See “Statistics Tables” below. |
| cmdtime | This is the delay time in milli-seconds between commands. | An integer greater than or equal to 0. |
| repeattime | This is the delay time in milli-seconds between repeating sets of commands. | An integer greater than or equal to 0. |
| retrytime | This is the delay time in milli-seconds between retrying commands in the event of an error. | An integer greater than or equal to 0. |
| retries | Maximum number of consecurtive command retries to allow. | An integer greater than or equal to 0. |
Example:
serialport = /dev/ttyS0 baudrate = 9600 parity = None bytesize = 8 stopbits = 1 statisticstable = 20 retries = 0 cmdtime = 500 repeattime = 2000 retrytime = 1000
Commands
| Item | Description | Valid Values |
|---|---|---|
| action | The command action. If ‘disabled’, the command will not be executed. For ‘oneshot’ action, if the current command is ‘Read’ type send the command until one successful response (valid or not) from field device (slave) is received. If the current command is ‘Write’ type send the command only if data to write has changed since last succesfully query. For ‘poll’ action, send the command in the normal sequence. | poll, oneshot, disabled |
| uid | Modbus unit id | 0 to 247 |
| function | Modbus function code. Functions 1, 2, 3 and 4 write the data received from the slaves to the ‘Data Table Write Addresses’, and functions 5, 6, 15 and 16 send to slaves the data read from the ‘Data Table Read Addresses’. | 1, 2, 3, 4, 5, 6,15, 16 |
| remoteaddr | Data table address of the remoted device. | 0 to 65535 |
| qty | Number of addresses to read or write. | The maximum value depends on the function selected. |
| datatype | The type of system data table address to read or write. | coil, inp, holdingreg, inpreg |
| dataoffset | The offset in the 'readtable' or 'writetable' arrays in which to read or write data. | Greater than or equal to 0. Must be less than the maximum address transferred for the selected datatype. |
Example:
&readinput = action=poll, uid=1, function=2, remoteaddr=10, qty=10, datatype=inp, dataoffset=0 &writesinglecoil = action=poll, uid=1, function=5, remoteaddr=0, qty=1, datatype=inp, dataoffset=0 &writemultiplecoil = action=oneshot, uid=1, function=15, remoteaddr=1, qty=9, datatype=coil, dataoffset=1 &readholding = action=disabled, uid=1, function=3, remoteaddr=10, qty=10, datatype=holdingreg, dataoffset=5 &writemultiplereg = action=oneshot, uid=1, function=16, remoteaddr=1, qty=9, datatype=holdingreg, dataoffset=0 &readinputreg = action=oneshot, uid=1, function=4, remoteaddr=10, qty=10, datatype=inpreg, dataoffset=0 &writesinglereg = uid=1, function=6, remoteaddr=0, qty=1, datatype=inpreg, dataoffset=0 &readcoil = action=poll, uid=1, function=1, remoteaddr=10, qty=10, datatype=coil, dataoffset=10
Serial Port Names
Serial ports must use the naming conventions defined by pyserial python library (http://pyserial.sourceforge.net)
For either Linux or MS Windows, serial ports may be named as:
- 0 is the first serial port
- 1 is the second serial port
- etc.
For Linux, it is also possible to use standard tty names:
- /dev/tty0 is the first serial port
- /dev/tty1 is the second serial port
- /dev/ttyUSB0 is the first serial port (using an USB-Serial Port adapter)
- etc.
Example:
serialport=/dev/ttyS0 serialport=1
Statistics
Each generic client has a additional statistic table, where results of each command are summarized. This table is contained into the “Input Register” section of “Data Table Write Addresses”, and its use is mandatory, so this section must have at least (Qty of Commands * 10) addresses. For example, if a generic client has 3 commands and must return 8 Input Registers of field data to the server, the size of “Input Register” must be at least 38 (3*10 + 8) .
Collection of statistics begins when the generic client starts and can not be reset (in this version).
The client alphabetically sorts all commands defined in the client configuration file, and the statistics of all commands are showed consecutively following that order. Each command has 10 registers whose function is described below:
| Offset | Description |
|---|---|
| 0 | Result of last query/poll. Value is 1 if Ok, or 0 if an error is present. |
| 1 | Total number of queries. |
| 2 | Total number of valid queries. |
| 3 | Total number of invalid queries. |
| 4 | Total number of frame errors. |
| 5 | Total number of command time-outs. |
| 6 | Total number of times a command was retried. |
| 7 | Command efficieny, calculated as: (valid queries) * 100 / (total queries). |
| 8 | Spare, reserved for future use. |
| 9 | Spare, reserved for future use. |