# 13 Modbus # 13.1 Introduction Modbus is a communication protocol for use with its programmable logic controllers (PLCs). Modbus has become a de facto standard communication protocol and is now a commonly available means of connecting industrial electronic devices. It was developed for industrial applications, is relatively easy to deploy and maintain compared to other standards, and places few restrictions other than size on the format of the data to be transmitted. Modbus enables communication among many devices connected to the same network, for example, a system that measures temperature and humidity and communicates the results to a computer. Modbus is often used to connect a supervisory computer with a remote terminal unit (RTU) in supervisory control and data acquisition (SCADA) systems. Many of the data types are named from industry usage of Ladder logic and its use in driving relays: a single-bit physical output is called a coil, and a single-bit physical input is called a discrete input or a contact.
WCC Lite supports both Modbus Master and Slave protocols. One can select between transmission over TCP/IP or serial connection (RS-485/RS232). Bytes to transmit can either be encoded according to both RTU and ASCII parts of the standard. # 13.2 Modbus Master Modbus communication contains a single Master and may include more than 1, but not more than 247 devices. To gather data from peripheral devices, the master device requests a cluster of slave devices for data. If any device understands that this message is addressed to it, it will reply with data. As no timestamp is sent along with data, having recent data requires frequent polling. WCC Lite can be configured to acquire data periodically in custom-defined intervals. #### Configuring datapoints Modbus Master in WCC Lite has to be configured via Excel. This configuration contains two Excel sheets where parameters have to be filled in - Devices and Signals ##### Modbus Master parameters for the Devices tab
**Parameter** **Type** **Description** **Required** **Default Value** (when not specified) **Range**
TCPRTU/ASCIIMinMax
name stringUser-friendly name for a device YesYes
description stringDescription of a device NoNo
device\_alias stringAlphanumeric string to identify a device YesYes
enablebooleanEnabling/disabling of a device NoNo101
protocolstringProtocol to be used YesYes Modbus RTU, Modbus TCP
ipstringThe IP address of the TCP slave deviceYes-
portintegerTCP communication port Yes - 502
bind\_addressstringThe IP address of the network adapter used to connect to the slave device (Default: ”0.0.0.0”) NoNo0.0.0.0
idintegerModbus Slave IDYesYes
modestringChoosing between RTU (”rtu”), ASCII (”ascii”) and TCP(”tcp”) modes. ASCII is the same as RTU, but with ASCII symbols.NoNoTCP (for TCP) RTU (for Serial) rtu, ascii, tcp
timeout\_msintegerResponse timeout in milliseconds Yes Yes10000
devicestring Communication port (”PORT1”/”PORT2”) - YesPORT1 PORT2
baudrateintegerCommunication speed, baud/s - Yes9600 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
databitsintegerData bit count for communication - Yes8 6 9
stopbitsintegerStop bit count for communication - Yes1 1 2
paritystring Communication parity option - Yesnone none, even, odd
flowcontrolstring Number of requests, before the link is considered lost (device status signals are changed) and reconnect attempt will be issued - Yesnone none
scan\_rate\_msintegerIf provided and positive - all jobs will have similar scan rates - all reads and writes will be executed within this timeframe (parameter scan\_rate\_ms in the Signals tab will be ignored) YesYes300
retry\_countintegerNumber of requests, before the link is considered lost (device status signals are changed) and reconnect attempt will be issued NoNo3
serial\_delayintegerRS485 delay between read and write operations in milliseconds - Yes50
keep\_alive\_timeout integerTime interval for sending a keep-alive packet (in milliseconds) NoNo60
modbus\_multi\_write booleanUse 15/16 functions to write 1 register/coil (Default: 0) NoNo001
comm\_restart\_delay integerTime delay between disconnecting from the slave device and restarting the connection (in milliseconds) (Default: 500) No -500
##### Modbus Master parameters for the Signals tab
**Parameter** **Type** **Description** **Required** **Default Value** (when not specified) **Range**
TCPRTU/ASCIIMinMax
signal\_name stringUser-friendly signal name YesYes
device\_alias stringAlphanumeric string to identify a device YesYes
signal\_alias stringUnique alphanumeric name of the signal to be Yes used YesYes
enablebooleanEnabling/disabling of an individual signal NoNo101
job\_todo stringRequest to send according to Modbus specification without device address and checksum. This field can be identical on several tags to fetch them in a single request YesYes
tag\_job\_todo stringSimilar format to the job\_todo field. Address and length must be a subset of the job field. Defines the individual tag’s register(s) or coil(s). Can be described in HEX or DEC formats YesYes
number\_type stringType of a number (FLOAT, DOUBLE, DIGITAL, etc.) YesYes
log integerIf the log parameter is 1, the signal will be visible in the events log tab, if 0, signals will not be logged. NoNo0
pulse\_short\_time\_ms integerThe time interval for short output pulse to stay active NoNo0
pulse\_long\_time\_ms integerThe time interval for a long output pulse to stay active NoNo0
periodic\_update\_ms integerSignal value will be published periodically according to the value set. NoNo

