Skip to content
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.

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

Gateway. Modbus Connector Configuration. Updated guide #1726

Open
wants to merge 1 commit into
base: develop/3.9
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
You can configure additional settings like: TLS connection, polling time, byte order and word order, and other. The table below describes the parameters for this purpose:

| **Parameter** | **Default value** | **Description** |
|:--------------------------|:-------------------|-------------------------------------------------------------------------------
| timeout | **35** | Timeout in seconds for connecting to Modbus server |
| byteOrder | **LITTLE** | Order of bytes to read |
| wordOrder | **LITTLE** | The order of words when reading several registers |
| retries | **true** | Retrying sending data to the master. The values can be either: true or false |
| retriesOnEmpty | **true** | Retrying sending data to the master if it is empty |
| retriesOnInvalid | **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 |
| 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 |
| ---

![image](/images/gateway/modbus-connector/advanced-connection-settings-advanced-1-ce.png)

<br>
Example:

```json
"master": {
"slaves": [
{
"timeout": 35,
"byteOrder": "LITTLE",
"wordOrder": "LITTLE",
"retries": true,
"retryOnEmpty": true,
"retryOnInvalid": true,
"pollPeriod": 5000,
"sendDataOnlyOnChange": true,
"connectAttemptTimeMs": 5000,
"connectAttemptCount": 5,
"waitAfterFailedAttemptsMs": 300000,
}
]
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
You can configure additional settings like: TLS connection, byte order, word order, and other. The table below describes the parameters for this purpose:

| **Parameter** | **Description** |
|:----------------|:----------------
| Byte order | LITTLE |
| Word order | LITTLE |
| Vendor name | |
| Product code | |
| Vendor URL | |
| Product name | |
| Model name | |
| ---

![image](/images/gateway/modbus-connector/advanced-connection-settings-slave-advanced-1-ce.png)
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
You can configure additional settings like: TLS connection, polling time, byte order and word order, and other. The table below describes the parameters for this purpose:

| **Parameter** | **Default value** | **Description** |
|:------------------------------------|:-------------------|-------------------------------------------------------------------------------
| Connection timeout (s) | **35** | Timeout in seconds for connecting to Modbus server |
| Byte order | **LITTLE** | Order of bytes to read |
| Word order | **LITTLE** | The order of words when reading several registers |
| Retries | **true** | Retrying sending data to the master. The values can be either: true or false |
| Retries on empty | **true** | Retrying sending data to the master if it is empty |
| Retries on invalid | **true** | Retrying sending data to the master if it is failed |
| Poll period (ms) | **5000** | Period in milliseconds to check the attributes and the telemetry on the slave |
| Connect attempt time (ms) | **5000** | A waiting period in milliseconds before connecting to the master |
| Connect attempt count | **5** | The number of connection attempts made through the ThingsBoard gateway |
| Wait after failed attempts (ms) | **300000** | A waiting period in milliseconds before trying to send data to the master |
| ---

{% assign advancedConnectionSettings = '
===
image: /images/gateway/modbus-connector/advanced-connection-settings-1-ce.png,
title: Click on the "**Advanced connection settings**" subsection to open it;
===
image: /images/gateway/modbus-connector/advanced-connection-settings-2-ce.png,
title: Make the necessary settings.
'
%}
{% include images-gallery.liquid showListImageTitles="true" imageCollection=advancedConnectionSettings %}

Also, you can configure TLS connection (can be used only for TCP/UDP connection type). The table below describes the parameters required to configure TLS connection:

| **Parameter** | **Description** |
|:--------------------------------|:------------------------------------------------------------
| Path to client certificate file | Path to certificate file in filesystem with gateway |
| Path to private key file | Path to private key file |
| Password | Server password |
| Server hostname | Server hostname (Should match with hostname in certificate) |
| ---

![image](/images/gateway/modbus-connector/tls-connection.png)
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
You can configure additional settings like: TLS connection, byte order, word order, and other. The table below describes the parameters for this purpose:

| **Parameter** | **Description** |
|:----------------|:----------------
| Byte order | LITTLE |
| Word order | LITTLE |
| Vendor name | |
| Product code | |
| Vendor URL | |
| Product name | |
| Model name | |
| ---

{% assign advancedConnectionSettingsBasic = '
===
image: /images/gateway/modbus-connector/advanced-connection-settings-basic-1-ce.png,
title: Click on the "**Advanced connection settings**" subsection to open it;
===
image: /images/gateway/modbus-connector/advanced-connection-settings-basic-2-ce.png,
title: Make the necessary settings.
'
%}

{% include images-gallery.liquid showListImageTitles="true" imageCollection=advancedConnectionSettingsBasic %}
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
The table below describes the attribute updates parameters:

| **Parameter** | **Description** |
|:--------------|:----------------------------------------------------------------------
| tag | Shared attribute name |
| type | Type of value |
| functionCode | The function to use in data processing, specifically Modbus functions |
| objectsCount | Count of objects to write |
| address | Object address |
| ---

![image](/images/gateway/modbus-connector/attribute-updates-advanced-1-ce.png)

<br>
Example:

```json
"attributeUpdates": [
{
"tag": "shared_attribute_write",
"type": "32int",
"functionCode": 6,
"objectsCount": 2,
"address": 29
}
]
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{% assign attributeUpdatesSubsection = '
===
image: /images/gateway/modbus-connector/attribute-updates-1-ce.png,
title: To add new requests mapping, navigate to the "Attribute updates" section and click the "pencil" icon;
===
image: /images/gateway/modbus-connector/attribute-updates-2-ce.png,
title: In the opened window click "Add attribute update";
===
image: /images/gateway/modbus-connector/attribute-updates-3-ce.png,
title: Set an attribute key name, type, function code, objects count, and address. Then, click "Apply".
'
%}
{% include images-gallery.liquid showListImageTitles="true" imageCollection=attributeUpdatesSubsection %}

