OPC-UA Integration

OPC-UA (Open Platform Communications Unified Architecture, IEC 62541) is a platform-independent industrial M2M protocol designed for reliable, secure data exchange in automation and IoT environments. The ThingsBoard OPC-UA integration connects to an OPC-UA server, subscribes to configured device nodes, decodes node values via an uplink converter, and pushes telemetry and attributes to the platform. In the reverse direction, it encodes Rule Engine messages via a downlink converter and delivers them to OPC-UA nodes as write operations or method calls.

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

1. Launch UA Admin Dialog and note the Hostname / IP and Port values — you will enter them in the ThingsBoard integration.
2. Launch UaCPPServer — the console window confirms the server is running and displays the endpoint URL in opc.tcp://host:port format.

UA Admin Dialog — note the Hostname / IP (e.g. 10.7.3.145) and Port (e.g. 48010) values; you will enter them in the ThingsBoard integration connection step UaCPPServer console confirms the server is running and listening — the endpoint URL follows the opc.tcp://host:port format

OPC-UA uses a generic uplink converter. The uplink converter decodes incoming OPC-UA node values and maps them to the ThingsBoard data model.

The decoder function receives:

• payload — JSON object with node values, e.g. {"temperature": "72.15819999999641"}
• metadata — node metadata: opcUaNode_name, opcUaNode_namespaceIndex, opcUaNode_identifier, opcUaNode_fqn, integrationName

Sample payload:

{
    "temperature": "72.15819999999641"
}

Sample metadata:

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

For the full decoder function reference, see Uplink data converter.

Import the uplink converter

1. Download the uplink converter file:

2. Go to Integrations center ⇾ Data converters.
3. Click + Add data converter ⇾ Import converter.
4. Drag and drop the downloaded JSON file into the Import converter window.
5. Click Import.

The decoder function used in this tutorial:

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;

var data = decodeToJson(payload);
var deviceName = metadata['opcUaNode_name'];
var deviceType = 'airconditioner';

var result = {
   deviceName: deviceName,
   deviceType: deviceType,
   telemetry: {
   },
   attributes: {
   }
};

if (data.temperature) {
    result.telemetry.temperature = Number(Number(data.temperature).toFixed(2));
}

if (data.humidity) {
    result.telemetry.humidity = Number(Number(data.humidity).toFixed(2));
}

if (data.powerConsumption) {
    result.telemetry.powerConsumption = Number(Number(data.powerConsumption).toFixed(2));
}

if (data.state !== undefined) {
    result.attributes.state = data.state === '1' ? true : false;
}

function decodeToString(payload) {
   return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
   var str = decodeToString(payload);
   var data = JSON.parse(str);
   return data;
}

return result;

The downlink converter encodes RPC commands from ThingsBoard into OPC-UA write operations or method calls.

The output of the downlink converter must follow this structure:

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

The encoder returns a single object with these fields:

• contentType — JSON, TEXT, or BINARY
• data — JSON string with two optional arrays:
  • writeValues — {nodeId, value} pairs; NodeId format: ns=<namespaceIndex>;<type>=<identifier> where <type> is s (string), i (numeric), g (GUID), or b (byte string)
  • callMethods — {objectId, methodId, args} objects for calling OPC-UA methods
• metadata — must be an empty object ({}) for OPC-UA

For the full encoder function reference, see Downlink data converter.

Create a downlink converter

1. Go to Integrations center ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Set Converter type to Downlink.
4. Select integration type from the dropdown - OPC-UA.
5. Enter a converter name: OPC-UA Downlink Converter
6. In the Main encoding configuration, enter an encoder function:

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;

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;

7. Optionally, click Test encoder function to validate.
8. Click Add.

1. Go to Integrations center ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to OPC-UA.
   • Enable integration and Allow create devices or assets are on by default.
   • Click Next.
3. Uplink data converter:
   • Select existing — choose a previously created OPC-UA Uplink Converter from the list.
   • Click Next.
4. Downlink data converter:
   • Select existing — choose a previously created OPC-UA Downlink Converter from the list.
   • Click Next.
5. Configure the connection:
   • Host — hostname or IP address of the OPC UA server.
   • Port — port number of the OPC UA server
   • Security — None.
   • Identity — Anonymous.
   Configure the mapping:
   • Mapping type: Fully Qualified Name.
   • Device Node Pattern: Objects.BuildingAutomation.AirConditioner_\d+$ — regex matched against OPC-UA node FQNs to identify device nodes; matches all AirConditioner_N paths.
   • Subscription tags — define the node paths and output message keys:
   • state — State.
   • temperature — Temperature
   • humidity — Humidity
   • powerConsumption — PowerConsumption.
   See Connection settings for a full description of each parameter.
6. Click Add to complete the integration.

Go to Integrations center → Integrations (1) and click + Add integration (2). Set Integration type to OPC-UA (3) and click Next (4) Click Select existing (5), choose OPC-UA Uplink Converter from the list, and click Next (6) Click Select existing (7), choose OPC-UA Downlink Converter from the list, and click Next (8) Connection: enter Host and Port (9), set Security to None (10) and Identity to Anonymous (11); scroll down to configure the Mapping section Mapping: set Mapping type to Fully Qualified Name (12), enter the Device Node Pattern regex (13), add subscription tags for state, temperature, humidity, and powerConsumption (14), then click Add (15)

After saving, ThingsBoard connects to the OPC-UA server and 10 airconditioner devices appear on the Devices page.

