IoT Gateway
ThingsBoard Documentation
Cloud Professional Edition Community Edition Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Try it now Pricing
Documentation > Configuration guides > Modbus Connector
Getting Started
Installation

On this page

Modbus Connector Configuration


Note that the configuration of the Modbus connector has changed since Gateway 3.0. The new configuration will be generated after installing the new version and running Gateway in the new_modbus.json file.

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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
{
  "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:

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
  "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:

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

image

image

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        ...
        "timeseries": [
          {
            "tag": "telemetry_1",
            "type": "16uint",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 1
          },
          {
            "tag": "telemetry_2",
            "type": "16uint",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 3
          }
        ],
        ...

image

image

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:

1
2
3
4
5
6
7
8
9
10
11
        ...
        "attributeUpdates": [
          {
            "tag": "maxTemperature",
            "type": "16int",
            "functionCode": 16,
            "objectsCount": 1,
            "address": 29
          }
        ],
        ...

image

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

image

image

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:

1
2
3
4
5
6
7
8
9
10
11
        ...
        "rpc": [
          {
            "tag": "maxTemperature_read",
            "type": "16int",
            "functionCode": 3,
            "objectsCount": 1,
            "address": 29
          }
        ],
        ...

image

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

image

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:

There are 2 variants of server section:

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "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:

  1. holding_registers
  2. coils_initializer
  3. input_registers
  4. discrete_inputs

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
"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": []
        }
      ]
    }
  }
}


In this section of the configuration, the only difference is the placement of values to a certain type of register, but the configuration of telemetry, attributes, rps, etc. is the same as the “master” section.

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: