Connect IoT - OPC UA Driver#

OPC Unified Architecture (OPC UA) is a machine to machine communication protocol for industrial automation developed by the OPC Foundation. Distinguishing characteristics are:

• Focus on communicating with industrial equipment and systems for data collection and control
• Open - freely available and implementable without restrictions or fees
• Cross-platform - not tied to one operating system or programming language
• Service-oriented architecture (SOA)
• Robust security

Data Types#

These are the supported specific data types:

Table: OPC UA specific data types

Protocol Parameters#

The protocol supports the following parameters:

Table: OPC UA specific parameters

Extended Parameters#

As with other protocol drivers, some extra parameters are necessary to provide more context to the behavior expected.

Property#

Event#

EventProperty#

Command#

Command Parameter#

Driver Extensions#

This protocol driver provides a set of extension that allow the customization to perform actions that are independent of the Driver Definitions associated. This means you can, using customization, get/set node values without needing to describe them.

• This is particularly useful when accessing equipment data that is shared/too complex to access using the regular mechanisms. Also useful when needing to access data whose naming convention may vary from device to device.
• To use these extensions you can either implement your own task or use the supplied Tasks Send Notification to Driver and Subscribe in Driver.

Objects#

The objects are structures that are either passed as parameters or returned as result values.

Event#

Property#

PropertyValue#

OriginalValue#

PropertyValuePair#

RegisterHandler#

UnregisterHandler#

CustomDataType#

CustomDataTypeField#

NodeInfo#

Describes a single node found while browsing the server's address space, together with its children.

Methods#

Get Properties Values#

Requests the server for the values of one or more properties (Nodes/Tags)

Signature

PropertyValue[] connect.iot.driver.opcua.getPropertiesValues(request Property[])

Example

Request connect.iot.driver.opcua.getPropertiesValues

[
  {
    "name": "stringValue",
    "deviceId": "ns=2;s=Demo.Static.Scalar.String",
    "dataType": "String"
  },
  {
    "name": "integerValue",
    "deviceId": "ns=2;s=Demo.Static.Scalar.Int16",
    "dataType": "Integer"
  }
]

Reply:

[
  {
    "propertyName": "stringValue",
    "originalValue": {
      "dataType": "String",
      "arrayType": "Scalar",
      "dimensions": null,
      "value": "Hello World",
      "quality": "Good",
      "statusCode": 0,
      "timestamps": {
        "serverTimestamp": "2026-01-01T12:00:00.000Z",
        "sourceTimestamp": "2026-01-01T12:00:00.000Z"
      }
    },
    "value": "Hello World",
  },
  {
    "propertyName": "integerValue",
    "originalValue": {
      "dataType": "Int16",
      "arrayType": "Scalar",
      "dimensions": null,
      "value": 123,
      "quality": "Good",
      "statusCode": 0,
      "timestamps": {
        "serverTimestamp": "2026-01-01T12:00:00.000Z",
        "sourceTimestamp": "2026-01-01T12:00:00.000Z"
      }
    },
    "value": 123,
  }
]

Set Property Values#

Requests the server to define the values of one or more properties (Nodes/Tags).

Signature

boolean connect.iot.driver.opcua.setPropertiesValues(request PropertyValuePair[])

Example

Request connect.iot.driver.opcua.setPropertiesValues

[
  {
    "property": {
      "name": "stringValue",
      "deviceId": "ns=2;s=Demo.Static.Scalar.String",
      "deviceType": "String"
    },
    "value": "Hello World"
  },
  {
    "property": {
      "name": "integerValue",
      "deviceId": "ns=2;s=Demo.Static.Scalar.Int16",
      "deviceType": "Int16"
    },
    "value": 123
  }
]

Reply:

true

Register Event#

Notifies the protocol driver to raise the occurrences of a specific event when it occurs.

Signature

void connect.iot.driver.opcua.registerEvent(data: RegisterHandler)

Example

{
   "event":{
      "name":"CustomEvent",
      "isEnabled":true,
      "properties":[
         {
            "name":"humidity",
            "deviceId":"ns=2;s=Demo.Static.Scalar.Double",
            "dataType":"Decimal",
            "deviceType":"Double",
            "extendedData":{
               "isTrigger":true
            }
         }
      ]
   }
}

Unregister Event#