The table below describes the attribute updates parameters:

| **Parameter** | **Description** |
|:--------------|:----------------------------------------------------------------------
| Key | Shared attribute name |
| Type | Type of value |
| Function code | The function to use in data processing, specifically Modbus functions |
| Objects count | Count of objects to write |
| Address | Object address |
| ---

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

{% assign maxTemperatureAttribute = '
===
image: /images/gateway/modbus-connector/max-temperature-attribute-1-ce.png,
title: Go to the "Devices" page. Click on your device to open the device details, then navigate to the "Attributes" tab. Select "Server attributes" as the entity attributes scope. Then, click the "plus" icon to add a new attribute;
===
image: /images/gateway/modbus-connector/max-temperature-attribute-2-ce.png,
title: Name the attribute "maxTemperature", select "Integer" as the value type, and set the value to 25;
===
image: /images/gateway/modbus-connector/max-temperature-attribute-3-ce.png,
title: Shared attribute is added.
'
%}
{% include images-gallery.liquid showListImageTitles="true" imageCollection=maxTemperatureAttribute %}
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
The configuration in this unit provides settings for processing data on Modbus server. These settings will be interpreted in ThingsBoard platform instance as attributes/time series of the device.

The table below describes the attributes and time series parameters:

| **Parameter** | **Description** |
|:--------------|:----------------------------------------------------------------------
| tag | Key name |
| type | Type of value |
| functionCode | The function to use in data processing, specifically Modbus functions |
| objectsCount | Count of objects to write |
| address | Object address |
| ---

![image](/images/gateway/modbus-connector/attributes-advanced-1-ce.png)

<br>
Example of attributes section:

```json
"attributes": [
{
"tag": "string_read",
"type": "string",
"functionCode": 4,
"objectsCount": 4,
"address": 1
}
]
```

Example of time series section:

