---
tags:
- connect iot
description: "This documentation details the OPC UA Driver for connecting to industrial automation equipment, supporting data types, protocol parameters, and driver"
---

# 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:

| Name          | Description                      |
| ------------- | -------------------------------- |
| UInt8         | Unsigned Integer 8 bits          |
| UInt16        | Unsigned Integer 16 bits         |
| UInt32        | Unsigned Integer 32 bits         |
| UInt64        | Unsigned Integer 64 bits         |
| Int8          | Signed Integer 8 bits            |
| Int16         | Signed Integer 16 bits           |
| Int32         | Signed Integer 32 bits           |
| Int64         | Signed Integer 64 bits           |
| Boolean       | Boolean value                    |
| Float         | Floating number                  |
| Double        | Floating double-precision number |
| String        | ASCII value (text string)        |
| LocalizedText | Text string localized            |
| DateTime      | Date and Time value              |

Table: OPC UA specific data types

## Protocol Parameters

The protocol supports the following parameters:

| Name            | Type    | Possible Values                          | Default Value                       | Description              |
| --------------- | ------- | ---------------------------------------- | ----------------------------------- | ------------------------ |
| address         | String  |                                          | ""                                  | Address of OPC UA server |
| discoveryUrl | String | | "" | Url to use if the server uses Discovery. Leave empty for none |
| user            | String  |                                          | ""                                  | Login username           |
| password        | String  |                                          | ""                                  | Login password           |
| securityMode    | String  | `None`<br/>`Sign`<br/>`SignAndEncrypt` | `None`                      | Message Security Mode for communication between client and server. |
| securityPolicy  | Enum    | `None`<br/>`Basic128`<br/>`Basic192`<br/>`Basic256`<br/>`Basic256Sha256` | `None` | Security Policies for communication between client and server. |
| certificatesRootFolder | String  |                                   | "\${temp}/ConnectIoT/OPC-UA/Certificates/${id}" | Absolute path of the root folder for the Public Key Infrastructure. Allows the use of tokens ${temp} or ${tmp} for the OS temporary folder and token ${id} for replacing with the respective driver instance id |
| certificate     | Text    |                                          | ""                                  | Own certificate - can be either a path to a file or the contents of the file in plain text. Format should be 'pem' |
| privateKey      | Text    |                                          | ""                                  | Own private key - can be either a path to a file or the contents of the file in plain text. Format should be 'pem' |
| floatDecimalPlaces | Integer |                                       | 0                                   | Decimal places to use with float types to help fix IEEE 754 precision errors. Leave 0 for no rounding. |
| defaultTransactionTimeout | Integer |                                       | 15000                                   | Client Secure Channel default transaction timeout (ms) |

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

| Name                     | Type    | Possible Values | Default Value  | Description                                                  |
| ------------------------ | ------- | --------------- | -------------- | ------------------------------------------------------------ |
| customDataType           | String  |                 | ""             | The name of the data type when selecting data type 'Custom'. Opcua requires data type names to end with 'DataType'. This isn't required here because this suffix will be automatically appended internally. |
| arrayType                | Enum    |`Scalar`<br>`Array`<br>`Matrix`| `Scalar`             | Whether the property is a scalar, an array or a matrix |
| dimensions               | String  |                 | ""             | Empty for scalars or arrays. For matrices this should be a comma separated list of unsigned integer values representing the length of each dimension. E.g., a 3x2 matrix: \"3,2\" or \"[3,2]\". Note: brackets are optional |

### Event

| Name                       | Type    | Possible Values                      | Default Value  | Description                                                  |
| -------------------------- | ------- | ------------------------------------ | -------------- | ------------------------------------------------------------ |
| eventType                  | Enum    | `Subscription`<br>`Event`<br>`Alarm` | `Subscription` | Type of alarm to register<br>`Subscription`- Notification when at least one node changes value<br>`Event` - Notification when event occurs<br>`Alarm` - Notification when alarm occurs |
| publishingInterval         | Integer |                                      | 1000           | The rate (in milliseconds) at which the subscription executes and reports any items that have changed |
| lifeTimeCount              | Integer |                                      | 2400           | if the client can't communicate with the server for a period of time shorter than (`lifetimeCount` * `publishingInterval`), then the subscription is still available in the server. After that, the server will delete the subscription. (In milliseconds) |
| maxKeepAliveCount          | Integer |                                      | 10             | If the server has no notifications pending for the period of time defined by (`MaxKeepAliveCount` * `PublishingInterval`), the server will send a keep alive message to the client |
| maxNotificationsPerPublish | Integer |                                      | 0              | The maximum number of notifications that the client wishes to receive in a single publish response |
| priority                   | Integer |                                      | 10             | If multiple subscriptions need to send notifications to the client, the server will send notifications to the subscription with the highest priority first |
| serverNodeId               | String  |                                      | `""`           | When event type is either `Event` or `Alarm`, the node representing the entire server must be provided for registration. Example: `"i=2253 [Server]"` |

