3.2. LibModBus
Summary: |
itom-plugin for a modbus communication |
Type: |
DataIO |
License: |
licensed under GPL, since the libmodbus is also licensed under GPL |
Platforms: |
Windows, Linux |
Devices: |
Modbus communication over TCP/IP and RTU |
Author: |
J.Nitsche, IPROM, TU Braunschweig |
3.2.1. Overview
LibModBus is a itom-Plugin which provides modbusTCP and modbusRTU communication. The plugin is based on libmodbus v3.1.1 library and tested under Windows only atm. Registers are addressed using the modbus_read_registers (0x03) and modbus_write_registers (0x10) functions of libmodbus, coils are addressed using the modbus_read_bits (0x01) and modbus_write_bits (0x0F) functions. The plugin-functions used are getVal(dObj) and setVal(dObj) with a data object of the size 1xN with N the number of registers to be read/written. The content of the registers is expected as data in the uint16 data object for registers or uint8 data object for coils, the addressing of the registers is performed by a dObj-MetaTag ‘registers’ containing a string with address and number of consecutive registers seperated by ‘,’ and different registers seperated by ‘;’ i.e.: ‘10,2;34,1;77,4’ to address registers 10,11;34;77..80. Number 1 of consecutive registers can be left out i.e.:’10,2;34;77,4’ If no MetaTag is set, values of m_params[‘registers’] is tried to be used for addressing.
3.2.2. Initialization
The following parameters are mandatory or optional for initializing an instance of this plugin:
- target: str
Adress of the target device. IP-Adress for ModbusTCP (i.e. 127.0.0.1) or COM-Port for ModbusRTU (i.e. COM1)
RegExp: “[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}.[0-9]{1,3}||COM[1-9]||/dev/ttyS[0-9]{1,3}||/dev/ttyUSB[0-9]{1,3}”, Default: “127.0.0.1”
- port: int, optional
The number of the TCP port for ModBusTCP (default 502) or slave ID for ModbusRTU
Value range: [0, 1024], Default: 502
- baud: int, optional
The baudrate of the port for RTU communication
Value range: [50, 4000000], Default: 9600
- parity: str, optional
Parity for RTU communication (N,E,O)
RegExp: “[N,P,O]{1}”, Default: “N”
- databit: int, optional
Number of bits to be written in line for RTU communication
Value range: [5, 8], Default: 8
- stopbit: int, optional
Stop bits after every n bits for RTU communication
Value range: [1, 2], Default: 1
- output_mode: int, optional
Enables command-line output of different readouts (e.g. register values of getVal)
Value range: [0, 1], Default: 0
An example for opening a LibModBus instance at local host 127.0.0.1; port 502 is:
lmb = dataIO("LibModBus", '127.0.0.1', 502)
3.2.3. Parameters
These parameters are available and can be used to configure the LibModBus instance. Many of them are directly initialized by the parameters of the constructor. During the runtime of an instance, the value of these parameters is obtained by the method getParam, writeable parameters can be changed using setParam.
- name: {str}, read-only
name of the plugin (LibModBus)
- target: {str}, read-only
IP-Address of the connected Modbus-TCP device or serial port for Modbus-RTU connection. Under Windows COM1-COM9 is supported, unix-based systems should use /dev/ttyS0.. or /dev/ttyUSB0..
- port: {int}, read-only
port used for IP communication or device ID for ModbusRTU
- baud: {int}, read-only
The baudrate of the port for RTU communication
- parity: {str}, read-only
Parity for RTU communication (N->None, E->Even, O->Odd)
- databit: {int}, read-only
Number of bits to be written in line for RTU communication
- stopbit: {int}, read-only
Stop bits after every n bits for RTU communication
- output_mode: {bool}
if output_mode is true, multiple outputs will be sent to command line, e.g. register values of getVal function. Default is false
- registers: {str}
fallback addressing for modbus registers. This value will be used, if a dataObject without ‘registers’-tag is sent to the getVal- or setVal-function. registers needs to be stored with address and number of consecutive registers seperated by ‘,’ and different registers seperated by ‘;’ i.e.: ‘10,2;34,1;77,4’ to address registers 10,11;34;77..80. Number 1 of consecutive registers can be left out i.e.:’10,2;34;77,4’
3.2.4. Usage
Values can be read or written via modbus communication using the getVal(dObj) and setVal(dObj) functions. The dataObject dObj needs to be two dimensional with the first dimension set to 1, the second dimension has to have the exact size of the numbers of written or read registers. As modbus uses 16bit integer values, dObj must be initialized as ‘uint16’ for modbus register values. To read or write coils, dObj must be initialized as ‘uint8’ as the decision for using read/write coil or read/write register only depends on the data type of the input data object.
obj = dataObject([1,10],'uint16')
To address the requested registers, either parameter registers can be used, or obj can be given a registers-tag. The registers-tag has to have the same structure as the registers parameter. The parameter is useful if the same registers need to be read/written multiple times while the tag should be used for changing registers.
lmb = dataIO("LibModBus", '127.0.0.1', 502)
lmb.setParam('registers','10,2;34,1;77,4;100,1;101,1;102,1')
obj = dataObject([1,10],'uint16') #initializes register-object
coilObj = dataObject([1,10],'uint8') #initializes coil-object
lmb.getVal(obj) #reads registers 10,11,34,77..80,100..102 and saves them to obj consecutive
lmb.getVal(coilObj) #reads coils 10,11,34,77..80,100..102 and saves them to obj consecutive
obj.setTag('registers','105,4;200,4;204,2') #sets registers-tag
lmb.setVal(obj) #writes previously read values to registers 105..108,200..203,204,205
obj.setTag('registers','105,4;200,4')
lmb.setVal(obj) #produces error, obj is of size [1,10] but only 8 registers (105..108,200..203) are requested
The number of consecutive registers is generally used to read/write values that are bigger than 16bit (2 registers for 32bit, 4 registers for 64bit)and should be used that way. Please refer to the documentation of the modbus slave you will be using.