```json
"timeseries": [
{
"tag": "16uint_read",
"type": "16uint",
"functionCode": 4,
"objectsCount": 2,
"address": 18
},
]
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
The configuration in this unit provides settings for processing data on Modbus server. These settings will be interpreted in ThingsBoard platform instance as attributes/time series of the device. For adding new attribute or time series use the following steps:

{% assign attributes = '
===
image: /images/gateway/modbus-connector/attributes-1-ce.png,
title: Click on "**pencil**" icon in the "Attributes" or "**Time series**" section (depends on the selected section);
===
image: /images/gateway/modbus-connector/attributes-2-ce.png,
title: In the opened window click "**Add attribute**" or "**Add time series**" (depends on selected section);
===
image: /images/gateway/modbus-connector/attributes-3-ce.png,
title: Fill in key, type, function code, objects count and address fields. Click "Apply".
'
%}

{% include images-gallery.liquid showListImageTitles="true" imageCollection=attributes %}

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

| **Parameter** | **Description** |
|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
| Type | **multiplier** - the result of reading will be multiplied by the value of this parameter. <br>**divider** - the result of reading will be divided by the value of this parameter |
| Value | The value that will be used to modify the read value |
| ---

![image](/images/gateway/modbus-connector/modifier.png)
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
To add new configuration for connection to server, navigate to the "Configuration" tab.

![image](/images/gateway/modbus-connector/add-new-server-connection-advanced-1-ce.png)

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.

{% capture modbusMasterConnectionsUDPTCPSerial %}
TCP<small></small>%,%tcp%,%templates/iot-gateway/modbus-connector/tcp-master-connections-section-advanced.md%br%
UDP<small></small>%,%udp%,%templates/iot-gateway/modbus-connector/udp-master-connections-section-advanced.md%br%
Serial<small></small>%,%serial%,%templates/iot-gateway/modbus-connector/serial-master-connections-section-advanced.md{% endcapture %}
{% include content-toggle.liquid content-toggle-id="modbusMasterConnectionsUDPTCPSerial" toggle-spec=modbusMasterConnectionsUDPTCPSerial %}
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
To add new configuration for connection to server, navigate to the "Master Connections" tab and click the "plus" icon:

![image](/images/gateway/modbus-connector/add-new-server-connection-1-ce.png)

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.

{% capture modbusMasterConnectionsUDPTCPSerial %}
TCP<small></small>%,%tcp%,%templates/iot-gateway/modbus-connector/tcp-master-connections-section.md%br%
UDP<small></small>%,%udp%,%templates/iot-gateway/modbus-connector/udp-master-connections-section.md%br%
Serial<small></small>%,%serial%,%templates/iot-gateway/modbus-connector/serial-master-connections-section.md{% endcapture %}
{% include content-toggle.liquid content-toggle-id="modbusMasterConnectionsUDPTCPSerial" toggle-spec=modbusMasterConnectionsUDPTCPSerial %}
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
![image](/images/gateway/modbus-connector/modbus-report-strategy-subsection-advanced.png)

This subsection enabling report strategy for data sending, and you can use one of 3 behavior scenarios:

- ON_REPORT_PERIOD - data will be collected and send every period of time (in milliseconds).
- ON_CHANGE - data will be send after change.
- ON_CHANGE_OR_REPORT_PERIOD - data will be sent either when it changes or after a report period has passed since the last time it was sent.

The table below describes the parameters required to configure report strategy:

| **Parameter** | **Default value** | **Description** |
|:--------------|:---------------------|-------------------------------------------------------------------------------------------
| type | **ON_REPORT_PERIOD** | Report strategy type: ON_REPORT_PERIOD, ON_CHANGE_OR_REPORT_PERIOD, ON_CHANGE|
| reportPeriod | **30000** | Period in milliseconds to send data to platform |
| ---

Configuration example:

```text
reportStrategy: {
"type": "ON_REPORT_PERIOD",
"reportPeriod": 30000
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
![image](/images/gateway/modbus-connector/modbus-report-strategy-subsection-basic.png)

This subsection enabling report strategy for data sending, and you can use one of 3 behavior scenarios:

- On report period - data will be collected and send every period of time (in milliseconds).
- On value change - data will be send after change.
- On value change or report period - data will be sent either when it changes or after a report period has passed since the last time it was sent.

The table below describes the parameters required to configure report strategy:

| **Parameter** | **Default value** | **Description** |
|:--------------|:---------------------|-------------------------------------------------------------------------------------------
| Type | **On report period** | Report strategy type: On report period, On value change, On value change or report period |
| Report period | **30000** | Period in milliseconds to send data to platform |
| ---
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
The table below describes the RPC request parameters:

| **Parameter** | **Description** |
|:--------------|:----------------------------------------------------------------------
| tag | RPC method name |
| type | Type of value |
| functionCode | The function to use in data processing, specifically Modbus functions |
| objectsCount | Count of objects to write or read |
| address | Object address |
| ---

![image](/images/gateway/modbus-connector/rpc-requests-advanced-1-ce.png)

<br>
Example:

```json
"rpc": [
{
"tag": "setValue",
"type": "bits",
"functionCode": 5,
"objectsCount": 1,
"address": 31
}
]
```
Loading