Skip to content

Added modbus batch reading overview with example #2382

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 3, 2025
Merged

Added modbus batch reading overview with example #2382

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e48ad8
Added modbus batch reading overview with example
samson0v Oct 14, 2025
0855070
Small fixes
samson0v Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions ...es/iot-gateway/modbus-connector/attributes-and-time-series-subsections-basic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,8 @@ For adding a new attribute or time series, use the following steps:
%}
{% include images-gallery.liquid showListImageTitles="true" imageCollection=attributes %}

##### Report strategy

You can enable a specific report strategy for each time series or attribute. This strategy defines how often
data is sent to the ThingsBoard server. The following strategies are available:

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

##### Modifier

Also, **modifier** for attribute/time series value can be applied using the following settings:

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

{% capture difference %}
More usage examples can be found in the [Example usage](/docs/iot-gateway/config/modbus/#usage-examples) section.
{% endcapture %}
{% include templates/info-banner.md content=difference %}

![image](/images/gateway/modbus-connector/modifier.png)

##### Batch reading (Advanced configuration mode only)

To optimize the reading process, you can group multiple registers into a single batch read request. This approach
reduces the number of requests sent to the Modbus server, which can enhance performance and decrease network traffic.
Take attention that the registers in a batch read request must be of the same type and function code.

Two parameters are important for group reading configuration: `address` and `tag`. Let's look at them in more detail:

- **address** - is the address of the starting register and the address of the ending register, separated by a `-`
character. For example, `0-10` means that the group read starts with the register at address `0` and ends at the
register at address `10`, inclusive.
- **tag** - is a unique identifier for each register within a group read. It is used to identify a specific register within
a given address range. The tag name can be formed using an expression using the following variables:
- `${address}` - register address within group read.
- `${unitId}` - slave ID.
- `${functionCode}` - function code.
- `${type}` - data type of register.
- `${objectsCount}` - number of objects.

Also, `divider` and `multiplier` parameters work as expected.

Example of group reading configuration:

```json
{
"tag": "${unitId} - ${type} - ${address}",
"type": "16int",
"functionCode": 3,
"objectsCount": 1,
"address": "0-10"
}
```

{% capture difference %}
More usage examples can be found in the [Example usage](/docs/iot-gateway/config/modbus/#usage-examples) section.
{% endcapture %}
{% include templates/info-banner.md content=difference %}
2 changes: 1 addition & 1 deletion ...es/iot-gateway/modbus-connector/examples/shared-attributes-rpc/rpc-to-device.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ Full configuration for Modbus connector for the example above will look like thi
{
"tag": "some_key",
"type": "16int",
"address": 1,
"address": 0,
"objectsCount": 1,
"functionCode": 3
}
Expand Down
82 changes: 82 additions & 0 deletions ...t-gateway/modbus-connector/examples/time-series-and-attributes/batch-reading.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
As an example, we will use ThingsBoard Modbus Demo Server, which can be run using Docker and the following command:

```bash
docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest
```
{:.copy-code}

The server available at `0.0.0.0:5021`. The server has the following structure:

| Variable Name | Register Type | Data Type | Address |
|:---------------|:----------------|------------|:-----------|
| Temperature | Holding | 16int | 0 |
| Humidity | Holding | 16int | 1 |
| Power | Holding | 16int | 2 |
| Pressure | Holding | 16int | 3 |
| Relay | Coil | bits | 1 |
| -------------- | --------------- | ---------- | ---------- |

For optimizing the number of requests sent to the Modbus server, you can use the **Batch reading** feature available
in the advanced configuration mode. This feature allows reading multiple registers in a single request, which can
significantly reduce the load on the Modbus server and improve performance.

Let’s look at an example of how to properly configure batch reading to read the `temperature`, `humidity`, `power`,
and `pressure` registers from the Modbus server.

From the table above, we can see that all the required registers are of the same type (`16int`) and have the same
function code (`03 - Read Holding Registers`). This means that we can group them into a single batch read request.
We need to read registers from address `0` to address `3`, so our address range will be `0-3`.
Also, you need to use, for examples `${address}` variable in the `tag` field to uniquely identify each register within
the batch read. In our case, we will use the following expression for the `tag` field:
`${unitId}.${type}.${address}` (you can find more information about variables in the corresponding [section of
the documentation](/docs/iot-gateway/config/modbus/#batch-reading-advanced-configuration-mode-only)).

Copy and paste the following configuration into the Modbus connector advanced configuration mode:

```json
{
"master": {
"slaves": [
{
"host": "0.0.0.0",
"port": 5021,
"type": "tcp",
"method": "socket",
"timeout": 35,
"byteOrder": "BIG",
"wordOrder": "LITTLE",
"retries": true,
"retryOnEmpty": true,
"retryOnInvalid": true,
"pollPeriod": 1000,
"unitId": 1,
"deviceName": "Demo Device",
"deviceType": "default",
"sendDataOnlyOnChange": true,
"connectAttemptTimeMs": 5000,
"connectAttemptCount": 5,
"waitAfterFailedAttemptsMs": 300000,
"attributes": [],
"timeseries": [
{
"tag": "${unitId}.${type}.${address}",
"type": "16int",
"functionCode": 3,
"objectsCount": 1,
"address": "0-3",
"divider": 10
}
],
"attributeUpdates": [],
"rpc": []
}
]
}
}
```
{:.copy-code}

After saving the changes and starting the connector, you see that the corresponding telemetry is being updated
correctly:

![image](/images/gateway/modbus-connector/examples/batch-reading-overview.png)
51 changes: 26 additions & 25 deletions docs/iot-gateway/config/modbus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ In the data mapping, you can specify how the Modbus master will interact with th
the slaves. You can also use this section to configure which data will be sent as device attributes or telemetry.
Data mapping contains all the necessary settings for flexible data management.

#### Subsection "Attributes" and "Time series"
#### Attributes and time series

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

Expand All @@ -133,7 +133,8 @@ Data mapping contains all the necessary settings for flexible data management.
{% capture modbus-attributes-timeseries-examples %}
Reading attributes/time series<small></small>%,%readingattributesandtimeseries%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/reading-attributes-and-time-series.md%br%
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%
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 %}
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%
Batch reading<small>(advanced configuration mode only)</small>%,%batchreading%,%templates/iot-gateway/modbus-connector/examples/time-series-and-attributes/batch-reading.md{% endcapture %}
{% include content-toggle.liquid content-toggle-id="modbus-attributes-timeseries-examples" toggle-spec=modbus-attributes-timeseries-examples %}

### Requests mapping
Expand Down Expand Up @@ -354,29 +355,29 @@ Example of the serial slave configuration:

##### Device attributes and time series

| **Parameter** | **Description** |
|:-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| server.slaves[].attributes[] | List of attributes that will be sent to the ThingsBoard platform instance. |
| server.slaves[].attributes[].tag | Key name of the attribute in ThingsBoard. It can be specified as a static value. |
| server.slaves[].attributes[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
| server.slaves[].attributes[].functionCode | [Function code](/docs/iot-gateway/config/modbus/#modbus-functions) to use for reading the attribute value from the Modbus slave. |
| server.slaves[].attributes[].objectsCount | Number of objects to read from the Modbus slave. |
| server.slaves[].attributes[].address | Address of the object in the Modbus slave. |
| server.slaves[].attributes[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
| server.slaves[].attributes[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
| server.slaves[].attributes[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the attributes data. If not specified, the device report strategy will be used. |
| server.slaves[].timeseries[] | List of time series that will be sent to the ThingsBoard platform instance. |
| server.slaves[].timeseries[].tag | Key name of the time series in ThingsBoard. It can be specified as a static value. |
| server.slaves[].timeseries[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
| 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. |
| server.slaves[].timeseries[].objectsCount | Number of objects to read from the Modbus slave. |
| server.slaves[].timeseries[].address | Address of the object in the Modbus slave. |
| server.slaves[].timeseries[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
| server.slaves[].timeseries[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
| server.slaves[].timeseries[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the time series data. If not specified, the device report strategy will be used. |
| --- | |
| **Parameter** | **Description** |
|:-------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| server.slaves[].attributes[] | List of attributes that will be sent to the ThingsBoard platform instance. |
| server.slaves[].attributes[].tag | Key name of the attribute in ThingsBoard. It can be specified as a static value. |
| server.slaves[].attributes[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
| server.slaves[].attributes[].functionCode | [Function code](/docs/iot-gateway/config/modbus/#modbus-functions) to use for reading the attribute value from the Modbus slave. |
| server.slaves[].attributes[].objectsCount | Number of objects to read from the Modbus slave. |
| 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). |
| server.slaves[].attributes[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
| server.slaves[].attributes[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
| server.slaves[].attributes[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the attributes data. If not specified, the device report strategy will be used. |
| server.slaves[].timeseries[] | List of time series that will be sent to the ThingsBoard platform instance. |
| server.slaves[].timeseries[].tag | Key name of the time series in ThingsBoard. It can be specified as a static value. |
| server.slaves[].timeseries[].type | [Data type](/docs/iot-gateway/config/modbus/#data-types) of value. |
| 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. |
| server.slaves[].timeseries[].objectsCount | Number of objects to read from the Modbus slave. |
| 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). |
| server.slaves[].timeseries[].divider | (Optional) Divider for the value. If not specified, the value will be sent as is. |
| server.slaves[].timeseries[].multiplier | (Optional) Multiplier for the value. If not specified, the value will be sent as is. |
| server.slaves[].timeseries[].bitTargetType | The response type can be either an integer (0/1) or a boolean (True/False). **Used only with type `bits`**. |
| mapping[].attributes[].reportStrategy | (Optional) Report strategy for the time series data. If not specified, the device report strategy will be used. |
| --- | |

Example of the attributes and telemetry configuration:

Expand Down
Binary file added images/gateway/modbus-connector/examples/batch-reading-overview.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.