OPC-UA Integration

OPC-UA Integration connects ThingsBoard Edge to an OPC UA server. It reads the nodes you subscribe to and converts their values into telemetry and attributes. It also supports downlink, so the Edge can write values and call methods on OPC UA nodes, for example from an RPC command.

This guide connects the Edge to the OPC UA C++ Demo Server, shows the telemetry of its air conditioner units on a dashboard, and switches a unit on and off with an RPC command.

• A ThingsBoard server with tenant administrator access. The templates are created there.
• A ThingsBoard Edge instance connected to the server.
• The OPC UA C++ Demo Server (Windows only), reachable from the Edge.

After the installation, open the UA Admin Dialog and note the Hostname / IP and Port on its UA Endpoints tab. Then start UaCPPServer. Its console prints the endpoint URL in the form opc.tcp://<host>:<port>, for example opc.tcp://10.7.3.145:48010. You need the host and port for the integration.

Converter templates are created on the server.

For each scanned node, the integration passes the node values as the payload and the node details as metadata:

Payload:

{
    "temperature": "72.15819999999641"
}

Metadata:

{
    "opcUaNode_namespaceIndex": "3",
    "opcUaNode_name": "AirConditioner_1",
    "integrationName": "OPC-UA air conditioners",
    "opcUaNode_identifier": "AirConditioner_1",
    "opcUaNode_fqn": "Objects.BuildingAutomation.AirConditioner_1"
}

The converter uses opcUaNode_name as the device name, saves temperature, humidity, and powerConsumption as telemetry, and state as an attribute. It also saves namespaceIndex as a client attribute, which the downlink converter needs later.

1. On the server, go to Edge management > Templates and open the Converter tab. Click Add data converter and select Create new converter.

2. Set Converter type to Uplink, select OPC-UA as the Integration type, and enter the name Air conditioner uplink.

