Skip to content

Commit cf8e813

Browse files
samson0vsamson0v
authored
Added a guide about how to connect Modbus device to TB CE (#2372)
1 parent 542029a commit cf8e813

File tree

8 files changed

+285
-3
lines changed

8 files changed

+285
-3
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -820,6 +820,7 @@ A list and description of the supported data types for reading/writing data.
820820

821821
Explore guides related to main ThingsBoard features:
822822

823+
- [How to connect Modbus device to ThingsBoard CE using ThingsBoard IoT Gateway](/docs/iot-gateway/guides/how-to-connect-modbus-device/)
823824
- [Data Visualization](/docs/user-guide/visualization/) - how to visualize collected data.
824825
- [Device attributes](/docs/user-guide/attributes/) - how to use device attributes.
825826
- [Telemetry data collection](/docs/user-guide/telemetry/) - how to collect telemetry data.

‎docs/iot-gateway/guides/how-to-connect-modbus-device.md‎

Lines changed: 284 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,290 @@
11
---
22
layout: docwithnav
33
assignees:
4-
- samson0v
5-
title: How to connect Modbus device to ThingsBoard using the ThingsBoard IoT Gateway
4+
- samson0v
5+
title: How to connect Modbus device to ThingsBoard CE?
66
description: Understand how to connect Modbus device to ThingsBoard using the ThingsBoard IoT Gateway
7-
redirect_to: "/docs/iot-gateway/config/modbus"
87

98
---
9+
10+
* TOC
11+
{:toc}
12+
13+
## Overview
14+
15+
In this guide, we will describe how to connect an Modbus device to ThingsBoard CE using ThingsBoard IoT Gateway.
16+
Whether you are just starting with Modbus protocol or looking to streamline your existing setup, this guide will
17+
provide you with the essential knowledge to get up and running quickly.
18+
19+
**What is ThingsBoard IoT Gateway?**
20+
21+
The ThingsBoard IoT Gateway is an open-source solution that serves as a bridge between IoT devices connected to
22+
legacy or third-party systems and the ThingsBoard platform. It enables seamless integration of devices that cannot
23+
communicate with ThingsBoard directly, ensuring data can be collected, processed, and visualized in real time. With
24+
the IoT Gateway, you can connect multiple devices, aggregate telemetry, and manage configurations centrally. It
25+
supports flexible deployment scenarios, making it especially suitable for industrial automation, monitoring, and smart
26+
energy systems where Modbus is widely used.
27+
28+
**What is Modbus?**
29+
30+
Modbus supports different communication modes, including serial (Modbus RTU and ASCII) and network-based (Modbus
31+
TCP/IP), making it adaptable to a wide range of industrial environments. Its simplicity and open standard have
32+
contributed to its widespread adoption, allowing devices from different manufacturers to communicate seamlessly. Despite
33+
being decades old, Modbus remains relevant today due to its reliability, ease of implementation, and compatibility with
34+
modern industrial systems. Additionally, it is often used as a backbone protocol for data acquisition, process
35+
monitoring, and control in applications ranging from manufacturing plants to building automation.
36+
37+
**What will You Learn?**
38+
39+
In this guide, we will walk you through the steps to connect a Modbus device to ThingsBoard CE using the ThingsBoard
40+
IoT Gateway. You will learn how to configure the gateway, set up the Modbus connector and map data points and send them
41+
to ThingsBoard. By the end of this guide, you will have a solid understanding of how to leverage the power of
42+
ThingsBoard IoT Gateway to integrate Modbus devices into your IoT ecosystem. By the end of this guide, you will have a
43+
working setup that allows you to seamlessly monitor and analyze your Modbus device data in ThingsBoard CE.
44+
45+
## Prerequisites
46+
47+
- Before initiating the Gateway setup, ensure that the ThingsBoard server is up and running. You can install ThingsBoard
48+
CE manually by following the steps outlined in
49+
the [Installation Guide](/docs/user-guide/install/installation-options/).
50+
- Before moving forward, ensure Docker is installed and properly configured on your machine. If you haven't installed
51+
Docker yet, you can download it from the [official Docker website](https://docs.docker.com/engine/install/) and follow
52+
their installation guide for your specific operating system.
53+
54+
## Modbus Device Structure Overview
55+
56+
For this guide, we will use a ThingsBoard Modbus Demo Device, which simulates a Modbus device and provides a
57+
convenient way to test and demonstrate Modbus communication with ThingsBoard. The demo device is pre-configured with a
58+
set of registers and data points that mimic the behavior of a real Modbus device. It allows users to interact with the
59+
device, read and write data, and observe how the data is processed and visualized in ThingsBoard.
60+
61+
The ThingsBoard Modbus Demo Device is designed to help users understand the Modbus protocol and how to integrate
62+
Modbus devices into their IoT solutions using ThingsBoard. It provides a practical and hands-on way to explore
63+
the capabilities of ThingsBoard in the context of Modbus communication.
64+
65+
The Modbus Demo Device has the following structure:
66+
67+
| Variable Name | Register Type | Data Type | Address |
68+
|:---------------|:----------------|------------|:-----------|
69+
| Temperature | Holding | 16int | 0 |
70+
| Humidity | Holding | 16int | 1 |
71+
| Power | Holding | 16int | 2 |
72+
| Pressure | Holding | 16int | 3 |
73+
| Relay | Coil | bits | 1 |
74+
| -------------- | --------------- | ---------- | ---------- |
75+
76+
To up and run the Modbus Demo Device, you can use Docker and the following command:
77+
78+
```bash
79+
docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest
80+
```
81+
{:.copy-code}
82+
83+
The server will be available at `0.0.0.0:5021`.
84+
85+
{% capture difference %}
86+
We will use `host.docker.internal` instead of `0.0.0.0` in our Gateway connector configuration to allow the Docker
87+
container to access another Docker container.
88+
{% endcapture %}
89+
{% include templates/info-banner.md content=difference %}
90+
91+
By working with the Demo Device and its registers, you'll see how to extract real-time telemetry data and then forward
92+
it to ThingsBoard for monitoring and analysis.
93+
94+
## Step 1. Create a new gateway device on ThingsBoard
95+
96+
First, add a gateway device to your ThingsBoard instance by following these steps:
97+
98+
{% assign createNewGatewayDevice = '
99+
===
100+
image: /images/gateway/dashboard/gateway-getting-started-1-ce.png,
101+
title: Go to "**Entities**" > "**Gateways**" tab.
102+
===
103+
image: /images/gateway/dashboard/gateway-getting-started-2-ce.png,
104+
title: Click the "**+**" button, enter the gateway device name (e.g., "My Gateway"), and select the device profile. Click on "**Create**" button.
105+
'
106+
%}
107+
108+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=createNewGatewayDevice %}
109+
110+
To launch the gateway, use the following steps:
111+
112+
{% assign remoteCreateGatewayDocker = '
113+
===
114+
image: /images/gateway/dashboard/gateway-getting-started-3-ce.png,
115+
title: Select and click on newly created gateway, click on **"Launch command"** button in the top right corner.
116+
===
117+
image: /images/gateway/dashboard/gateway-getting-started-4-ce.png,
118+
title: Click to download `docker-compose.yml` file to your PC, copy command and execute it in your terminal.
119+
'
120+
%}
121+
122+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=remoteCreateGatewayDocker %}
123+
124+
After running gateway docker image, you can see the following logs in your terminal:
125+
126+
![](/images/gateway/dashboard/launch-gateway-docker.png)
127+
128+
## Step 2. Add new Modbus connector
129+
130+
Let’s add a Modbus connector, which will read described before data from a simulated Modbus device to the
131+
created gateway. To create a connector, follow these steps:
132+
133+
{% assign addNewConnector = '
134+
===
135+
image: /images/gateway/dashboard/gateway-getting-started-7-ce.png,
136+
title: Click on "**Connectors configuration**" button on the right panel;
137+
===
138+
image: /images/gateway/dashboard/gateway-getting-started-8-ce.png,
139+
title: Click the "**+ Add connector**" button;
140+
===
141+
image: /images/gateway/dashboard/gateway-getting-started-modbus-9-ce.png,
142+
title: Choose "**Modbus**" connector type from the dropdown, fill in "**Name**" field, choose "**Logging level**" to "**INFO**", turn off the "**Fill configuration with default values**" option and click on "**Add**" button;
143+
===
144+
image: /images/gateway/modbus-connector/guides/connector-configuration.png,
145+
title: Choose “**Advanced**” configuration mode, click on “**Configuration**” tab and paste connector configuration (_you can find it under these steps_).
146+
===
147+
image: /images/gateway/modbus-connector/guides/connector-configuration-save.png,
148+
title: Click on “**Save**” button to apply changes.
149+
'
150+
%}
151+
152+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=addNewConnector %}
153+
154+
**Modbus connector configuration:**
155+
156+
```json
157+
{
158+
"master": {
159+
"slaves": [
160+
{
161+
"host": "host.docker.internal",
162+
"port": 5021,
163+
"type": "tcp",
164+
"method": "socket",
165+
"timeout": 35,
166+
"byteOrder": "BIG",
167+
"wordOrder": "LITTLE",
168+
"retries": true,
169+
"retryOnEmpty": true,
170+
"retryOnInvalid": true,
171+
"pollPeriod": 1000,
172+
"unitId": 1,
173+
"deviceName": "Modbus PLC",
174+
"deviceType": "default",
175+
"connectAttemptTimeMs": 5000,
176+
"connectAttemptCount": 5,
177+
"waitAfterFailedAttemptsMs": 300000,
178+
"attributes": [
179+
{
180+
"tag": "power",
181+
"type": "16int",
182+
"functionCode": 3,
183+
"objectsCount": 1,
184+
"address": 2,
185+
"divider": 10
186+
}
187+
],
188+
"timeseries": [
189+
{
190+
"tag": "temperature",
191+
"type": "16int",
192+
"functionCode": 3,
193+
"objectsCount": 1,
194+
"address": 0,
195+
"divider": 10
196+
},
197+
{
198+
"tag": "humidity",
199+
"type": "16int",
200+
"functionCode": 3,
201+
"objectsCount": 1,
202+
"address": 1,
203+
"divider": 10
204+
},
205+
{
206+
"tag": "pressure",
207+
"type": "16int",
208+
"functionCode": 3,
209+
"objectsCount": 1,
210+
"address": 3,
211+
"divider": 10
212+
},
213+
{
214+
"tag": "relay",
215+
"type": "bits",
216+
"functionCode": 1,
217+
"objectsCount": 1,
218+
"address": 1
219+
}
220+
],
221+
"attributeUpdates": [],
222+
"rpc": []
223+
}
224+
]
225+
}
226+
}
227+
```
228+
{:.copy-code.expandable-10}
229+
230+
Let’s break our connector configuration into smaller pieces and provide an explanation:
231+
232+
- `master.slaves` - a list of Modbus “devices” the gateway will talk to. We have just one.
233+
- `host: "host.docker.internal"` – the IP/hostname of the Modbus server. This value makes a Dockerized gateway reach your host machine.
234+
- `pollPeriod: 1000` – poll the device every 1000 ms (1 second).
235+
- `unitId: 1` – the Modbus unit/slave ID on the target (for TCP, this is still used by many gateways).
236+
- `deviceName: "Modbus PLC"` – the ThingsBoard device name that will receive the data.
237+
- `attributes` - a list of Modbus registers that will be read as device attributes in ThingsBoard.
238+
- `timeseries` - a list of Modbus registers that will be read as device telemetry in ThingsBoard.
239+
- `tag` - the key name that appears in ThingsBoard.
240+
- `type` - how to decode the raw data (e.g., 16int is a signed 16-bit integer; bits is a coil/bitfield).
241+
- `functionCode` - the Modbus function code to use when reading the data (e.g., 3 is for holding registers, 1 is for coils).
242+
- `address` - the Modbus address to read from (e.g., 0 for temperature, 1 for humidity, etc.).
243+
- `divider` - a modifier that divides the read value by 10 to get the actual value.
244+
245+
{% capture difference %}
246+
Additional information about the Modbus connector can be found [here](/docs/iot-gateway/config/modbus){:target="_blank"}.
247+
{% endcapture %}
248+
{% include templates/info-banner.md content=difference %}
249+
250+
## Step 3. Check device data
251+
252+
To review the data uploaded from your gateway, use the following step:
253+
254+
{% assign checkDeviceData = '
255+
===
256+
image: /images/gateway/modbus-connector/guides/review-device-data.png,
257+
title: Navigate to the **Entities** > **Devices** page and click on the created device "**Modbus PLC**" as we named it in the “**deviceName**” field . This will open the device details page. From there, switch to the **"Latest telemetry"** tab to view the real-time data that were configured in the connector.
258+
'
259+
%}
260+
261+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=checkDeviceData %}
262+
263+
## Conclusion
264+
265+
In this guide, we have walked you through the process of connecting a Modbus device to ThingsBoard CE using the
266+
ThingsBoard IoT Gateway. By following the steps outlined in this guide, you have successfully set up the gateway,
267+
configured the Modbus connector, and mapped data points to send telemetry and attributes to ThingsBoard. You have also
268+
learned how to monitor and visualize the data from your Modbus device in ThingsBoard CE.
269+
With the ThingsBoard IoT Gateway acting as a bridge between your Modbus device and ThingsBoard, you can now leverage
270+
the powerful features of ThingsBoard to analyze and manage your device data effectively. Whether you are monitoring
271+
environmental conditions, tracking energy consumption, or managing industrial processes, the integration of Modbus
272+
devices with ThingsBoard opens up new possibilities for data-driven decision-making and automation.
273+
274+
As you continue to explore the capabilities of ThingsBoard and the ThingsBoard IoT Gateway, you can further enhance your
275+
IoT solutions by adding more devices, implementing advanced data processing, and creating custom dashboards to visualize
276+
your data. The flexibility and scalability of ThingsBoard make it an ideal platform for building robust IoT
277+
applications.
278+
279+
We encourage you to experiment with different configurations, explore additional features of ThingsBoard IoT Gateway,
280+
and leverage the power of Modbus devices in your IoT projects. With the knowledge gained from this guide, you are
281+
well-equipped to take your IoT initiatives to the next level.
282+
283+
## Next steps
284+
285+
Explore guides related to main ThingsBoard features:
286+
- [Data Visualization](/docs/user-guide/visualization/) - how to visualize collected data.
287+
- [Device attributes](/docs/user-guide/attributes/) - how to use device attributes.
288+
- [Telemetry data collection](/docs/user-guide/telemetry/) - how to collect telemetry data.
289+
- [Using RPC capabilities](/docs/user-guide/rpc/) - how to send commands to/from devices.
290+
- [Rule Engine](/docs/user-guide/rule-engine/) - how to use rule engine to analyze data from devices.

‎images/gateway/modbus-connector/guides/connector-configuration-preview.png‎

16.2 KB
Loading

‎images/gateway/modbus-connector/guides/connector-configuration-save-preview.png‎

16 KB
Loading

‎images/gateway/modbus-connector/guides/connector-configuration-save.png‎

622 KB
Loading

‎images/gateway/modbus-connector/guides/connector-configuration.png‎

626 KB
Loading

‎images/gateway/modbus-connector/guides/review-device-data-preview.png‎

13.3 KB
Loading

‎images/gateway/modbus-connector/guides/review-device-data.png‎

427 KB
Loading

0 commit comments

Comments
 (0)