Note: If the number type is more than 16 bits (this means FLOAT, SIGNED32, DOUBLE etc.), modbus multiwrite should be enabled (1).

##### Device status signals Modbus Master has an additional signal which can be configured to show communication status. It is used to indicate if the slave device has disconnected from the master (WCC Lite). To configure such signal for Modbus protocol, job\_todo and tag\_job\_todo fields with string values are required. For Modbus master required parameters for the status signal will be **signal\_name** **device\_alias, signal\_alias, number\_type, job\_todo** and **tag\_job\_todo**. Job\_todo value must be *device\_status* and for tag\_job\_todo there are 4 variations: communication\_status, device\_running, device\_error, uknown\_error. Each signal has 4 possible values and is based on the same logic. If the signal returns the value of 0, it means an unknown error has appeared, 1 – device or protocol connection is on and working properly, 2 – device is off or protocol is disconnected, 3 – error or service is down. Different device vendors can have different implementations of a Modbus protocol stack. A register table can be one of the primary differences. WCC Lite Modbus Master transmits the most significant word (byte) first, however, devices from some vendors might require transmitting the least significant word (byte) first. If that is the case, make sure to switch bytes as needed. To find out more about setting a correct number format, one should consult a section [`number_type`](https://wiki.elseta.com/link/859#bkmrk-number_type-field). Modbus job or tag (as a task to be completed) can be built in two different formats - the user can select a more convenient way for him: - hexadecimal format with every single byte separated by a | symbol. Device address, bytes containing output information and CRC (LRC) bytes should be excluded from the message; - decimal format containing function number, first address and address count, separated by ; symbol. All other information should be excluded from the message; `job_todo` can group several `tag_job_todo`’s. That way one Modbus message can be used to extract several tags. Grouping is accomplished dynamically meaning that if several identical jobs are found, their tags are grouped automatically. #### Debugging a Modbus Master application If the configuration for Modbus Master is set up, a handler for the protocol will start automatically. If the configuration is missing or contains errors, the protocol will not start. It is done intentionally to decrease unnecessary memory usage. Modbus Master command line debugging options `modbus-master ` ``` -h [ –help ] Display help information

-V [ –version ] Show version

-d Set debugging level

-c [ –config ] Config path

