Skip to content

Commit f9f8dd7

Browse files
Andry925Andry925
authored
Added docs for device node identifiers with relative paths & non-device node RPCs (#2463)
* write documentation to use relative path with identifier as device node * write documentation to use rpc's to non-device nodes * remove duplicated description from usage examples * remove duplicated description from usage examples, correct example for device nodes rpcs * remove duplicated part from opcua attributes/timeseries usage examples relative path * add improvements to opcua documentation * replace screenshot for example with relative path as device identifier. * add spaces between server-even
1 parent 03318c1 commit f9f8dd7

16 files changed

+215
-17
lines changed

‎_includes/templates/iot-gateway/opcua-connector/examples/shared-attributes-rpc/reserved-rpc-foreign-node.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
Every telemetry and attribute parameter comes with built-in `get` and `set` RPC methods, so you don’t need to configure them manually.
2+
3+
Additionally, you can use the reserved RPC methods to access any node on the OPC-UA server - even if it doesn’t belong to a specific device. This is especially useful when management or control nodes are located outside the device’s node tree.
4+
We will set the device node to `Root\.Objects\.DemoDevice`, but we will access the `TextMessage` node located at `Root\.Objects\.DemoDeviceInfo\.TextMessage`, which is outside the device node tree.
5+
As an example, we will use Prosys OPC-UA Simulation Server, which is
6+
available at `opc.tcp://0.0.0.0:53530/OPCUA/SimulationServer`. The server has the following structure:
7+
8+
![image](/images/gateway/opc-ua-connector/examples/opc-ua-server-structure-overview-4.png)
9+
10+
We’re interested in the "**TextMessage**" which has the "**[Path](/docs/iot-gateway/config/opc-ua/#absolute-path)**" - `Root\.Objects\.DemoDeviceInfo\.TextMessage`,
11+
and does not belong to the device node tree. We added this node as a telemetry parameter
12+
with the key `textmessage`, so it would be easy to verify later whether the value changed after calling the reserved `set` RPC method.
13+
14+
```json
15+
"timeseries": [
16+
{
17+
"key": "textmessage",
18+
"type": "path",
19+
"path": "${Root\\.Objects\\.DemoDeviceInfo\\.TextMessage}"
20+
}
21+
]
22+
```
23+
{: .copy-code}
24+
25+
Let's check the value of the textmessage node using the reserved `get` method. To get the current value of textmessage node,
26+
run the query in RPC debug terminal:
27+
28+
```bash
29+
get Root\\.Objects\\.DemoDeviceInfo\\.TextMessage;
30+
```
31+
{: .copy-code}
32+
33+
Response:
34+
35+
```json
36+
{"result":{"value":"HI"}}
37+
```
38+
{: .copy-code}
39+
40+
![image](/images/gateway/opc-ua-connector/examples/opc-ua-reserved-rpc-get-foreign-nodes-result-1.png)
41+
42+
So, the `get` method returns the current value of the textmessage node, and we can see that the textmessage is `HI`.
43+
44+
{% capture difference %}
45+
The RPC Debug Terminal is used only for example purpose, so you can use any other widget that supports RPC calls.
46+
{% endcapture %}
47+
{% include templates/info-banner.md content=difference %}
48+
49+
To set the value of the textmessage node and change its value, run the query:
50+
51+
```bash
52+
set Root\\.Objects\\.DemoDeviceInfo\\.TextMessage; New Message
53+
```
54+
{: .copy-code}
55+
56+
Response:
57+
58+
```json
59+
{"result":{"value":"New Message"}}
60+
```
61+
{: .copy-code}
62+
63+
And as you can see, from the screenshot below, the textmessage telemetry value has changed to `New Message`:
64+
65+
![image](/images/gateway/opc-ua-connector/examples/opc-ua-reserved-rpc-set-foreign-nodes-result-1.png)
66+
67+
Also, let's check the value of the textmessage telemetry again:
68+
69+
```bash
70+
get Root\\.Objects\\.DemoDeviceInfo\\.TextMessage;
71+
```
72+
{: .copy-code}
73+
74+
Response:
75+
76+
```json
77+
{"result":{"value":"New Message"}}
78+
```
79+
{: .copy-code}
80+
81+
![image](/images/gateway/opc-ua-connector/examples/opc-ua-reserved-rpc-get-foreign-nodes-result-2.png)
82+
83+
Full configuration for OPC-UA connector for the examples above will look like this:
84+
85+
```json
86+
{
87+
"server": {
88+
"url": "opc.tcp://0.0.0.0:53530/OPCUA/SimulationServer",
89+
"timeoutInMillis": 5000,
90+
"scanPeriodInMillis": 3600000,
91+
"enableSubscriptions": true,
92+
"subCheckPeriodInMillis": 100,
93+
"showMap": false,
94+
"security": "Basic128Rsa15",
95+
"identity": {
96+
"type": "anonymous"
97+
},
98+
"pollPeriodInMillis": 5000
99+
},
100+
"mapping": [
101+
{
102+
"deviceNodePattern": "Root\\.Objects\\.DemoDevice",
103+
"deviceNodeSource": "path",
104+
"deviceInfo": {
105+
"deviceNameExpression": "Demo Device",
106+
"deviceNameExpressionSource": "constant",
107+
"deviceProfileExpression": "default",
108+
"deviceProfileExpressionSource": "constant"
109+
},
110+
"attributes": [],
111+
"attributes_updates": [],
112+
"timeseries": [
113+
{
114+
"key": "textmessage",
115+
"type": "path",
116+
"value": "${Root\\.Objects\\.DemoDeviceInfo\\.TextMessage}"
117+
}
118+
],
119+
"rpc_methods": []
120+
}
121+
]
122+
}
123+
```
124+
{: .copy-code}

‎_includes/templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-identifier-device-node.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
Attributes and time series data can be accessed using [relative paths](/docs/iot-gateway/config/opc-ua/#relative-path)
2+
in the OPC UA Connector. This allows you to retrieve data without needing to specify the full path to the node.
3+
Additionally, we may use [identifiers](/docs/iot-gateway/config/opc-ua/#identifier-types) for "**Device node**".
4+
5+
As an example, we will use Prosys OPC-UA Simulation Server, which is available at
6+
`opc.tcp://0.0.0.0:53530/OPCUA/SimulationServer`. The server has the following structure:
7+
8+
![image](/images/gateway/opc-ua-connector/examples/opc-ua-server-structure-overview-2.png)
9+
10+
11+
We are interested in node "**Humidity**". We will use this node to retrieve the humidity data.
12+
13+
Let's configure the humidity data in the OPC-UA connector, using [relative paths](/docs/iot-gateway/config/opc-ua/#relative-path).
14+
For this purpose, follow these steps:
15+
16+
{% assign attributesAndTimeSeriesRelativePathIdentifierDeviceNode = '
17+
===
18+
image: /images/gateway/opc-ua-connector/examples/device-name-and-profile-absolute-path-1.png,
19+
title: Go to "**Entities**" → "**Gateways**" in the left sidebar and select your gateway.
20+
===
21+
image: /images/gateway/opc-ua-connector/examples/device-name-and-profile-absolute-path-2.png,
22+
title: Click on the "**Connectors configuration**" button on the right side menu.
23+
===
24+
image: /images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-1.png,
25+
title: Select the OPC-UA connector, click on the "**Data mapping**" tab. Select data mapping with device to which you want to add time series data (if you do not know how to add a new device, see the [Getting Started](/docs/iot-gateway/getting-started/?connectorsCreation=opcua){:target="_blank"} guide or [Data mapping](/docs/iot-gateway/config/opc-ua/#data-mapping) section of this guide with respective examples).
26+
===
27+
image: /images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-2.png,
28+
title: In the opened data mapping windows, click on the "**pencil**" icon next to the "**Time series**" or "**Attributes**" section.
29+
===
30+
image: /images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-3.png,
31+
title: Click on the "**Add time series**" button. Fill in the "**Key**" field with `Humidity`, also select "**[Path](/docs/iot-gateway/config/opc-ua/#relative-path)**" in "**Type**" field, and fill in the "**Value**" field with `${Humidity}`. This is a relative path to the node that contains the humidity data.
32+
===
33+
image: /images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-3.png,
34+
title: Remember to save your changes by clicking the "**Apply**" button.
35+
'
36+
%}
37+
38+
{% include images-gallery.liquid showListImageTitles="true" imageCollection=attributesAndTimeSeriesRelativePathIdentifierDeviceNode %}
39+
40+
Now we can check if the humidity data is sending correctly. Go to "**Entities**" > "**Devices**", select a created device and as you
41+
can see, the humidity data is available in the "**Time series**" section:
42+
43+
![image](/images/gateway/opc-ua-connector/examples/result-device-overview-relative-path-device-identifier.png)
44+
45+
If you are using advanced configuration mode and want to set the humidity data using a relative path, you can
46+
use the following configuration:
47+
48+
```json
49+
{
50+
"name": "OPCUA",
51+
"server": {
52+
"url": "opc.tcp://0.0.0.0:53530/OPCUA/SimulationServer",
53+
"timeoutInMillis": 5000,
54+
"scanPeriodInMillis": 3600000,
55+
"pollPeriodInMillis": 5000,
56+
"enableSubscriptions": false,
57+
"subCheckPeriodInMillis": 100,
58+
"showMap": false,
59+
"security": "Basic128Rsa15",
60+
"identity": {
61+
"type": "anonymous"
62+
}
63+
},
64+
"mapping": [
65+
{
66+
"deviceNodeSource": "identifier",
67+
"deviceNodePattern": "ns=3;i=1008",
68+
"deviceInfo": {
69+
"deviceNameExpression": "Demo Device",
70+
"deviceNameExpressionSource": "constant",
71+
"deviceProfileExpressionSource": "constant",
72+
"deviceProfileExpression": "default"
73+
},
74+
"attributes": [],
75+
"timeseries": [
76+
{
77+
"key": "Humidity",
78+
"type": "path",
79+
"value": "${Humidity}"
80+
}
81+
],
82+
"rpc_methods": [],
83+
"attributes_updates": []
84+
}
85+
]
86+
}
87+
```

‎_includes/templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-identifier.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Let's configure the humidity data in the OPC-UA connector. For this purpose, fol
1515
{% assign attributesAndTimeSeriesIdentifierPath = '
1616
===
1717
image: /images/gateway/opc-ua-connector/examples/device-name-and-profile-absolute-path-1.png,
18-
title: Go to "**Entities**" → "**Gateways**" in the right sidebar and select your gateway.
18+
title: Go to "**Entities**" → "**Gateways**" in the left sidebar and select your gateway.
1919
===
2020
image: /images/gateway/opc-ua-connector/examples/device-name-and-profile-absolute-path-2.png,
2121
title: Click on the "**Connectors configuration**" button on the right side menu.

‎_includes/templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-relative-path.md‎

Lines changed: 1 addition & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,6 @@ We are interested in node "**Humidity**". We will use this node to retrieve the
1010

1111
Let's configure the humidity data in the OPC-UA connector. For this purpose, follow these steps:
1212

13-
- Go to "**Entities**" → "**Gateways**" in the right sidebar.
14-
- Select your gateway.
15-
- Click on the "**Connectors**" tab.
16-
- Select the OPC-UA connector and click on the "**Data mapping**" tab.
17-
- Select data mapping with device to which you want to add time series data (if you don't know how to add a new device,
18-
see the [Getting Started](/docs/iot-gateway/getting-started/?connectorsCreation=opcua){:target="_blank"} guide
19-
or [Data mapping](/docs/iot-gateway/config/opc-ua/#subsection-attributes-and-time-series) section of this guide with
20-
respective examples).
21-
- In the opened data mapping windows, click on the "**pencil**" icon next to the "**Time series**" or "**Attributes**"
22-
section.
23-
- Click on the "**Add time series**" button. Fill in the "**Key**" field with `Humidity`, also select
24-
"**[Path](/docs/iot-gateway/config/opc-ua/#relative-path)**" in "**Type**" field, and fill in the "**Value**" field
25-
with `${Humidity}`. This is a relative path to the node that contains the humidity data.
26-
- Remember to save your changes by clicking the "**Apply**" button.
27-
2813
{% assign attributesAndTimeSeriesRelativePath = '
2914
===
3015
image: /images/gateway/opc-ua-connector/examples/device-name-and-profile-absolute-path-1.png,
@@ -40,7 +25,7 @@ Let's configure the humidity data in the OPC-UA connector. For this purpose, fol
4025
title: In the opened data mapping windows, click on the "**pencil**" icon next to the "**Time series**" or "**Attributes**" section.
4126
===
4227
image: /images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-3.png,
43-
title: Click on the "**Add time series**" button. Fill in the "**Key**" field with `Humidity`, also select "**[Path](/docs/iot-gateway/config/opc-ua/#absolute-path)**" in "**Type**" field, and fill in the "**Value**" field with `${Root\.Objects\.DemoDevice\.Humidity}`. This is an absolute path to the node that contains the humidity data.
28+
title: Click on the "**Add time series**" button. Fill in the "**Key**" field with `Humidity`, also select "**[Path](/docs/iot-gateway/config/opc-ua/#relative-path)**" in "**Type**" field, and fill in the "**Value**" field with `${Humidity}`. This is a relative path to the node that contains the humidity data.
4429
===
4530
image: /images/gateway/opc-ua-connector/examples/attributes-time-series-absolute-path-4.png,
4631
title: Remember to save your changes by clicking the "**Apply**" button.

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,7 @@ Device name/profile with Absolute Path<small></small>%,%devicenameandprofileabso
154154
Device name/profile with Relative Path<small></small>%,%devicenameandprofilerelativepath%,%templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/device-name-and-profile-relative-path.md%br%
155155
Device name/profile with Identifier<small></small>%,%devicenameandprofileidentifier%,%templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/device-name-and-profile-identifier.md%br%
156156
Attributes/Time series with Relative Path<small></small>%,%attributestimeseriesrelativepath%,%templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-relative-path.md%br%
157+
Attributes/Time series with Relative Path and Identifier device node<small></small>%,%attributestimeseriesrelativepathdevicenode%,%templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-identifier-device-node.md%br%
157158
Attributes/Time series with Absolute Path<small></small>%,%attributestimeseriesabsolutepath%,%templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-absolute-path.md%br%
158159
Attributes/Time series with Identifier<small></small>%,%attributestimeseriesidentifier%,%templates/iot-gateway/opcua-connector/examples/time-series-and-attributes/attributes-time-series-identifier.md{% endcapture %}
159160
{% include content-toggle.liquid content-toggle-id="opcua-attributes-timeseries-examples" toggle-spec=opcua-attributes-timeseries-examples %}
@@ -236,6 +237,7 @@ Attribute Updates<small>with Absolute Path</small>%,%sharedabsolute%,%templates/
236237
Attribute Updates<small>with Identifier</small>%,%sharedidentifier%,%templates/iot-gateway/opcua-connector/examples/shared-attributes-rpc/shared-attributes-with-identifier.md%br%
237238
RPC to Device<small></small>%,%rpctodevice%,%templates/iot-gateway/opcua-connector/examples/shared-attributes-rpc/rpc-to-device.md%br%
238239
Reserved RPCs<small></small>%,%reservedrpc%,%templates/iot-gateway/opcua-connector/examples/shared-attributes-rpc/reserved-rpc.md%br%
240+
Reserved RPCs to foreign nodes<small></small>%,%reservedrpctoforeignnodes%,%templates/iot-gateway/opcua-connector/examples/shared-attributes-rpc/reserved-rpc-foreign-node.md%br%
239241
RPC to Connector<small></small>%,%rpctoconnector%,%templates/iot-gateway/opcua-connector/examples/shared-attributes-rpc/rpc-to-connector.md{% endcapture %}
240242
{% include content-toggle.liquid content-toggle-id="opcua-shared-attributes-rpc-examples" toggle-spec=opcua-shared-attributes-rpc-examples %}
241243

‎images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-1-preview.png‎

161 KB
Loading

‎images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-1.png‎

161 KB
Loading

‎images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-2-preview.png‎

199 KB
Loading

‎images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-2.png‎

199 KB
Loading

‎images/gateway/opc-ua-connector/examples/attributes-time-series-relative-path-device-identifier-3-preview.png‎

201 KB
Loading

0 commit comments

Comments
 (0)