Modbus Connector Configuration

Section “master”: description and configuration parameters
- Subsection “slaves”
  - Slave object settings
Section “slave”: description and configuration parameters
- Subsection “values”
Additional information
- Modbus functions
- Data types
Next steps

This guide will help you to get familiar with Modbus connector configuration for ThingsBoard IoT Gateway. Use general configuration to enable this connector. We will describe connector configuration file below.

Example of Modbus Connector config file. Press to expand.

{
  "master": {
    "slaves": [
      {
        "host": "127.0.0.1",
        "port": 5021,
        "type": "tcp",
        "method": "socket",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 5000,
        "unitId": 1,
        "deviceName": "Temperature_Sensor_1",
        "deviceType": "sensors",
        "sendDataOnlyOnChange": false,
        "connectAttemptTimeMs": 5000,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 300000,
        "attributes": [
          {
            "tag": "bits_read",
            "type": "bits",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 5
          },
          {
            "tag": "8int_read",
            "type": "8int",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 6
          },
          {
            "tag": "16int_read",
            "type": "16int",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 7
          },
          {
            "tag": "32int_read_divider",
            "type": "32int",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 8,
            "divider": 10
          },
          {
            "tag": "8int_read_multiplier",
            "type": "8int",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 10,
            "multiplier": 10
          },
          {
            "tag": "32int_read",
            "type": "32int",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 11
          },
          {
            "tag": "64int_read",
            "type": "64int",
            "functionCode": 4,
            "objectsCount": 4,
            "address": 13
          }
        ],
        "timeseries": [
          {
            "tag": "8uint_read",
            "type": "8uint",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 17
          },
          {
            "tag": "16uint_read",
            "type": "16uint",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 18
          },
          {
            "tag": "32uint_read",
            "type": "32uint",
            "functionCode": 4,
            "objectsCount": 4,
            "address": 20
          },
          {
            "tag": "64uint_read",
            "type": "64uint",
            "functionCode": 4,
            "objectsCount": 4,
            "address": 24
          },
          {
            "tag": "16float_read",
            "type": "16float",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 25
          },
          {
            "tag": "32float_read",
            "type": "32float",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 26
          },
          {
            "tag": "64float_read",
            "type": "64float",
            "functionCode": 4,
            "objectsCount": 4,
            "address": 28
          }
        ],
        "attributeUpdates": [
          {
            "tag": "shared_attribute",
            "type": "16int",
            "functionCode": 16,
            "objectsCount": 1,
            "address": 29
          }
        ],
        "rpc": [
          {
            "tag": "shared_attribute_read",
            "type": "16int",
            "functionCode": 3,
            "objectsCount": 1,
            "address": 29
          },
          {
            "tag": "setValue",
            "type": "bits",
            "functionCode": 5,
            "objectsCount": 1,
            "address": 31
          },
          {
            "tag": "getValue",
            "type": "bits",
            "functionCode": 1,
            "objectsCount": 1,
            "address": 31
          },
          {
            "tag": "setCPUFanSpeed",
            "type": "32int",
            "functionCode": 16,
            "objectsCount": 2,
            "address": 33
          },
          {
            "tag": "getCPULoad",
            "type": "32int",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 35
          }
        ]
      }
    ]
  },
  "slave": {
    "type": "tcp",
    "host": "127.0.0.1",
    "port": 5026,
    "method": "socket",
    "deviceName": "Modbus_Slave_Example",
    "deviceType": "default",
    "pollPeriod": 5000,
    "sendDataToThingsBoard": false,
    "byteOrder": "BIG",
    "unitId": 0,
    "values": {
      "holding_registers": [
        {
          "attributes": [
            {
              "tag": "sm",
              "type": "string",
              "objectsCount": 1,
              "address": 1,
              "value": "ON"
            }
          ],
          "timeseries": [
            {
              "tag": "smm",
              "type": "int",
              "objectsCount": 1,
              "address": 2,             
              "value": "12334"
            }
          ],
          "attributeUpdates": [
            {
              "tag": "shared_attribute_write",
              "type": "32int",
              "functionCode": 6,
              "objectsCount": 2,
              "address": 29,
              "value": 1243
            }
          ],
          "rpc": [
            {
              "tag": "setValue",
              "type": "bits",
              "functionCode": 5,
              "objectsCount": 1,
              "address": 31,
              "value": 22
            }
          ]
        }
      ],
      "coils_initializer": [
        {
          "attributes": [
            {
              "type": "string",
              "tag": "sm",
              "objectsCount": 1,
              "address": 5,
              "value": "12"
            }
          ],
          "timeseries": [],
          "attributeUpdates": [],
          "rpc": []
        }
      ]
    }
  }
}

