Skip to content

Commit 370a552

Browse files
samson0vsamson0v
authored
Added modbus batch reading overview with example (#2382)
* Added modbus batch reading overview with example * Small fixes
1 parent aedcc5c commit 370a552

File tree

5 files changed

+156
-26
lines changed

5 files changed

+156
-26
lines changed

‎_includes/templates/iot-gateway/modbus-connector/attributes-and-time-series-subsections-basic.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ For adding a new attribute or time series, use the following steps:
3232
%}
3333
{% include images-gallery.liquid showListImageTitles="true" imageCollection=attributes %}
3434

35+
##### Report strategy
36+
3537
You can enable a specific report strategy for each time series or attribute. This strategy defines how often
3638
data is sent to the ThingsBoard server. The following strategies are available:
3739

@@ -45,6 +47,8 @@ Additional information about the report strategy can be found [here](/docs/iot-g
4547
{% endcapture %}
4648
{% include templates/info-banner.md content=difference %}
4749

50+
##### Modifier
51+
4852
Also, **modifier** for attribute/time series value can be applied using the following settings:
4953

5054
| **Parameter** | **Description** |
@@ -53,4 +57,47 @@ Also, **modifier** for attribute/time series value can be applied using the foll
5357
| Value | The value that will be used to modify the read value |
5458
| --- | |
5559

60+
{% capture difference %}
61+
More usage examples can be found in the [Example usage](/docs/iot-gateway/config/modbus/#usage-examples) section.
62+
{% endcapture %}
63+
{% include templates/info-banner.md content=difference %}
64+
5665
![image](/images/gateway/modbus-connector/modifier.png)
66+
67+
##### Batch reading (Advanced configuration mode only)
68+
69+
To optimize the reading process, you can group multiple registers into a single batch read request. This approach
70+
reduces the number of requests sent to the Modbus server, which can enhance performance and decrease network traffic.
71+
Take attention that the registers in a batch read request must be of the same type and function code.
72+
73+
Two parameters are important for group reading configuration: `address` and `tag`. Let's look at them in more detail:
74+
75+
- **address** - is the address of the starting register and the address of the ending register, separated by a `-`
76+
character. For example, `0-10` means that the group read starts with the register at address `0` and ends at the
77+
register at address `10`, inclusive.
78+
- **tag** - is a unique identifier for each register within a group read. It is used to identify a specific register within
79+
a given address range. The tag name can be formed using an expression using the following variables:
80+
- `${address}` - register address within group read.
81+
- `${unitId}` - slave ID.
82+
- `${functionCode}` - function code.
83+
- `${type}` - data type of register.
84+
- `${objectsCount}` - number of objects.
85+
86+
Also, `divider` and `multiplier` parameters work as expected.
87+
88+
Example of group reading configuration:
89+
90+
```json
91+
{
92+
"tag": "${unitId} - ${type} - ${address}",
93+
"type": "16int",
94+
"functionCode": 3,
95+
"objectsCount": 1,
96+
"address": "0-10"
97+
}
98+
```
99+
100+
{% capture difference %}
101+
More usage examples can be found in the [Example usage](/docs/iot-gateway/config/modbus/#usage-examples) section.
102+
{% endcapture %}
103+
{% include templates/info-banner.md content=difference %}

‎_includes/templates/iot-gateway/modbus-connector/examples/shared-attributes-rpc/rpc-to-device.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ Full configuration for Modbus connector for the example above will look like thi
8787
{
8888
"tag": "some_key",
8989
"type": "16int",
90-
"address": 1,
90+
"address": 0,
9191
"objectsCount": 1,
9292
"functionCode": 3
9393
}

‎_includes/templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/batch-reading.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:
2+
3+
```bash
4+
docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest
5+
```
6+
{:.copy-code}
7+
8+
The server available at `0.0.0.0:5021`. The server has the following structure:
9+
10+
| Variable Name | Register Type | Data Type | Address |
11+
|:---------------|:----------------|------------|:-----------|
12+
| Temperature | Holding | 16int | 0 |
13+
| Humidity | Holding | 16int | 1 |
14+
| Power | Holding | 16int | 2 |
15+
| Pressure | Holding | 16int | 3 |
16+
| Relay | Coil | bits | 1 |
17+
| -------------- | --------------- | ---------- | ---------- |
18+
19+
For optimizing the number of requests sent to the Modbus server, you can use the **Batch reading** feature available
20+
in the advanced configuration mode. This feature allows reading multiple registers in a single request, which can
21+
significantly reduce the load on the Modbus server and improve performance.
22+
23+
Let’s look at an example of how to properly configure batch reading to read the `temperature`, `humidity`, `power`,
24+
and `pressure` registers from the Modbus server.
25+
26+
From the table above, we can see that all the required registers are of the same type (`16int`) and have the same
27+
function code (`03 - Read Holding Registers`). This means that we can group them into a single batch read request.
28+
We need to read registers from address `0` to address `3`, so our address range will be `0-3`.
29+
Also, you need to use, for examples `${address}` variable in the `tag` field to uniquely identify each register within
30+
the batch read. In our case, we will use the following expression for the `tag` field:
31+
`${unitId}.${type}.${address}` (you can find more information about variables in the corresponding [section of
32+
the documentation](/docs/iot-gateway/config/modbus/#batch-reading-advanced-configuration-mode-only)).
33+
34+
Copy and paste the following configuration into the Modbus connector advanced configuration mode:
35+
36+
```json
37+
{
38+
"master": {
39+
"slaves": [
40+
{
41+
"host": "0.0.0.0",
42+
"port": 5021,
43+
"type": "tcp",
44+
"method": "socket",
45+
"timeout": 35,
46+
"byteOrder": "BIG",
47+
"wordOrder": "LITTLE",
48+
"retries": true,
49+
"retryOnEmpty": true,
50+
"retryOnInvalid": true,
51+
"pollPeriod": 1000,
52+
"unitId": 1,
53+
"deviceName": "Demo Device",
54+
"deviceType": "default",
55+
"sendDataOnlyOnChange": true,
56+
"connectAttemptTimeMs": 5000,
57+
"connectAttemptCount": 5,
58+
"waitAfterFailedAttemptsMs": 300000,
59+
"attributes": [],
60+
"timeseries": [
61+
{
62+
"tag": "${unitId}.${type}.${address}",
63+
"type": "16int",
64+
"functionCode": 3,
65+
"objectsCount": 1,
66+
"address": "0-3",
67+
"divider": 10
68+
}
69+
],
70+
"attributeUpdates": [],
71+
"rpc": []
72+
}
73+
]
74+
}
75+
}
76+
```
77+
{:.copy-code}
78+
79+
After saving the changes and starting the connector, you see that the corresponding telemetry is being updated
80+
correctly:
81+
82+
![image](/images/gateway/modbus-connector/examples/batch-reading-overview.png)

‎docs/iot-gateway/config/modbus.md‎

Lines changed: 26 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ In the data mapping, you can specify how the Modbus master will interact with th
124124
the slaves. You can also use this section to configure which data will be sent as device attributes or telemetry.
125125
Data mapping contains all the necessary settings for flexible data management.
126126

127-
#### Subsection "Attributes" and "Time series"
127+
#### Attributes and time series
128128

129129
{% include /templates/iot-gateway/modbus-connector/attributes-and-time-series-subsections-basic.md %}
130130

@@ -133,7 +133,8 @@ Data mapping contains all the necessary settings for flexible data management.
133133
{% capture modbus-attributes-timeseries-examples %}
134134
Reading attributes/time series<small></small>%,%readingattributesandtimeseries%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/reading-attributes-and-time-series.md%br%
135135
Multiplier<small>in attributes/time series</small>%,%multiplierinattributesandtimeseries%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/multiplier-in-attributes-and-time-series.md%br%
136-
Divider<small>in attributes/time series</small>%,%dividerinattributesandtimeseries%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/divider-in-attributes-and-time-series.md{% endcapture %}
136+
Divider<small>in attributes/time series</small>%,%dividerinattributesandtimeseries%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/divider-in-attributes-and-time-series.md%br%
137+
Batch reading<small>(advanced configuration mode only)</small>%,%batchreading%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/batch-reading.md{% endcapture %}
137138
{% include content-toggle.liquid content-toggle-id="modbus-attributes-timeseries-examples" toggle-spec=modbus-attributes-timeseries-examples %}
138139

139140
### Requests mapping
@@ -354,29 +355,29 @@ Example of the serial slave configuration:
354355

355356
##### Device attributes and time series
356357

357-
| **Parameter** | **Description** |
358-
|:-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
359-
| server.slaves[].attributes[] | List of attributes that will be sent to the ThingsBoard platform instance. |
360-
| server.slaves[].attributes[].tag | Key name of the attribute in ThingsBoard. It can be specified as a static value. |
361-
| server.slaves[].attributes[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
362-
| server.slaves[].attributes[].functionCode | [Function code](/docs/iot-gateway/config/modbus/#modbus-functions) to use for reading the attribute value from the Modbus slave. |
363-
| server.slaves[].attributes[].objectsCount | Number of objects to read from the Modbus slave. |
364-
| server.slaves[].attributes[].address | Address of the object in the Modbus slave. |
365-
| server.slaves[].attributes[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
366-
| server.slaves[].attributes[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
367-
| server.slaves[].attributes[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
368-
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the attributes data. If not specified, the device report strategy will be used. |
369-
| server.slaves[].timeseries[] | List of time series that will be sent to the ThingsBoard platform instance. |
370-
| server.slaves[].timeseries[].tag | Key name of the time series in ThingsBoard. It can be specified as a static value. |
371-
| server.slaves[].timeseries[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
372-
| server.slaves[].timeseries[].functionCode | [Function code](/docs/iot-gateway/config/modbus/#modbus-functions) to use for reading the time series value from the Modbus slave. |
373-
| server.slaves[].timeseries[].objectsCount | Number of objects to read from the Modbus slave. |
374-
| server.slaves[].timeseries[].address | Address of the object in the Modbus slave. |
375-
| server.slaves[].timeseries[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
376-
| server.slaves[].timeseries[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
377-
| server.slaves[].timeseries[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
378-
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the time series data. If not specified, the device report strategy will be used. |
379-
| --- | |
358+
| **Parameter** | **Description** |
359+
|:-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
360+
| server.slaves[].attributes[] | List of attributes that will be sent to the ThingsBoard platform instance. |
361+
| server.slaves[].attributes[].tag | Key name of the attribute in ThingsBoard. It can be specified as a static value. |
362+
| server.slaves[].attributes[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
363+
| server.slaves[].attributes[].functionCode | [Function code](/docs/iot-gateway/config/modbus/#modbus-functions) to use for reading the attribute value from the Modbus slave. |
364+
| server.slaves[].attributes[].objectsCount | Number of objects to read from the Modbus slave. |
365+
| server.slaves[].attributes[].address | Address of the object in the Modbus slave. Can be configured for [batch reading](/docs/iot-gateway/config/modbus/#batch-reading-advanced-configuration-mode-only). |
366+
| server.slaves[].attributes[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
367+
| server.slaves[].attributes[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
368+
| server.slaves[].attributes[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
369+
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the attributes data. If not specified, the device report strategy will be used. |
370+
| server.slaves[].timeseries[] | List of time series that will be sent to the ThingsBoard platform instance. |
371+
| server.slaves[].timeseries[].tag | Key name of the time series in ThingsBoard. It can be specified as a static value. |
372+
| server.slaves[].timeseries[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
373+
| server.slaves[].timeseries[].functionCode | [Function code](/docs/iot-gateway/config/modbus/#modbus-functions) to use for reading the time series value from the Modbus slave. |
374+
| server.slaves[].timeseries[].objectsCount | Number of objects to read from the Modbus slave. |
375+
| server.slaves[].timeseries[].address | Address of the object in the Modbus slave. Can be configured for [batch reading](/docs/iot-gateway/config/modbus/#batch-reading-advanced-configuration-mode-only). |
376+
| server.slaves[].timeseries[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
377+
| server.slaves[].timeseries[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
378+
| server.slaves[].timeseries[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
379+
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the time series data. If not specified, the device report strategy will be used. |
380+
| --- | |
380381

381382
Example of the attributes and telemetry configuration:
382383

‎images/gateway/modbus-connector/examples/batch-reading-overview.png‎

423 KB
Loading

0 commit comments

Comments
 (0)