OPC-UA Integration

OPC-UA Integration streams data from an OPC UA server to ThingsBoard Edge, converting device payloads into telemetry and attributes. It also supports downlink — sending RPC commands from ThingsBoard Edge back to OPC UA nodes.

This guide walks through integrating ThingsBoard Edge PE with the OPC UA C++ Demo Server to visualize air conditioner telemetry and control units via RPC.

• Download and install the OPC UA C++ Demo Server (Windows only).

• After installation, launch the UA Admin Dialog and verify the hostname/IP address and port are configured correctly — you will need these when setting up the integration.

  

• Launch UaCPPServer. A console window will show the server endpoint URLs.

  

Converter and integration templates are created on the Cloud (ThingsBoard PE server). Log in as a Tenant administrator.

The uplink converter parses the OPC UA node payload and maps it to ThingsBoard telemetry and attributes. For each scanned node, the integration sends a payload and metadata like this:

Payload:

{
    "temperature": "72.15819999999641"
}

Metadata:

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

The converter takes opcUaNode_name as the device name and maps temperature, humidity, powerConsumption, and state to telemetry and attributes.

1. Go to Integration templates > Converter templates and click +, then Create new converter. Enable Debug mode to inspect events.

2. Paste the following script into the Decoder function field and save:

   /** Decoder **/
   
   var data = decodeToJson(payload);
   var deviceName = metadata['opcUaNode_name'];
   var namespaceIndex = metadata['opcUaNode_namespaceIndex'];
   var deviceType = 'airconditioner';
   
   var result = {
      deviceName: deviceName,
      deviceType: deviceType,
      telemetry: {},
      attributes: {
          namespaceIndex: namespaceIndex
      }
   };
   
   if (data.temperature != null) {
       result.telemetry.temperature = toFixed(data.temperature, 2);
   }
   
   if (data.humidity != null) {
      result.telemetry.humidity = toFixed(data.humidity, 2);
   }
   
   if (data.powerConsumption != null) {
      result.telemetry.powerConsumption = toFixed(data.powerConsumption, 2);
   }
   
   if (data.state != null) {
      result.attributes.state = data.state == '1' ? true : false;
   }
   
   /** Helper functions 'decodeToString' and 'decodeToJson' are already built-in **/
   
   return result;

Step 1: Click + and select Create new converter. Step 2: Paste the decoder script and save the converter.

To edit the converter later, open it from the Converter templates page, click the pencil icon, update the decoder, and click the checkmark to save.

Open the converter and click the pencil icon to edit. Update the decoder function and click the checkmark to save.

The downlink converter transforms RPC commands from ThingsBoard Edge into OPC UA write values or call methods. The output must have this structure:

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

1. Create another converter on the Converter templates page. Enable Debug mode.

2. Paste the following script into the Encoder function field and save:

   /** Encoder **/
   
   var data = {
       writeValues: [],
       callMethods: []
   };
   
   if (msgType === 'RPC_CALL_FROM_SERVER_TO_DEVICE') {
       if (msg.method === 'setState') {
           var targetMethod = msg.params === 'true' ? 'Start' : 'Stop';
           var writeValue = {
               nodeId: 'ns=' + metadata['cs_namespaceIndex'] + ';s=' + metadata['deviceName'],
               value: msg.params
           };
           data.writeValues.push(writeValue);
           var callMethod = {
               objectId: 'ns=' + metadata['cs_namespaceIndex'] + ';s=' + metadata['deviceName'],
               methodId: 'ns=' + metadata['cs_namespaceIndex'] + ';s=' + metadata['deviceName'] + '.' + targetMethod,
               args: []
           };
           data.callMethods.push(callMethod);
       }
   }
   
   var result = {
       contentType: "JSON",
       data: JSON.stringify(data),
       metadata: {}
   };
   
   return result;

Step 1: Click + and create a new downlink converter. Step 2: Paste the encoder script and save the converter.

1. Go to Edge management > Integration templates and click +. Select OPC-UA, name it OPC-UA air conditioners, enable Debug mode, and attach the uplink and downlink converters created above.

2. Fill in the connection and mapping fields:

   Field	Value
   Application name	(leave empty)
   Application URI	(leave empty)
   Host	${{endpointHost}}
   Port	Your OPC UA server endpoint port
   Scan period (seconds)	10
   Timeout (milliseconds)	5000
   Security	None
   Identity	Anonymous
   Mapping type	Fully Qualified Name
   Device node pattern	Objects\.BuildingAutomation\.AirConditioner_\d+$

   The device node pattern is a regular expression that matches node FQNs to device names. Objects\.BuildingAutomation\.AirConditioner_\d+$ matches nodes AirConditioner_1 through AirConditioner_N.

3. Add the following Subscription tags (node paths to subscribe to, with their key names in the output):

   Path	Key
   state	State
   temperature	Temperature
   humidity	Humidity
   powerConsumption	PowerConsumption

4. Click Add to save the integration template.

Step 1: Go to Integration templates and click +. Step 1: Select OPC-UA, name the integration, and attach the converters. Step 2: Set Host to ${{endpointHost}}, port, and security settings. Step 3: Add subscription tags for the four node attributes. Step 3: Review the configuration. Step 4: The OPC-UA integration template is created.

To send RPC commands from ThingsBoard Edge to OPC UA nodes, add two rule nodes to the Edge Root Rule Chain.

Go to Edge management > Rule chain templates and open the Edge Root Rule Chain. Add an "originator fields" node configured to add originator name and type to metadata. The downlink converter uses the device name to determine the target OPC UA node. Add an "integration downlink" node. Link "RPC Request to Device" → originator fields → integration downlink. Apply changes.

To visualize air conditioner data and test RPC commands, import the air conditioners dashboard and assign it to the Edge.

1. Download the airconditioners_dashboard.json file.

2. In the Cloud, go to Dashboards, open the Groups tab, and create a new group named Air conditioner.

3. Click Import dashboard, browse to the airconditioners_dashboard.json file, and click Import.

4. Go to Edge management > Instances and click Manage edge dashboard groups. Assign the Air conditioner group to the Edge.

Step 2: Go to Dashboards > Groups and create the Air conditioner group. Step 2: Open the Air conditioner group. Step 3: Import the dashboard JSON file. Step 4: Click the Manage edge dashboard groups button on the Edge instance. Step 4: Click Assign to edge and select the Air conditioner group.

Before assigning, add the endpointHost attribute to the Edge instance to provide the value for the ${{endpointHost}} placeholder.

Add the endpointHost attribute to the Edge and set it to the OPC UA server hostname or IP address. Click the Manage Integrations button on the Edge entity. Assign the OPC-UA integration template to the Edge. Log in to your Edge instance. The ${{endpointHost}} placeholder is replaced with the attribute value.

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

1. Go to Entities > Device groups. The Air conditioners group appears with all 10 devices.

2. Open any device and select the Latest Telemetry tab to see live readings.

3. Open the Air conditioners dashboard on the Edge to see all units at a glance.

4. Click Details on any unit to open the Air conditioner details page.

5. Click the On/Off Round switch to send a downlink RPC command. The unit turns off — the status light turns gray, temperature and humidity begin to rise, and power consumption stops.

Step 1: The Air conditioners device group showing all 10 units. Step 2: Telemetry values update continuously as data is read from the OPC UA server. Step 3: The Air conditioners dashboard showing live telemetry from all 10 units. Step 3: Dashboard detail view. Step 4: The details page shows the current state and the On/Off switch. Step 5: Toggle the On/Off switch to send an RPC downlink command. Step 5: The unit turns off. Temperature and humidity rise; power consumption stops.