Ten airconditioner devices appear on the Devices page after the integration connects Click a device to open details and navigate to the Latest telemetry tab — values update as the integration polls the OPC-UA server

Host

Hostname or IP address of the OPC-UA server.

Port

Port number of the OPC-UA server. Default: 49320.

Endpoint

Optional path suffix appended to the server address when constructing the OPC-UA connection URL. Use this when the server exposes a specific endpoint path, for example /OPCUA/SimulationServer. Leave blank if the server listens on the root path (most common for demo servers).

Security

Message security policy for the OPC-UA session:

• None — no encryption or signing (suitable for local/trusted networks)
• Basic128Rsa15 — 128-bit symmetric encryption, RSA-15 key exchange
• Basic256 — 256-bit symmetric encryption
• Basic256Sha256 — 256-bit symmetric encryption with SHA-256 signing (recommended for production)

When any security policy other than None is selected, you must provide a client certificate and private key so the server can verify the ThingsBoard client’s identity.

Identity

Authentication method used when establishing the OPC-UA session:

• Anonymous — no credentials required; the server must have anonymous logon enabled
• Username — additional Username and Password fields appear; authenticate with a server-side account

Mapping type

Determines how ThingsBoard identifies device nodes on the OPC-UA server:

• Fully Qualified Name — matches nodes by their full browsed path (e.g. Objects.BuildingAutomation.AirConditioner_1)
• ID — matches nodes by namespace index and node identifier

Device Node Pattern

Regular expression applied to OPC-UA node names or IDs to identify which nodes represent devices. Only nodes matching this pattern are subscribed to. Example: Channel1\.Device\d+$.

Namespace

OPC-UA namespace index used to scope node identifiers. Only visible when Mapping type is set to ID.

Subscription tags

Defines which child node values ThingsBoard reads from each matched device node. Each entry has:

• Key — the field name used in the ThingsBoard message payload (e.g. temperature)
• Path — relative path of the child node under the matched device node (e.g. Temperature)
• Required — when checked, a missing or unreadable value for this tag prevents the message from being processed; leave unchecked for optional tags

Execute remotely

When enabled, ThingsBoard generates an Integration key and Integration secret that allow the integration to run as a separate Remote Integration process outside the ThingsBoard cluster. This is the recommended approach when the OPC-UA server is only reachable from a local or isolated network that has no direct path to ThingsBoard.

Advanced settings

• Application name — OPC-UA client application name sent to the server during session establishment (informational)
• Application uri — OPC-UA client application URI; must be globally unique per the OPC-UA specification
• Scan period in seconds — how frequently ThingsBoard polls the OPC-UA server for updated node values. Default: 10
• Timeout in milliseconds — connection and request timeout. Default: 5000
• Description — optional text description for the integration
• Metadata — key-value pairs injected into every uplink message as integrationMetadata in converter scripts

To enable downlink (RPC) support, import the pre-built Airconditioners rule chain and wire it into the Root Rule Chain.

Download: airconditioners_rule_chain.json

1. Go to Rule chains, click + Add rule chain ⇾ Import rule chain, drag airconditioners_rule_chain.json into the window, and click Import.
2. The Airconditioners rule chain opens. Double-click the integration downlink node.
3. Set Integration to your OPC-UA integration and click the orange checkmark to confirm.
4. Click Apply changes to save the rule chain.

Go to Rule chains (1), click + Add rule chain (2), select Import rule chain, drop the JSON file into the dialog (4), and click Import The Airconditioners rule chain opens — double-click the integration downlink node (5) to configure it Set the Integration field (6) to your OPC-UA integration, then click the orange checkmark to save the node Click Apply changes (8) to save the Airconditioners rule chain

1. Go to Rule chains and open the Root Rule Chain.
2. Search for rule chain in the node panel and drag it onto the canvas.
3. In the Add rule node dialog, set Name = Airconditioners and Rule chain = Airconditioners. Click Add.
4. Connect the message type switch node to the Airconditioners node using the Post Telemetry, Post attributes, Attributes Updated, and RPC Request to Device relations.
5. Click Apply changes.

Go to Rule chains (1) and open the Root Rule Chain (2); type "rule" in the search box (3) to find the rule chain node, then drag it onto the canvas (4) In the Add rule node dialog, set Name = Airconditioners (5) and Rule chain = Airconditioners (6), then click Add (7) Connect the message type switch to the Airconditioners node via Post Telemetry, Post attributes, Attributes Updated, and RPC Request to Device (8), then click Apply changes (9)

Download the dashboard file: airconditioners_dashboard.json

1. Go to the Dashboards page.
2. Click + Add dashboard ⇾ Import dashboard.
3. Drag and drop the downloaded JSON file into the Import dashboard dialog and click Import.
4. Open the Airconditioners dashboard.

The dashboard displays real-time Temperature, Humidity, and Power Consumption graphs for all 10 airconditioners.

5. In the Entities widget, click the Open airconditioner details icon next to any device.
6. The Airconditioner status indicator is green. Click the Round switch to turn the airconditioner off.

After switching off, the status indicator turns grey, temperature and humidity begin to rise, and power consumption drops to zero.

Go to Dashboards (1), click + Add dashboard (2) → Import dashboard (3), drop the JSON file into the dialog (4), and click Import Airconditioners dashboard shows real-time telemetry graphs — click the Open airconditioner details icon (5) in the Entities widget to navigate to a device details page AirConditioner details page — Airconditioner status is green (on); click the Round switch (6) to send an RPC command and turn the device off After switching off — Airconditioner status turns grey, temperature and humidity trend upward, and power consumption drops to zero