### EventProperty

| Name             | Type    | Possible Values | Default Value | Description                                                  |
| ---------------- | ------- | --------------- | ------------- | ------------------------------------------------------------ |
| isTrigger        | Boolean |                 | true          | Trigger the event when the value changes                     |
| samplingInterval | Integer |                 | 1000          | Sampling interval (in milliseconds) for the monitored item to create |
| discardOldest    | Boolean |                 | true          | Discard the oldest item when the queue is full               |
| queueSize        | Integer |                 | 1             | Size of sampling queue                                       |

### Command

| Name           | Type    | Possible Values | Default Value | Description                                                  |
| -------------- | ------- | --------------- | ------------- | ------------------------------------------------------------ |
| objectDeviceId | String  |                 | ""            | Identifier of the Object (parent) where the method is located (ex: ns=3;s=AirConditioner1) |

### Command Parameter

| Name           | Type | Possible Values         | Default Value | Description                                                  |
| -------------- | ---- | ----------------------- | ------------- | ------------------------------------------------------------ |
| customDataType | String |                       | ""       | The name of the data type when selecting data type 'Custom'. Opcua requires data type names to end with 'DataType'. This isn't required here because this suffix will be automatically appended internally. |
| arrayDimensions| String |                       | ""       | Empty for scalars. For arrays, this should be a comma separated list of unsigned integer values representing the maximum length of each array dimension, where 0 represents a dimension with no maximum (or unknown) length. E.g., a 3x2 matrix: \"3,2\" or \"[3,2]\"; an array with unlimited size: \"0\" or \"[0]\". Note: brackets are optional |

## 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

| Name       | Type         | Description                                                  |
| ---------- | ------------ | ------------------------------------------------------------ |
| name       | String       | Name of the event. Will be used as identifiers in the result calls. |
| isEnabled  | Boolean      | Is the event enabled and ready to be used? Default `false`   |
| properties | `Property`[] | List of properties to link with the event                    |

### Property

| Name       | Type   | Description                                                  |
| ---------- | ------ | ------------------------------------------------------------ |
| name       | String | Name of the property. Will be used as identifiers in the result calls. |
| deviceId   | String | Unique identifier in the OPC UA server (this is the NodeId/Tag Name). |
| deviceType | String | Data Type as the Server known the Property. Must use one from the supported Data Types of this protocol driver. |
| dataType   | String | Data Type of the value as known/used by the MES/System.      |

### PropertyValue

| Name          | Type   | Description                                                  |
| ------------- | ------ | ------------------------------------------------------------ |
| propertyName  | String | Name of the property. Will match the `name` of the `property` object provided |
| value         | any    | Value received from the Server, converted to the `dataType` of the `Property` |
| originalValue | any    | Value received from the Server without any conversion applied. |

### PropertyValuePair

| Name     | Type       | Description                          |
| -------- | ---------- | ------------------------------------ |
| property | `property` | Full description of the property     |
| value    | any        | Value to associate with the property |

### RegisterHandler

| Name  | Type    | Description                          |
| ----- | ------- | ------------------------------------ |
| event | `Event` | Event to register (full information) |

### UnregisterHandler

| Name  | Type    | Description                                                  |
| ----- | ------- | ------------------------------------------------------------ |
| event | `Event` | Event to unregister (at least the property `name` must be supplied) |

## Methods

### Get Properties Values

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

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

#### Example

Request `connect.iot.driver.opcua.getPropertiesValues`

```json
[
  {
    "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:

```json
[
  {
    "propertyName": "stringValue",
    "originalValue": {
      "dataType": "String",
      "arrayType": "Scalar",
      "value": "Hello World",
    },
    "value": "Hello World",
  },
  {
    "propertyName": "integerValue",
    "originalValue": {
      "dataType": "Int16",
      "arrayType": "Scalar",
      "value": 123,
    },
    "value": 123,
  }
]
```

### Set Property Values

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

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

#### Example

Request `connect.iot.driver.opcua.setPropertiesValues`

```json
[
  {
    "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:

```json
true
```

### Register Event

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

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

!!! note
    The events will be published to the listeners `connect.iot.driver.opcua.event` appended with the name of the event registered and a random id. Example: `connect.iot.driver.opcua.event.TemperatureChanged`

#### Example

``` json
{
   "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.

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

#### Example

```json
{
   "event":{
      "name":"CustomEvent"
   }
}
```

### Send Command

Will be implemented in a future version.

## 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.
- 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.
- 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.

![Diagram about OPC-UA transparency](diagrams/opcua_transparency.drawio.svg)

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.