Notifies the protocol driver to stop raising the occurrences of a specific event when they occur.

Signature

void connect.iot.driver.opcua.unregisterEvent(data: UnregisterHandler)

Example

{
   "event":{
      "name":"CustomEvent"
   }
}

Add Custom Data Types#

Registers one or more structured (complex) data types with the driver, so the driver knows how to encode and decode values for OPC UA nodes whose data type is not one of the built-in scalars.

When to use

Use this method whenever the OPC UA server exposes nodes or method parameters whose value is a structure — for example, an equipment-defined Job object, a Recipe definition, or a MaintenanceWindow record. Without registration, the driver has no schema for these types and cannot serialise values for write operations or deserialise the fields after a read.

End-to-end setup

1. Declare the structure on the driver by calling addCustomDataTypes once at start-up, after the driver is connected and before any node with a custom data type is read or written. The recommended way to issue this call from a workflow is the Add Custom Data Types OPC UA task; the transport topic below documents the underlying contract for custom code.
2. Point properties or command parameters at the type. On every Property or Command Parameter that should carry a custom value, configure the Driver Definition with:
   • AutomationProtocolDataType / deviceType set to Custom.
   • Extended parameter customDataType set to the same name you registered (without the DataType suffix — the driver appends it automatically when querying the server).
3. Run the workflow. When a read or write happens, the driver looks up the type on the server using the registered name, encodes the JSON value into an OPC UA ExtensionObject matching the field order, and exchanges it with the server.

Signature

{ success: boolean } connect.iot.driver.opcua.addCustomDataTypes(data: CustomDataType[])

Example — simple structure

A TemperatureReading with a numeric value and a string unit. Both fields are mandatory.

Request connect.iot.driver.opcua.addCustomDataTypes:

[
  {
    "name": "TemperatureReading",
    "description": "Temperature value with unit",
    "fields": [
      { "name": "value", "dataType": { "Name": "Double" }, "isOptional": false },
      { "name": "unit",  "dataType": { "Name": "String" }, "isOptional": false }
    ]
  }
]

Reply:

{ "success": true }

A Property on the Driver Definition that reads/writes this type would then be configured as deviceType: "Custom" with customDataType: "TemperatureReading".

Example — nested structure with an array of structures

A Job with an id, an optional name, and an array of Step objects (itself a custom type). Nested types must be registered too; either include them in the same call or split into multiple calls — order does not matter.

[
  {
    "name": "Step",
    "description": "One step in a job",
    "fields": [
      { "name": "index",       "dataType": { "Name": "UInt16" }, "isOptional": false },
      { "name": "description", "dataType": { "Name": "String" }, "isOptional": true  }
    ]
  },
  {
    "name": "Job",
    "description": "Job with an ordered list of steps",
    "fields": [
      { "name": "id",    "dataType": { "Name": "String" },  "isOptional": false },
      { "name": "name",  "dataType": { "Name": "String" },  "isOptional": true  },
      {
        "name": "steps",
        "dataType": { "Name": "Custom" },
        "customDataTypeName": "Step",
        "arrayDimensions": "0",
        "isOptional": false
      }
    ]
  }
]

Notes

• The field order in fields must match the field order declared on the server; field-by-name encoding is not used.
• customDataTypeName is required whenever dataType.Name is "Custom" and ignored otherwise.
• arrayDimensions applies to any field, scalar or structured. Use "0" when the length is variable, "<n>" for a fixed-length 1D array, and "<n>,<m>" for a matrix.
• The driver caches the resolved node id of each custom type after the first successful read. Re-registering a type with the same name is safe but does not invalidate the cache during the same session — restart the driver if the server-side definition changes.

Browse#

Walks the server's address space starting from a given node and returns the resulting tree of variables, methods, and object containers, including each variable's current value and metadata. Use this to discover which nodes a server exposes, instead of requiring the node IDs to already be known.

Standard-namespace nodes (namespace 0 and 1), such as the built-in Server object, are traversed but not included in the result, so the returned tree only surfaces the parts of the address space that a custom server actually defines.

Signature

NodeInfo[] connect.iot.driver.opcua.browse(request: { startNodeId?: string })

Example

Request connect.iot.driver.opcua.browse, starting from the server's root:

{}

Or from a specific node:

{
  "startNodeId": "ns=2;s=Demo.Static.Scalar"
}

Reply:

[
  {
    "nodeId": "ns=2;s=Demo.Static.Scalar.String",
    "nodeClass": "Variable",
    "browseName": "String",
    "displayName": "String",
    "description": "",
    "dataType": "String",
    "value": "Hello World",
    "valueRank": -1,
    "arrayDimensions": null,
    "accessLevel": 3,
    "userAccessLevel": 3,
    "minimumSamplingInterval": 100,
    "children": []
  }
]

Notes

• Leave startNodeId empty to browse from the server's root folder.
• The node IDs returned in nodeId can be used directly as deviceId when configuring Properties, Events, and Commands.
• Browsing a large address space reads the metadata of every discovered variable, so it can take longer to complete than a regular read; prefer starting from a specific startNodeId when only part of the tree is relevant.

Send Command#

The driver extensions have no method to send a command. OPC UA Method calls are supported through the regular Command flow defined in the Driver Definition (configure the parent object with the objectDeviceId extended parameter described above).

Remarks/Behavior#

• When an event has more than one property with the isTrigger flag:
• It will be triggered every time any of the properties value changes.
• The value of the other properties will be requested at that time.

• It is possible to have multiple triggers with the same set values (because they have not changed). If this behavior is not intended, separate into multiple events each one with it's own trigger set.

• When an event has no property with the isTrigger flag, it will never be triggered.

• In an event of type Subscription, the first value that the server reports for a property after the event is subscribed does not trigger the event.
• A read of a node that does not exist does not fail: the property has no value, and its originalValue.quality is Bad.
• An event registered with connect.iot.driver.opcua.registerEvent is not subscribed again after a reconnect. To restore it, unregister it and register it again.
• A command passes its parameters to the method as input arguments by position, not by name, so the command parameters must follow the order of the method's input arguments.
• When using events of type Event the property device id must follow the format <Namespace>:<name> (ex: 2:Temperature)
• When it´s necessary to convert a value from Int64/UInt64 to Long, Integer or Decimal, a warning is displayed stating that a conversion was made on the value, that could cause a loss in the accuracy. When the accurate value is needed, the RawValue should be used to be processed.
• Starting with version 12.0.0, originalValue also reports the tag's quality (Good/Uncertain/Bad, derived from the OPC UA status code) and statusCode/timestamps, for both property reads and event occurrences — see OriginalValue. Custom scripts that destructure originalValue expecting only dataType/arrayType/value continue to work, since the existing fields are unchanged, but should be updated to make use of the new quality field where relevant.
• After nodejs@>20.11.1 and nodejs@>18.19.1 the Rsa15 Security Policy has been deprecated.
• To store OPC UA certificates (trusted, rejected, and own) in a custom location, set the NODEOPCUA_PKI environment variable. This overrides the default directory and ensures the driver uses a consistent PKI path across all environments.
  • Example: export NODEOPCUA_PKI=/opt/iot/opcua-pki

Transparent Redundancy#

This driver only supports transparent redundancy.

In transparent redundancy, failover between servers is invisible to the client. If a server becomes unavailable, the client is not notified and does not need to take any action.

Servers in a transparent redundancy group appear as a single OPC UA server. They typically share the same Server URI and Endpoint URL, often exposed through a virtual IP address or a network load balancer. From the client’s perspective, there is only one server connection, and no special failover logic is required.

Failover is handled by the underlying infrastructure or cluster. When the primary server fails, the system automatically directs client communications to a standby server, allowing data exchange to continue without interruption.

Because this approach shifts complexity to the server and network layers, it requires a robust clustering setup. This usually includes a virtual IP address or network load balancer in front of multiple servers, as well as mechanisms to keep servers’ state in sync.

File Transfer#

The driver supports OPC UA file transfer operations through dedicated workflow tasks. Each task wraps the corresponding connect.iot.driver.opcua.{createDirectory,createFile,writeFile,readFile} transport topic so workflows do not need to call them directly.

• Create Directory task — creates a new directory on the OPC UA server.
• Create File task — creates a new file node.
• Write File task — uploads file content to the server.
• Read File task — downloads file content from the server (supports both streaming to a local directory and inline raw output).

Refer to the OPC UA task documentation for setting and parameter details.