Section “master”: description and configuration parameters

A Modbus Master is used to query data from devices. In order to configure slaves which the master must be queried, it must be specified “master” section that includes the “slaves” list.

Subsection “slaves”

This subsection provides array of configurations for slaves.

Slave object settings

This configuration contains common connection parameters and settings for data processing.

Due to the nature of preferred way of communication between Modbus master there are 2 options how to configure this part: if using TCP/UDP or via Serial port.

There are 2 variants of server section:

TCP/UDPConnection over TCP/UDP protocol

SerialConnection over serial port

Parameter	Default value	Description
name	Modbus Default Server	Name of connector to server.
host	127.0.0.1	Hostname or ip address of Modbus server.
port	5021	Port of Modbus server for connect.
type	tcp	Type of connection may be tcp, udp or serial.
method	socket	Type of a framer socket or rtu, if needed.
timeout	35	Timeout in seconds for connecting to Modbus server.
byteOrder	LITTLE	Order of bytes to read.
wordOrder	LITTLE	Order of words in case of reading several registers.

Parameter	Default value	Description
name	Modbus Default Server	Name of connector to server.
type	serial	Type of connection may be tcp, udp or serial.
method	rtu	Type of application data unit - rtu or ascii
port	/dev/ttyUSB0	Serial port for connection.
baudrate	19200	Baudrate for The baud rate to use for the serial device.
stopbits	1	The number of bits sent after each character in a message to indicate the end of the byte.
bytesize	8	The number of bits in a byte of serial data. This can be one of 5, 6, 7, or 8.
parity	N	The type of checksum to use to verify data integrity. This can be on of the following: (E)ven, (O)dd, (N)one.
strict	true	Use Inter char timeout for baudrates <= 19200.
timeout	35	Timeout in seconds for connecting to Modbus server.
byteOrder	BIG	Order of bytes to read.

The next part of slave section contains common connection parameters and settings for data processing. Available parameters are as follows:

Parameter	Default value	Description
retries	true	Retrying sending data to the master. The values: true or false
retryOnEmpty	true	Retrying sending data to the master if it is empty
retryOnInvalid	true	Retrying sending data to the master if it is failed
pollPeriod	5000	Period in milliseconds for check the attributes and the telemetry on slave.
unitId	1	Id of current slave on Modbus.
deviceName	Temperature_Sensor_1	Name of the current slave
deviceType	sensors	Type of the current slave
sendDataOnlyOnChange	false	Sending only if data changed from last check, if no – data will send after every check
connectAttemptTimeMs	5000	A period in milliseconds for waiting to connect to the master
connectAttemptCount	5	The number of connection attempts made through the ThingsBoard gateway
waitAfterFailedAttemptsMs	300000	A period in milliseconds for a wait before trying to send data to the master

Example:

{
  "master": {
    "slaves": [
      {
        "host": "10.7.1.106",
        "port": 5021,
        "type": "tcp",
        "method": "socket",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 5000,
        "unitId": 1,
        "deviceName": "Temperature_Sensor_1",
        "deviceType": "sensors",
        "sendDataOnlyOnChange": false,
        "connectAttemptTimeMs": 5000,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 300000
      }
    ]
  }
}

Key settings for “attributes”

Configuration in this unit provides settings for processing data on Modbus server, which will be interpreted in ThingsBoard platform instance as attribute of device.

Parameter	Default value	Description
tag	certificateNumber	Tag, which will use as attribute key for ThingsBoard platform instance.
type	32int	Type of value. Available data types
functionCode	4	Function to use in processing data. Modbus functions
objectsCount	2	Count of objects to read.
address	0	Object address to check.

