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.
    1. {
    2. "server": {
    3.   "type": "tcp",
    4.   "host": "127.0.0.1",
    5.   "port": 5020,
    6.   "timeout": 35,
    7.   "method": "socket",
    8.   "byteOrder": "BIG",
    9.   "devices": [
    10.     {
    11.       "unitId": 1,
    12.       "deviceName": "Temp Sensor",
    13.       "attributesPollPeriod": 5000,
    14.       "timeseriesPollPeriod": 5000,
    15.       "sendDataOnlyOnChange": true,
    16.       "attributes": [
    17.         {
    18.           "tag": "string_read",
    19.           "type": "string",
    20.           "functionCode": 4,
    21.           "objectsCount": 4,
    22.           "address": 1
    23.         },
    24.         {
    25.           "tag": "bits_read",
    26.           "type": "bits",
    27.           "functionCode": 4,
    28.           "objectsCount": 1,
    29.           "address": 5
    30.         },
    31.         {
    32.           "tag": "8int_read",
    33.           "type": "8int",
    34.           "functionCode": 4,
    35.           "objectsCount": 1,
    36.           "address": 6
    37.         },
    38.         {
    39.           "tag": "16int_read",
    40.           "type": "16int",
    41.           "functionCode": 4,
    42.           "objectsCount": 1,
    43.           "address": 7
    44.         },
    45.         {
    46.           "tag": "32int_read_divider",
    47.           "type": "32int",
    48.           "functionCode": 4,
    49.           "objectsCount": 2,
    50.           "address": 8,
    51.           "divider": 10
    52.         },
    53.         {
    54.           "tag": "8int_read_multiplier",
    55.           "type": "8int",
    56.           "functionCode": 4,
    57.           "objectsCount": 1,
    58.           "address": 10,
    59.           "multiplier": 10
    60.         },
    61.         {
    62.           "tag": "32int_read",
    63.           "type": "32int",
    64.           "functionCode": 4,
    65.           "objectsCount": 2,
    66.           "address": 11
    67.         },
    68.         {
    69.           "tag": "64int_read",
    70.           "type": "64int",
    71.           "functionCode": 4,
    72.           "objectsCount": 4,
    73.           "address": 13
    74.         }
    75.     ],
    76.     "timeseries": [
    77.         {
    78.           "tag": "8uint_read",
    79.           "type": "8uint",
    80.           "functionCode": 4,
    81.           "objectsCount": 1,
    82.           "address": 17
    83.         },
    84.         {
    85.           "tag": "16uint_read",
    86.           "type": "16uint",
    87.           "functionCode": 4,
    88.           "objectsCount": 2,
    89.           "address": 18
    90.         },
    91.         {
    92.           "tag": "32uint_read",
    93.           "type": "32uint",
    94.           "functionCode": 4,
    95.           "objectsCount": 4,
    96.           "address": 20
    97.         },
    98.         {
    99.           "tag": "64uint_read",
    100.           "type": "64uint",
    101.           "functionCode": 4,
    102.           "objectsCount": 1,
    103.           "address": 24
    104.         },
    105.         {
    106.           "tag": "16float_read",
    107.           "type": "16float",
    108.           "functionCode": 4,
    109.           "objectsCount": 1,
    110.           "address": 25
    111.         },
    112.         {
    113.           "tag": "32float_read",
    114.           "type": "32float",
    115.           "functionCode": 4,
    116.           "objectsCount": 2,
    117.           "address": 26
    118.         },
    119.         {
    120.           "tag": "64float_read",
    121.           "type": "64float",
    122.           "functionCode": 4,
    123.           "objectsCount": 4,
    124.           "address": 28
    125.         }
    126.       ],
    127.       "attributeUpdates": [
    128.         {
    129.           "tag": "shared_attribute_write",
    130.           "type": "32int",
    131.           "functionCode": 6,
    132.           "objectsCount": 2,
    133.           "address": 29
    134.         }
    135.       ],
    136.       "rpc": [
    137.         {
    138.           "tag": "setValue",
    139.           "type": "bits",
    140.           "functionCode": 5,
    141.           "objectsCount": 1,
    142.           "address": 31
    143.         },
    144.         {
    145.           "tag": "getValue",
    146.           "type": "bits",
    147.           "functionCode": 1,
    148.           "objectsCount": 1,
    149.           "address": 31
    150.         },
    151.         {
    152.           "tag": "setCPUFanSpeed",
    153.           "type": "32int",
    154.           "functionCode": 16,
    155.           "objectsCount": 2,
    156.           "address": 33
    157.         },
    158.         {
    159.           "tag":"getCPULoad",
    160.           "type": "32int",
    161.           "functionCode": 4,
    162.           "objectsCount": 2,
    163.           "address": 35
    164.         }
    165.       ]
    166.     }
    167.   ]
    168. }
    169. }

Section “server”: description and configuration parameters

In order to connect to Modbus server, the one must set required parameters of section “server”. Due to the nature of preferred way of communication with Modbus server 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/UDP
Connection over TCP/UDP protocol |
Serial
Connection over serial port
| | —- | —- |

Parameter Default value Description
name Modbus Default Server Name of connector to server.
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.
timeout 35 Timeout in seconds for connecting to Modbus server.
method socket Type of a framer socket or rtu, if needed.
byteOrder BIG Order of bytes to read.
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.

Sub-section “devices”

This sub-section provides array of configurations for devices.

Device object settings

This configuration contains common connection parameters and settings for data processing. Available parameters are as follows:

Parameter Default value Description
unitId 1 Id of current device on Modbus.
deviceName Temp Sensor Name of the current device
attributesPollPeriod 5000 Period in milliseconds for check the attributes on device.
timeseriesPollPeriod 5000 Period in milliseconds for check the telemetry on device.
sendDataOnlyOnChange true Sending only if data changed from last check, if no – data will send after every check

Example:

  1.     "devices": [
  2.       {
  3.         "unitId": 1,
  4.         "deviceName": "Temp Sensor",
  5.         "attributesPollPeriod": 5000,
  6.         "timeseriesPollPeriod": 5000,
  7.         "sendDataOnlyOnChange": true,

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 test 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 1 Count of objects to read.
address 1 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:

  1.         "attributes": [
  2.           {
  3.             "tag": "test",
  4.             "type": "32int",
  5.             "functionCode": 4,
  6.             "objectsCount": 1,
  7.             "address": 1
  8.           }
  9.         ],

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

Example:

  1. "timeseries": [
  2.           {
  3.             "tag": "test",
  4.             "type": "16uint",
  5.             "functionCode": 4,
  6.             "objectsCount": 1,
  7.             "address": 1
  8.           }
  9.         ],

Key settings for “attributeUpdates”

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

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

Example:

  1. "attributeUpdates": [
  2.           {
  3.             "tag": "shared_attribute_write",
  4.             "type": "32int",
  5.             "functionCode": 6,
  6.             "objectsCount": 2,
  7.             "address": 1
  8.           }
  9.         ],

Key settings for “rpc”

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

Parameter Default value Description
tag setValue RPC method name.
type bits Type of value. Available data types
functionCode 5 Function to use in processing data. Modbus functions
objectsCount 1 Count of objects to write.
address 1 Object address.

Example:

  1. "rpc": [
  2.           {
  3.             "tag": "setValue",
  4.             "type": "bits",
  5.             "functionCode": 5,
  6.             "objectsCount": 1,
  7.             "address": 1
  8.           }
  9.         ],

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: