Skip to content

Commit 2e16192

Browse files
ashvaykaashvayka
committed
Merge branch 'staging/4.2' into release/4.2
2 parents fded25f + d212354 commit 2e16192

13 files changed

Lines changed: 271 additions & 166 deletions

‎docs/iot-gateway/config/opc-ua.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -594,6 +594,7 @@ byte string (`b`), and GUID (`g`). Below is an explanation of each identifier ty
594594
## Next steps
595595

596596
Explore guides related to main ThingsBoard features:
597+
- [How to connect OPC-UA device to ThingsBoard CE using ThingsBoard IoT Gateway](/docs/iot-gateway/guides/how-to-connect-opc-ua-device-to-thingsboard-ce/)
597598
- [ThingsBoard IoT Gateway Features](/docs/iot-gateway/features/)
598599
- [Data Visualization](/docs/user-guide/visualization/) - how to visualize collected data.
599600
- [Device attributes](/docs/user-guide/attributes/) - how to use device attributes.

‎docs/iot-gateway/guides/how-to-connect-opc-ua-device-to-thingsboard-ce.md‎

Lines changed: 270 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,270 @@
1+
---
2+
layout: docwithnav-gw
3+
title: How to connect OPC-UA device to ThingsBoard CE?
4+
description: Understand how to connect OPC-UA device to ThingsBoard CE using ThingsBoard IoT Gateway
5+
6+
---
7+
8+
* TOC
9+
{:toc}
10+
11+
## Overview
12+
13+
In this guide, we will describe how to connect an OPC-UA device to ThingsBoard CE using ThingsBoard IoT Gateway.
14+
Whether you are just starting with OPC-UA integration or looking to streamline your existing setup, this guide will
15+
provide you with the essential knowledge to get up and running quickly.
16+
17+
**What is ThingsBoard IoT Gateway?**
18+
19+
The ThingsBoard IoT Gateway is an open-source solution that serves as a bridge between IoT devices connected to
20+
legacy or third-party systems and the ThingsBoard platform. It enables seamless integration of devices that cannot
21+
communicate with ThingsBoard directly, ensuring data can be collected, processed, and visualized in real time. With
22+
the IoT Gateway, you can connect multiple devices, aggregate telemetry, and manage configurations centrally. It
23+
supports flexible deployment scenarios, making it especially suitable for industrial automation, monitoring, and smart
24+
energy systems where OPC-UA is widely used.
25+
26+
**What is OPC-UA?**
27+
28+
OPC Unified Architecture (OPC-UA) is a machine-to-machine communication protocol widely adopted in industrial
29+
automation. It provides a platform-independent, secure, and reliable framework for exchanging data between devices,
30+
servers, and applications. Unlike older OPC standards, OPC-UA supports modern technologies, allows structured data
31+
modeling, and is designed for scalability across different platforms and networks. Its robustness and interoperability
32+
make it a standard choice for industries that require consistent, real-time, and vendor-neutral communication.
33+
34+
**What will You Learn?**
35+
36+
In this guide, we will walk step by step through the process of integrating an OPC-UA device with ThingsBoard CE. You
37+
will learn how to install and configure the ThingsBoard IoT Gateway, set up the OPC-UA connector, and establish a
38+
connection to your OPC-UA server. We will also demonstrate how to map data points, send telemetry to ThingsBoard.
39+
By the end of this guide, you will have a working setup that allows you to seamlessly monitor and analyze your OPC-UA
40+
device data in ThingsBoard CE.
41+
42+
## Prerequisites
43+
44+
- Before initiating the Gateway setup, ensure that the ThingsBoard server is up and running. You can install ThingsBoard
45+
CE manually by following the steps outlined in
46+
the [Installation Guide](/docs/user-guide/install/installation-options/).
47+
- Before moving forward, ensure Docker is installed and properly configured on your machine. If you haven't installed
48+
Docker yet, you can download it from the [official Docker website](https://docs.docker.com/engine/install/) and follow
49+
their installation guide for your specific operating system.
50+
51+
## OPC-UA Server Structure Overview
52+
53+
For this guide, we’ll use the Prosys OPC-UA Simulation Server as our example OPC-UA device. It’s available at:
54+
55+
```bash
56+
opc.tcp://0.0.0.0:53530/OPCUA/SimulationServer
57+
```
58+
59+
{% capture difference %}
60+
We will use `host.docker.internal` instead of `0.0.0.0` in our Gateway connector configuration to allow the Docker
61+
container to access the host machine's network.
62+
{% endcapture %}
63+
{% include templates/info-banner.md content=difference %}
64+
65+
This simulation server provides a predefined set of nodes that we can use to mimic a real industrial device.
66+
Its structure looks like this:
67+
68+
![image](https://img.thingsboard.io/gateway/opc-ua-connector/guides/opc-ua-server-structure-overview.png)
69+
70+
In our example, we’ll focus on the following nodes:
71+
72+
- `Root.Objects.OPC-UA_PLC` - the parent device node that contains all related data points:
73+
- Root.Objects.OPC-UA_PLC.`Humidity` - represents humidity value. We’ll map this node to ThingsBoard CE as a
74+
time-series value.
75+
- Root.Objects.OPC-UA_PLC.`Temperature` - represents temperature value. We’ll also send this value to ThingsBoard CE
76+
as a time-series value.
77+
- Root.Objects.OPC-UA_PLC.`Pressure` - represents pressure measurements, which will be stored in ThingsBoard CE as a
78+
time-series value.
79+
- Root.Objects.OPC-UA_PLC.`FirmwareInformation` - a child node that holds metadata about the device firmware:
80+
- Root.Objects.OPC-UA_PLC.FirmwareInformation.`Version` - the firmware version number. We’ll map this to ThingsBoard
81+
CE as a device attribute.
82+
- Root.Objects.OPC-UA_PLC.FirmwareInformation.`UpdatedDate` - the last time the firmware was updated. This will also
83+
be sent to ThingsBoard CE as a device attribute.
84+
85+
By working with these nodes, you’ll see how to extract both real-time telemetry data (Humidity, Temperature, Pressure)
86+
and static attributes (firmware details) from an OPC-UA device, and then forward them into ThingsBoard CE for
87+
monitoring and visualization.
88+
89+
## Step 1. Create a new gateway device on ThingsBoard
90+
91+
First, add a gateway device to your ThingsBoard instance by following these steps:
92+
93+
{% assign createNewGatewayDevice = '
94+
===
95+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-1-ce.png,
96+
title: Go to "**Entities**" > "**Gateways**" tab.
97+
===
98+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-2-ce.png,
99+
title: Click the "**+**" button, enter the gateway device name (e.g., "My Gateway"), and select the device profile. Click on "**Create**" button.
100+
'
101+
%}
102+
103+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=createNewGatewayDevice %}
104+
105+
To launch the gateway, use the following steps:
106+
107+
{% assign remoteCreateGatewayDocker = '
108+
===
109+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-3-ce.png,
110+
title: Select and click on newly created gateway, click on **"Launch command"** button in the top right corner.
111+
===
112+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-4-ce.png,
113+
title: Click to download `docker-compose.yml` file to your PC, copy command and execute it in your terminal.
114+
'
115+
%}
116+
117+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=remoteCreateGatewayDocker %}
118+
119+
After running gateway docker image, you can see the following logs in your terminal:
120+
121+
![](https://img.thingsboard.io/gateway/dashboard/launch-gateway-docker.png)
122+
123+
## Step 2. Add new OPC-UA connector
124+
125+
Let’s add an OPC-UA connector, which will read described before data from a simulated OPC-UA device to the
126+
created gateway. To create a connector, follow these steps:
127+
128+
{% assign addNewConnector = '
129+
===
130+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-7-ce.png,
131+
title: Click on "**Connectors configuration**" button on the right panel;
132+
===
133+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-8-ce.png,
134+
title: Click the "**+ Add connector**" button;
135+
===
136+
image: https://img.thingsboard.io/gateway/dashboard/gateway-getting-started-opc-ua-9-ce.png,
137+
title: Choose "**OPCUA**" 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;
138+
===
139+
image: https://img.thingsboard.io/gateway/opc-ua-connector/guides/connector-configuration.png,
140+
title: Choose “**Advanced**” configuration mode, click on “**Configuration**” tab and paste connector configuration (_you can find it under these steps_).
141+
===
142+
image: https://img.thingsboard.io/gateway/opc-ua-connector/guides/connector-configuration-save.png,
143+
title: Click on “**Save**” button to apply changes.
144+
'
145+
%}
146+
147+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=addNewConnector %}
148+
149+
**OPC-UA configuration:**
150+
151+
```json
152+
{
153+
"server": {
154+
"url": "opc.tcp://host.docker.internal:53530/OPCUA/SimulationServer",
155+
"timeoutInMillis": 5000,
156+
"scanPeriodInMillis": 3600000,
157+
"pollPeriodInMillis": 5000,
158+
"enableSubscriptions": false,
159+
"subCheckPeriodInMillis": 100,
160+
"showMap": false,
161+
"security": "Basic128Rsa15",
162+
"identity": {
163+
"type": "anonymous"
164+
}
165+
},
166+
"mapping": [
167+
{
168+
"deviceNodeSource": "path",
169+
"deviceNodePattern": "Root\\.Objects\\.OPC-UA_PLC",
170+
"deviceInfo": {
171+
"deviceNameExpression": "OPC-UA PLC",
172+
"deviceNameExpressionSource": "constant",
173+
"deviceProfileExpressionSource": "constant",
174+
"deviceProfileExpression": "default"
175+
},
176+
"attributes": [
177+
{
178+
"key": "Firmware Version",
179+
"type": "path",
180+
"value": "${FirmwareInformation\\.Version}"
181+
},
182+
{
183+
"key": "Updated",
184+
"type": "path",
185+
"value": "${FirmwareInformation\\.UpdatedDate}"
186+
}
187+
],
188+
"timeseries": [
189+
{
190+
"key": "Humidity",
191+
"type": "path",
192+
"value": "${Humidity}"
193+
},
194+
{
195+
"key": "Temperature",
196+
"type": "path",
197+
"value": "${Temperature}"
198+
},
199+
{
200+
"key": "Pressure",
201+
"type": "path",
202+
"value": "${Pressure}"
203+
}
204+
],
205+
"rpc_methods": [],
206+
"attributes_updates": []
207+
}
208+
]
209+
}
210+
```
211+
{:.copy-code.expandable-10}
212+
213+
Let’s break our connector configuration into smaller pieces and provide an explanation:
214+
215+
**Server** - defines how the gateway connects and interacts with your OPC-UA server. From all parameters for us
216+
the following is important:
217+
- **`url`** - specifies the server’s TCP endpoint. In this case, it's pointing to a local Prosys simulation at `opc.tcp://host.docker.internal:53530/OPCUA/SimulationServer`.
218+
- **`pollPeriodInMillis`** - sets the interval for polling node values when subscriptions aren't used (every 5 seconds in our example).
219+
- **`security`** - sets the OPC-UA security policy. Options include `Basic128Rsa15`, `Basic256`, and `Basic256Sha256`. Depends on your OPC-UA server settings.
220+
- **`identity`** - defines how the gateway authenticates to the server: here, anonymous for simplicity.
221+
222+
**Mapping** - defines how node data from the OPC-UA server maps to ThingsBoard devices:
223+
- **`deviceNodeSource`** & **`deviceNodePattern`** - the source type is path, and the pattern matches the root node (`Root.Objects.OPC-UA_PLC`) that represents our device.
224+
- **`deviceInfo`** - define ThingsBoard device name and device profile. In our example, we use constant values for this purpose.
225+
- **`attributes`** - these values are pushed to ThingsBoard attributes and are typically static or change infrequently. We use a relative path for configuring attributes data mapping.
226+
- **`timeseries`** - these gauge readings will appear under the "**Latest Telemetry**" tab in the device's page. We use a relative path for configuring time series data mapping too.
227+
228+
{% capture difference %}
229+
Additional information about the OPC-UA connector can be found [here](/docs/iot-gateway/config/opc-ua){:target="_blank"}.
230+
{% endcapture %}
231+
{% include templates/info-banner.md content=difference %}
232+
233+
## Step 3. Check device data
234+
235+
To review the data uploaded from your gateway, use the following steps:
236+
237+
{% assign checkDeviceData = '
238+
===
239+
image: https://img.thingsboard.io/gateway/opc-ua-connector/guides/review-device-data-1.png,
240+
title: Navigate to the **Entities** > **Devices** page and click on the created device "**OPC-UA PLC**" as we named it in the “**deviceNameExpression**” field . This will open the device details page. From there, switch to the **"Attributes"** tab to view the attributes that were configured in the connector.
241+
===
242+
image: https://img.thingsboard.io/gateway/opc-ua-connector/guides/review-device-data-2.png,
243+
title: To view real-time telemetry data from the device, navigate to the “**Latest Telemetry**” tab. Here, you will find the telemetry data being sent by the device, including metrics like “**humidity**”, “**temperature**” and “**pressure**”. This tab provides real-time device telemetry updates.
244+
'
245+
%}
246+
247+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=checkDeviceData %}
248+
249+
## Conclusion
250+
251+
In this guide, we demonstrated how to connect an OPC-UA device to ThingsBoard CE using the ThingsBoard IoT Gateway.
252+
By configuring the gateway, setting up the OPC-UA connector, and mapping both telemetry data (such as humidity,
253+
temperature, and pressure) and device attributes (like firmware version and update date), we established a complete
254+
data flow from the OPC-UA server into ThingsBoard.
255+
256+
With this setup, you can now monitor your device data in real time, visualize it on dashboards, and use
257+
ThingsBoard’s powerful features—such as alarms, rule chains—to build advanced IoT solutions. The same approach
258+
can be extended to real industrial OPC-UA devices, enabling seamless integration of systems into modern IoT platforms.
259+
260+
This example using the Prosys Simulation Server is just the beginning. You can now adapt the configuration to
261+
your own devices, scale up to multiple servers, and customize data mappings based on your project’s needs.
262+
263+
## Next steps
264+
265+
Explore guides related to main ThingsBoard features:
266+
- [Data Visualization](/docs/user-guide/visualization/) - how to visualize collected data.
267+
- [Device attributes](/docs/user-guide/attributes/) - how to use device attributes.
268+
- [Telemetry data collection](/docs/user-guide/telemetry/) - how to collect telemetry data.
269+
- [Using RPC capabilities](/docs/user-guide/rpc/) - how to send commands to/from devices.
270+
- [Rule Engine](/docs/user-guide/rule-engine/) - how to use rule engine to analyze data from devices.

0 commit comments

Comments
 (0)