Optional parameters:
multiplier - result of reading will be multiplied by value of this parameter.
divider - result of reading will be divided by value of this parameter.

Example:

        ...
          "attributes": [
          {
            "tag": "certificateNumber",
            "type": "32int",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 0
          }
        ],
        ...

Key settings for “timeseries”

Configuration in this unit provides settings for processing data on Modbus server, which will be interpreted in ThingsBoard platform instance as telemetry of device.

Parameter	Default value	Description
tag	telemetry_1	Tag, which will use as attribute key for ThingsBoard platform instance.
type	16uint	Type of value. Available data types
functionCode	4	Function to use in processing data. Modbus functions
objectsCount	1	Count of objects to read.
address	1	Object address to check.

tag	telemetry_2	Tag, which will use as attribute key for ThingsBoard platform instance.
type	16uint	Type of value. Available data types
functionCode	4	Function to use in processing data. Modbus functions
objectsCount	1	Count of objects to read.
address	3	Object address to check.

Example:

        ...
        "timeseries": [
          {
            "tag": "telemetry_1",
            "type": "16uint",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 1
          },
          {
            "tag": "telemetry_2",
            "type": "16uint",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 3
          }
        ],
        ...

Key settings for “attributeUpdates”

Configuration in this unit provides settings for Attribute update requests from ThingsBoard platform instance.

Parameter	Default value	Description
tag	maxTemperature	Shared attribute name.
type	16int	Type of value. Available data types
functionCode	16	Function to use in processing data. Modbus functions
objectsCount	1	Count of objects to write.
address	29	Object address.

Example:

        ...
        "attributeUpdates": [
          {
            "tag": "maxTemperature",
            "type": "16int",
            "functionCode": 16,
            "objectsCount": 1,
            "address": 29
          }
        ],
        ...

For example, create a new attribute “maxTemperature” and give it a value “25”.

Key settings for “rpc”

Configuration in this unit provides settings for RPC requests from ThingsBoard platform instance to device.

Parameter	Default value	Description
tag	maxTemperature_read	RPC method name.
type	16int	Type of value. Available data types
functionCode	3	Function to use in processing data. Modbus functions
objectsCount	1	Count of objects to write.
address	29	Object address.

Example:

        ...
        "rpc": [
          {
            "tag": "maxTemperature_read",
            "type": "16int",
            "functionCode": 3,
            "objectsCount": 1,
            "address": 29
          }
        ],
        ...

To send RPC requests to the gateway the one should use RPC Debug Terminal from Control widgets bundle.

Execute “maxTemperature_read” RPC request from the ThingsBoard instance to the device.

In response, you should receive the previously recorded value - “25”.

Also, every telemetry and attribute parameter has built-in GET and SET RPC methods out of the box, so you don’t need to configure it manually. To use them, make sure you set all required parameters (in the case of Modbus Connector, these are the following: type, functionCode, objectsCount, address). See the guide.

Section “slave”: description and configuration parameters

Starting with version 3.0, Gateway can run as a Modbus slave. In order to configure Gateway as a Modbus slave, specify the “slave” section in the configuration file.

There are 2 variants of Gateway slave section:

TCP/UDPConnection over TCP/UDP protocol

SerialConnection over serial port

Parameter	Default value	Description
type	tcp	Type of connection may be tcp, udp or serial.
host	127.0.0.1	Hostname or ip address of Modbus server.
port	5020	Port of Modbus server for connect.
method	socket	Type of framer socket or rtu, if needed.
deviceName	Modbus_Slave_Example	Device name
deviceType	default	Device type
pollPeriod	5000	Period in milliseconds for check the attributes and the telemetry.
sendDataToThingsBoard	false	If set to TRUE, Gateway make autoconfiguration and every ms send values to ThingsBoard
byteOrder	BIG	Order of bytes to read.
unitId	0	Unit id of the device

Parameter	Default value	Description
deviceName	Gateway	Device name
deviceType	default	Device type
type	serial	Type of connection may be tcp, udp or serial.
method	rtu	Type of application data unit - rtu or ascii
port	/dev/ttyUSB0	Serial port for connection.
baudrate	19200	Baudrate for The baud rate to use for the serial device.
byteOrder	BIG	Order of bytes to read.
unitId	0	Unit id of the device
pollPeriod	5000	Period in milliseconds for check the attributes and the telemetry.
sendDataToThingsBoard	false	If set to TRUE, Gateway make autoconfiguration and every ms send values to ThingsBoard

Example:

{
  "slave": {
    "type": "tcp",
    "host": "127.0.0.1",
    "port": 5026,
    "method": "socket",
    "deviceName": "Modbus_Slave_Example",
    "deviceType": "default",
    "pollPeriod": 5000,
    "sendDataToThingsBoard": false,
    "byteOrder": "BIG",
    "unitId": 0
  }
}

You can also specify service information about the device using the “identity” subsection as follows:

Parameter	Default value
vendorName	Gateway
productCode	GT
vendorUrl	https://github.com/thingsboard/thingsboard-gateway
productName	Gateway
modelName	1

Subsection “values”

In this section you can specify values that Gateway will save in the store. Each value refers to a specific type of register. There are:

holding_registers
coils_initializer
input_registers
discrete_inputs

Depending on which value the register belongs to, you must add it to the appropriate array. For example:

"values": {
      "holding_registers": [
        {
          "attributes": [
            {
              "tag": "sm",
              "type": "string",
              "objectsCount": 1,
              "address": 1,
              "value": "ON"
            }
          ],
          "timeseries": [
            {
              "tag": "smm",
              "type": "int",
              "objectsCount": 1,
              "address": 2,              
              "value": "12334"
            }
          ],
          "attributeUpdates": [
            {
              "tag": "shared_attribute_write",
              "type": "32int",
              "functionCode": 6,
              "objectsCount": 2,
              "address": 29,
              "value": 1243
            }
          ],
          "rpc": [
            {
              "tag": "setValue",
              "type": "bits",
              "functionCode": 5,
              "objectsCount": 1,
              "address": 31,
              "value": 22
            }
          ]
        }
      ], 
        "coils_initializer": [
        {
          "attributes": [
            {
              "tag": "sm",
              "type": "string",
              "objectsCount": 1,
              "address": 5,
              "value": "12"
            }
         ],
          "timeseries": [],
          "attributeUpdates": [],
          "rpc": []
        }
      ]
    }
  }
}

Additional information

Additional information about Modbus functions and supported data types.

Modbus functions

The Modbus connector supports the following Modbus functions:

Modbus function code	Description
Read data
1	Read Coils
2	Read Discrete Inputs
3	Read Multiple Holding Registers
4	Read Input Registers
Write data:
5	Write Coil
6	Write Register
15	Write Coils
16	Write Registers

Data types

A list and description of the supported data types for reading/writing data.

Type	Function code	Objects count	Note
string	3-4	1-…	Read bytes from registers and decode it (‘UTF-8’ coding).
bytes	3-4	1-…	Read bytes from registers.
bits	1-4	1-…	Read coils. If objects count 1 - result will be interpret as a boolean, else the result will be an array with bits.
16int	3-4	1	Integer 16 bit.
16uint	3-4	1	Unsigned integer 16 bit.
16float	3-4	1	Float 16 bit.
32int	3-4	2	Integer 32 bit.
32uint	3-4	2	Unsigned integer 32 bit.
32float	3-4	2	Float 32 bit.
64int	3-4	4	Integer 64 bit.
64uint	3-4	4	Unsigned integer 64 bit.
64float	3-4	4	Float 64 bit.

Next steps

Explore guides related to main ThingsBoard features:

Connect Modbus device - how to connect Modbus device using ThingsBoard IoT Gateway
Data Visualization - how to visualize collected data.
Device attributes - how to use device attributes.
Telemetry data collection - how to collect telemetry data.
Using RPC capabilities - how to send commands to/from devices.
Rule Engine - how to use rule engine to analyze data from devices.

On this page

Modbus Connector Configuration

Section “master”: description and configuration parameters

Subsection “slaves”

Slave object settings

Key settings for “attributes”

Key settings for “timeseries”

Key settings for “attributeUpdates”

Key settings for “rpc”

Section “slave”: description and configuration parameters

Subsection “values”

Additional information

Modbus functions

Data types

Next steps