3. In Main decoding configuration, select TBEL, paste the following script, and click Add:

   /** Decoder **/
   
   var data = decodeToJson(payload);
   var deviceName = metadata['opcUaNode_name'];
   var namespaceIndex = metadata['opcUaNode_namespaceIndex'];
   var deviceType = 'airconditioner';
   
   var result = {
      deviceName: deviceName,
      deviceType: deviceType,
   

   ▼Expand

To change a converter later, open it on the Converter tab, click the pencil icon, edit the script, and click the checkmark icon. The change is pushed to every Edge that uses it.

The downlink converter turns an RPC command from the Edge into OPC UA write operations and method calls. Its output has this structure:

[{
  "contentType": "JSON",
  "data": "{\"writeValues\":[],\"callMethods\":[{\"objectId\":\"ns=3;s=AirConditioner_1\",\"methodId\":\"ns=3;s=AirConditioner_1.Stop\",\"args\":[]}]}",
  "metadata": {}
}]

The encoder builds the node IDs from two metadata keys, deviceName and cs_namespaceIndex. The rule chain adds them to the message before it reaches the integration.

1. On the Converter tab, click Add data converter and select Create new converter.

2. Set Converter type to Downlink, select OPC-UA as the Integration type, and enter the name Air conditioner downlink.

3. In Main encoding configuration, select TBEL, paste the following script, and click Add:

   /** Encoder **/
   
   var data = {
       writeValues: [],
       callMethods: []
   };
   
   if (msgType === 'RPC_CALL_FROM_SERVER_TO_DEVICE') {
       if (msg.method === 'setState') {
           var targetMethod = msg.params === 'true' ? 'Start' : 'Stop';
   

   ▼Expand

1. On the server, go to Edge management > Templates, open the Integration tab, and click Add integration.

2. On the Basic settings step, select OPC-UA as the Integration type and enter the name OPC-UA air conditioners. Click Next.

3. On the Uplink data converter step, select Select existing, choose Air conditioner uplink, and click Next.

4. On the Downlink data converter step, select Select existing, choose Air conditioner downlink, and click Next.

5. On the Connection step, fill in the connection and mapping fields:

   Field	Value
   Host	${{endpointHost}}. The placeholder is replaced by the endpointHost server attribute of each Edge.
   Port	The port of the OPC UA server endpoint, for example 48010
   Endpoint	Leave empty
   Security	None
   Identity	Anonymous
   Mapping type	Fully Qualified Name
   Device Node Pattern	Objects\.BuildingAutomation\.AirConditioner_\d+$

   Device Node Pattern is a regular expression. Nodes whose fully qualified name matches it become devices. This pattern matches AirConditioner_1 to AirConditioner_N. Keep the defaults under Advanced settings (Scan period in seconds 10, Timeout in milliseconds 5000).

6. Under Subscription tags, fill in the empty first row, then click Add subscription tag for each further row. The keys must match the names used in the uplink converter.

   Key	Path
   state	state
   temperature	temperature
   humidity	humidity
   powerConsumption	powerConsumption

7. Click Add.

Add the endpointHost attribute first. Without it, the assignment dialog warns Edge has missing attribute(s) and the Edge receives the literal placeholder.

1. On the server, go to Edge management > Edges and click the Edge. On the Attributes tab, with the Server attributes scope selected, click +. Enter endpointHost as the key and the host name or IP address of the OPC UA server as the value. Click Add.

2. On the Details tab, click Manage integrations, then Assign to edge (+). Select OPC-UA air conditioners and click Assign.

3. Log in to the Edge and go to Integrations > Integrations. Open the integration. Host shows the attribute value instead of the placeholder.

As soon as the integration starts on the Edge and connects to the OPC UA server, data flows automatically.

1. On the Edge, go to Integrations > Integrations, open the integration, and select the Events tab. Uplink events with status OK appear on every scan.

2. Go to Devices & assets > Devices. Ten devices, AirConditioner_1 to AirConditioner_10, are listed.

3. Open one of them and select the Latest telemetry tab. The temperature, humidity, and powerConsumption values update on every scan. The Attributes tab shows the client attributes state and namespaceIndex.

To send an RPC command to an OPC UA node, add three nodes to the root rule chain of the Edge. The downlink converter reads deviceName and cs_namespaceIndex from the message metadata. Two enrichment nodes add these values, and an integration downlink node passes the message to the integration.

1. On the Edge, go to Data processing > Rule chains and open Edge Root Rule Chain.

2. In the node search field, type originator fields and drag the originator fields node onto the canvas. Name it add device name. In Originator fields mapping, change the target keys of the default rows: Name to deviceName and Profile name to deviceType. Keep Add mapped originator fields to at Metadata and click Add.

3. Search for originator attributes and drag the originator attributes node onto the canvas. Name it get namespaceIndex. In Client attributes, add namespaceIndex. Keep Add originator attributes to at Metadata and click Add. Client attributes are added to the metadata with the cs_ prefix, so the encoder reads cs_namespaceIndex.

4. Search for integration downlink and drag the integration downlink node onto the canvas. Name it push to integration, select OPC-UA air conditioners in the Integration field, and click Add.

5. Connect the nodes:

   • message type switch to originator fields with the RPC Request to Device label.
   • originator fields to originator attributes with the Success label.
   • originator attributes to integration downlink with the Success label.

6. Click the checkmark icon (Apply changes) to save the rule chain.

The Airconditioners dashboard shows the telemetry of all units and has a switch that sends the setState RPC command. Import it on the server and assign it to the Edge.

1. Download airconditioners_dashboard.json.

2. On the server, go to Monitor > Dashboards, open the Groups tab, and click Add entity group. Enter the name Air conditioner and click Add.

3. Open the group, click the Import dashboard icon (upload arrow), select the downloaded file, and click Import.

4. Go to Edge management > Edges and click the Edge. On the Details tab, click Manage dashboard groups, then Assign to edge (+). Select the Air conditioner group and click Assign.

1. On the Edge, go to Monitor > Dashboards and open the Airconditioners dashboard. It shows the live telemetry of all units.

2. In the Entities table, click the gear icon of a unit to open its details.

3. Click the Round switch. The dashboard sends the setState RPC command, the rule chain forwards it to the integration, and the downlink converter calls the Stop method of the node. The unit turns off: the Airconditioner status light turns gray, the temperature and humidity start to rise, and the power consumption drops to zero.

4. To check the downlink on the Edge, open the Events tab of the integration. A Downlink event with status OK appears. The Events tab of Air conditioner downlink under Integrations > Data converters shows the encoded message.