-e [ –redis ] Show redis debug information ``` If Modbus Master does not work properly (e.g. no communication between devices, data is corrupted, etc.), a user can launch a debug session from the command line interface and find out why the link is not functioning properly. To launch a debugging session, a user should stop the Modbus-master process and run the Modbus-master command with respective flags as shown above. To run a debug session: - **Step 1**: Service must be stopped by entering the following command into the wcclite: **/etc/init.d/modbus-­master stop** - **Step 2**: After the service is stopped it must be started with the preferred configuration file (JSON files found in the /etc/ folder) and a debug level 7: **modbus-master ­-c /etc/modbus-master/modbus-master.json ­-d7** Additional output forming options described in the table above. - **Step 3**: Once the problem is diagnosed normal operations can be resumed with the following command: **/etc/init.d/modbus-master start** # 13.3 Modbus Slave WCC Lite can act as one (or several) of slave devices in a communication line. This can be used to transmit data to SCADA systems or other RTU devices. It can reply to messages from Modbus Master with matching devices and register addresses. #### Configuring datapoints Modbus Slave in WCC Lite has to be configured via Excel. This configuration contains two Excel sheets where parameters have to be filled in - Devices and Signals

If TCP/IP is used as a transmission medium, only devices with IPs predefined in the host column are allowed to connect. All other connections are rejected

##### Modbus Slave parameters for Devices tab
**Parameter** **Type** **Description** **Required** **Default Value** (when not specified) **Range**
TCPRTU/ASCIIMinMax
name stringUser-friendly name for a device YesYes
description stringDescription of a device NoNo
device\_alias stringAlphanumeric string to identify a device YesYes
unknown
enablebooleanEnabling/disabling of a device NoNo101
protocolstringProtocol to be used YesYes Modbus serial Slave, Modbus TCP Slave
hoststringSpace-separated host IP addresses of master deviceYes-
portintegerTCP port to listen for incoming connections Yes -
bind\_addressstringThe IP address of the network adapter used to connect to the slave device (Default: ”0.0.0.0”) NoNo0.0.0.0
keep\_alive\_timeout integerThe minimum time a connection can be idle without being closed in milliseconds NoNo60
modestringChoosing between RTU (”rtu”), ASCII (”ascii”) and TCP(”tcp”) modes. ASCII is the same as RTU, but with ASCII symbols.NoNoTCP (for TCP) RTU (for Serial) rtu, ascii, tcp
devicestring Communication port (”PORT1”/”PORT2”) - YesPORT1 PORT2
baudrateintegerCommunication speed, baud/s - Yes9600 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200
databitsintegerData bit count for communication - Yes8 6 9
stopbitsintegerStop bit count for communication - Yes1 1 2
paritystring Communication parity option - Yesnone none, even, odd
flowcontrolstring The communication device’s flow control option. -Nonone none
##### Modbus Slave parameters for the Signals tab
**Parameter** **Type** **Description** **Required** **Default Value** (when not specified) **Range**
TCPRTU/ASCIIMinMax
signal\_name stringUser-friendly signal name YesYes
device\_alias stringAlphanumeric string to identify a device YesYes
signal\_alias stringUnique alphanumeric name of the signal to be used YesYes
enablebooleanEnabling/disabling an individual signal NoNo101
number\_type stringType of a number (FLOAT, DOUBLE, DIGITAL, etc.). This defines the size that will be read. YesYes
log integerIf the log parameter is equal to 1, the signal values and attributes will be seen in the events log. NoNo0
slave\_idintegerAddress of a slave deviceYesYes
functionintegerFunction numberYesYes 1, 2, 3, 4
register\_addressintegerRegister addressYesYes
periodic\_update\_msintegerSignal value is published periodically according to the value set.NoNo---
##### Device status signals
Modbus slave has an additional signal which can be configured to show communication status. It indicates if the master device has disconnected from the slave (WCC Lite). To configure such signal for Modbus protocol, job\_todo and tag\_job\_todo fields with string values are required. For Modbus slave required parameters for the status, the signal will be **signal\_name** **device\_alias, signal\_alias, number\_type, slave\_id, function**, **register\_address, job\_todo** and **tag\_job\_todo**. Job\_todo value must be *device\_status* and for tag\_job\_todo there are 4 variations: communication\_status, device\_running, device\_error, uknown\_error. Each signal has 4 possible values and is based on the same logic. If the signal returns the value of 0, it means an unknown error has appeared, 1 – device or protocol connection is on and working properly, 2 – device is off or protocol is disconnected, 3 – error or service is down. #### Mapping values to registers Internally stored values aren’t organised in a register-like order, therefore mapping should be done by the user. This mapping includes setting the address of the device WCC Lite is simulating as well as the function number, register number and how many 16-bit registers are used to store a value. These values should be set in `common_address`, `function`, `info_address` and `size` columns respectively in the Excel configuration. To find out how many registers should be used for storing values, and how values can have their values swapped, a user should consult a section `number_type`.

If a Modbus master device requests data from a register that is mapped but doesn’t yet have an initial value, an ILLEGAL DATA ADDRESS error code will be returned. The same error code is returned if the requested size of the value is bigger than defined or if the register is not configured at all.

#### Debugging a Modbus Slave application If the configuration for Modbus Slave is set up, a handler for the protocol will start automatically. If the configuration is missing or contains errors, the protocol will not start. It is done intentionally to decrease unnecessary memory usage. Modbus Slave command line debugging options To run a debug session: - **Step 1**: Service must be stopped by entering the following command into the wcclite: **/etc/init.d/modbus-­slave stop** - **Step 2**: After the service is stopped it must be started with the preferred configuration file (JSON files found in the /etc/ folder) and a debug level 7: **modbus-slave ­-c /etc/modbus-­slave/modbus-slave.json ­-d7** Additional output forming options described in the table below. - **Step 3**: Once the problem is diagnosed normal operations can be resumed with the following command: **/etc/init.d/modbus-­slave start** ``` -h [ –help ] Display help information

-V [ –version ] Show version

-d Set debugging level

-c [ –config ] Config path

-e [ –redis ] Show redis debug information ```

If Modbus Slave does not work properly (e.g. no communication between devices, data is corrupted, etc.), a user can launch a debug session from the command line interface and find out why the link is not functioning properly.

To launch a debugging session, a user should stop `modbus-slave` process and run `modbus-slave` command with respective flags as shown above.