- Section “master”: description and configuration parameters
- Section “slave”: description and configuration parameters
- Additional information
- Next steps
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. The connector configuration file will be described below.
Example of Modbus Connector config file.
Section “master”: description and configuration parameters
A Modbus Master is used to query data from devices. In order to configure the slaves that the master must query, you need to specify the “master” section which includes the “slaves” list.
Subsection “slaves”
This subsection provides an 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:
Also, you can configure TLS connection using the following configuration:
Configuration example: |
|
The next part of the slave section contains common connection parameters and settings for data processing. The available parameters are as follows:
| Parameter | Default value | Description |
|---|---|---|
| retries | true | Retrying sending data to the master. The values can be either: 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 to check the attributes and the telemetry on the slave |
| unitId | 1 | Id of current slave on Modbus. |
| deviceName | Demo Device | Name of the current slave |
| deviceType | default | Type of the current slave |
| sendDataOnlyOnChange | false | Sending only if data has changed since the last check. If not, data will be sent after every check |
| connectAttemptTimeMs | 5000 | A waiting period in milliseconds before connecting to the master |
| connectAttemptCount | 5 | The number of connection attempts made through the ThingsBoard gateway |
| waitAfterFailedAttemptsMs | 300000 | A waiting period in milliseconds 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": "host.docker.internal",
"port": 5021,
"type": "tcp",
"method": "socket",
"timeout": 35,
"byteOrder": "LITTLE",
"wordOrder": "LITTLE",
"retries": true,
"retryOnEmpty": true,
"retryOnInvalid": true,
"pollPeriod": 5000,
"unitId": 1,
"deviceName": "Demo Device",
"deviceType": "default",
"sendDataOnlyOnChange": false,
"connectAttemptTimeMs": 5000,
"connectAttemptCount": 5,
"waitAfterFailedAttemptsMs": 300000
}
]
}
}
Key settings for “attributes”
The configuration in this unit provides settings for processing data on Modbus server. These settings will be interpreted in ThingsBoard platform instance as attributes of the device.
| Parameter | Default value | Description |
|---|---|---|
| tag | certificateNumber | Tag, which will be used as attribute key for ThingsBoard platform instance |
| type | 32int | Type of value. Available data types |
| functionCode | 4 | The function to use in data processing, specifically Modbus functions |
| objectsCount | 2 | Count of objects to read. |
| address | 0 | Object address to check. |
Optional parameters:
multiplier - the result of reading will be multiplied by the value of this parameter.
divider - the result of reading will be divided by the 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
}
],
...
Key settings for “timeseries”
The configuration in this unit provides settings for processing data on Modbus server. These settings will be interpreted in ThingsBoard platform instance as telemetry of the device.
| Parameter | Default value | Description |
|---|---|---|
| tag | telemetry_1 | Tag, which will be used as attribute key for ThingsBoard platform instance. |
| type | 16uint | Type of value. Available data types |
| functionCode | 4 | The function to use in data processing, specifically Modbus functions |
| objectsCount | 1 | Count of objects to read. |
| address | 1 | Object address to check. |
| tag | telemetry_2 | Tag, which will be used as attribute key for ThingsBoard platform instance. |
| type | 16uint | Type of value. Available data types |
| functionCode | 4 | The function to use in data processing, specifically 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
}
],
...
Key settings for “attributeUpdates”
The 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 | The function to use in data processing, specifically 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
}
],
...
For example, create a new attribute “maxTemperature” and give it a value “25”.
Key settings for “RPC”
The configuration in this unit provides settings for RPC requests from ThingsBoard platform instance to the device.
| Parameter | Default value | Description |
|---|---|---|
| tag | maxTemperature_read | RPC method name. |
| type | 16int | Type of value. Available data types |
| functionCode | 3 | The function to use in data processing, specifically 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
}
],
...
To send RPC requests to the gateway, use the RPC Debug Terminal from the 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:
Also, you can configure TLS connection using the following configuration:
Configuration example: |
|
Don’t use “Gateway” as the value of “deviceName” parameter!
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:
- 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:
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 in the placement of values to a certain type of register. However, the configuration of telemetry, attributes, RPCs, etc., remains the same as in the “master” section.
Additional information
Here’s more details regarding Modbus functions and the 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 the objects count is 1, result will be interpreted as a boolean. Otherwise 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.