OPC-UA Connector Configuration

• Connector configuration
• Section “General”
• Section “Server”
  • Subsection “Security”
• Section “Data mapping”
  • Subsection “Attributes” and “Time series”
  • Subsection “Attribute updates”
  • Subsection “RPC methods”
• Path types
  • Absolute path
  • Relative path
• Identifier types
• Next steps

This documentation will help you set up the OPC-UA connector for the ThingsBoard IoT Gateway. We’ll explain the configuration parameters in simple terms to make it easy for you to understand and follow. The OPC-UA (Open Platform Communications Unified Architecture) is a machine-to-machine communication protocol for industrial automation, and this connector allows seamless integration with the ThingsBoard platform. Use general configuration to enable this extension.

We will describe the connector configuration below.

Please note: If you are new to IoT Gateway, use the “Basic” configuration mode. If you are familiar with configuring IoT Gateway, you can use the “Advanced” configuration mode.

Connector configuration

The connector configuration is a user interface form that helps you set up a connection to OPC-UA server. Let’s look at all the available settings and explain each one clearly. This will help you understand how everything works.

Please note: To access the actual UI for the gateway - you need to a have connected gateway before adding a connector. Otherwise, you will see the old UI.

Section “General”

This configuration section contains general connector settings, such as:

• Name - connector name used for logs and saving to persistent devices;
• Logs configuration:
  • Enable remote logging - enables remote logging for the connector;
  • Logging level - logging level for local and remote logs: NONE, ERROR, CRITICAL, WARNING, INFO, DEBUG, TRACE;
• Send data only on change - sends data only it has changed since the last check, otherwise – data will be sent after every check;
• Report strategy - strategy for sending data to ThingsBoard:
  • Report period - period for sending data to ThingsBoard in milliseconds;
  • Type - type of the report strategy:
    • On report period - sends data to ThingsBoard after the report period;
    • On value change - sends data to ThingsBoard when the value changes;
    • On value change and report period - sends data to ThingsBoard when the value changes or after the report period;
    • On received - sends data to ThingsBoard after receiving data from the device (default strategy).

Additional information about the report strategy can be found here.

The General tab in settings is the same for both the basic and advanced configurations.

Section “Server”

The configuration in this section is used to connect to the OPC-UA server.

Select basic or advanced OPC-UA configuration:

1
2
3
4
5
6
7
8
9
10
11
"server": {
    "name": "OPC-UA Default Server",
    "url": "localhost:53530/OPCUA/SimulationServer",
    "timeoutInMillis": 5000,
    "scanPeriodInMillis": 5000,
    "disableSubscriptions": false,
    "subCheckPeriodInMillis": 100,
    "showMap": false,
    "security": "Basic128Rsa15",
    ...
},

Subsection “Security”

Select basic or advanced OPC-UA configuration:

Basic

Advanced

OPC-UA server connections offer three distinct security types: Anonymous - the simplest option of identity; Basic - using this option, you can provide the username and password to connect to the OPC-UA server; Certificates - the safest option of identity. Using this option, you can also provide path on machine with the gateway to certificate, private key and CA certificate. Optionally, you can provide the username/password pair.

There are several types available for this subsection: anonymous username cert.PEM anonymous (recommended if all servers are on the local network) username (recommended for a basic level of security) cert.PEM (recommended for a higher level of security) This option of identity subsection is the simplest. Parameter Default value Description type anonymous Type of identity on OPC-UA server. This part of configuration will look like this: 1 2 3 "identity": { "type": "anonymous" }, Using this option, you can provide the username and password to connect to the OPC-UA server. Parameter Default value Description type basic Type of identity. username user Username for logging into the OPC-UA server. password 5Tr0nG?@$sW0rD Password for logging into the OPC-UA server. This part of configuration will look like this: 1 2 3 4 5 "identity": { "type": "basic", "username": "user", "password": "5Tr0nG?@$sW0rD" }, This option of identity subsection is the safest. Parameter Default value Description type cert.PEM Type of identity on OPC-UA server. caCert /etc/thingsboard-gateway/ca.pem Path to the CA certificate. privateKey /etc/thingsboard-gateway/private_key.pem Path to the private key. cert /etc/thingsboard-gateway/cert.pem Path to the certificate file. mode SignAndEncrypt Security mode, there are 2 options – Sign and SignAndEncrypt. username user Username for logging into the OPC-UA server. password 5Tr0nG?@$sW0rD Password for logging into the OPC-UA server. Optionally, you can provide the username/password pair. This part of configuration will look like: 1 2 3 4 5 6 7 8 9 "identity": { "type": "cert.PEM", "caCert": "etc/thingsboard-gateway/ca.pem", "privateKey": "etc/thingsboard-gateway/private_key.pem", "cert": "etc/thingsboard-gateway/cert.pem", "mode": "SignAndEncrypt", "username": "user", "password": "5Tr0nG?@$sW0rD" },

Section “Data mapping”

This section contains general settings for the nodes and subsections for data processing.

Select basic or advanced OPC-UA configuration:

Basic

Advanced

To add a new node, click the “plus” icon; Provide the following fields in the opened model window: Device node, Device name and Profile name (all of them can be path or identifier).

Parameter Default value Description deviceNodePattern Root\\.Objects\\.Device1 Regular expression, which is used for looking up the node for a current device. deviceNodeSource path Source of the device node. deviceInfo     … deviceNameExpressionSource path Source of the device name (can be path, identifier or constant). … deviceNameExpression Device ${Root\\.Objects\\.Device1\\.serialNumber} Path to a variable with device name, which is used for looking up the device name in a variable. … deviceProfileExpressionSource constant Source of the device profile (can be path, identifier or constant). … deviceProfileExpression Device Path to a variable with device profile, is used for looking the device profile in some variable. This part of the configuration will look like this: 1 2 3 4 5 6 7 8 "deviceNodePattern": "Root\\.Objects\\.Device1", "deviceNodeSource": "path", "deviceInfo": { "deviceNameExpression": "Device ${Root\\.Objects\\.Device1\\.serialNumber}", "deviceNameExpressionSource": "path", "deviceProfileExpression": "Device", "deviceProfileExpressionSource": "constant" },

Subsection “Attributes” and “Time series”

The configuration in this subsection provides settings for processing data from OPC-UA node. These settings will be interpreted in ThingsBoard platform instance as attributes/time series of the device.

Basic

Advanced

To add new time series or attribute key, follow these steps: Click the “pencil” icon in the “Attributes” section to add new attribute key; Click on “Add attribute” in the opened window; Enter the “Key” field, select the “Type” (can be path, identifier or constant), enter “Value” and click “Apply” button; Now click on the “pencil” icon in the “Time series” section to add new time series key; Click on “Add time series” in the opened window; Enter the “Key” field, select the “Type” (can be path, identifier or constant), enter “Value” and click “Apply” button. You can enable a specific report strategy for each time series or attribute. This strategy defines how often data is sent to the ThingsBoard server. The following strategies are available: On report period - sends data to ThingsBoard after the report period; On value change - sends data to ThingsBoard when the value changes; On value change and report period - sends data to ThingsBoard when the value changes or after the report period; On received - sends data to ThingsBoard after receiving data from the device (default strategy). Additional information about the report strategy can be found here.

Parameter Default value Description key temperature °C Tag, that will be interpreted as telemetry for ThingsBoard platform instance. type path Source of the value (can be path, identifier or constant). value ${Root\\.Objects\\.Device1\\.TemperatureAndHumiditySensor\\.Temperature} Name of the variable in the OPC-UA object is used for looking up the value within a specific variable. ** * ** All rules below apply in the same way to attributes configuration. ** * ** You can input some expressions for search here, like: Full path to node - ${Root\\.Objects\\.Device1\\.TemperatureAndHumiditySensor\\.Temperature} Relative path from device object - ${TemperatureAndHumiditySensor\.Temperature} Some regular expressions to search for - ${Root\\.Objects\\.Device\\d*\\.TemperatureAndHumiditySensor\\.Temperature} Namespace identifier and node identifier - ${ns=2;i=5} This part of the configuration will look like this: 1 2 3 4 5 6 "timeseries": [ { "key": "temperature °C", "path": "${Root\\.Objects\\.Device1\\.TemperatureAndHumiditySensor\\.Temperature}" } ], Let’s look at an example. Replace the “path” value with the “NodeId” value. This is a relative path from device object or Display Name identifier taken from our test server. In this example, the timeseries section would look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 "timeseries": [ { "key": "humidity", "path": "${Counter}" }, { "key": "pressure", "path": "${Root\\.Objects\\.Simulation\\.Triangle}" }, { "key": "temperature °C", "path": "${ns=3;i=1002}" } ], You should be able to see the telemetry you have sent to ThingsBoard in the Latest telemetry section of your device:

Subsection “Attribute updates”

This subsection contains configuration for attribute updates request from ThingsBoard platform instance.

ThingsBoard allows the provisioning of device attributes and fetches some of them from the device application. You can treat this as a remote configuration for devices, enabling them to request shared attributes from ThingsBoard. See user guide for more details.

Basic

Advanced

In order to add new attribute update, follow these steps: Click the “pencil” icon in the “Attribute updates” section to add new attribute update; Click on “Add attribute update” in the opened window; Enter the “Key” field, select the “Type” (can be path, identifier or constant), enter “Value” and click “Apply” button.

Parameter Default value Description key deviceName Shared attribute name on the platform. type path Source of the shared attribute (can be path, identifier or constant). value Root\\.Objects\\.Device1\\.serialNumber Regular expression or identifier, which is used for looking up the node for the current device. This subsection in configuration file looks like this: 1 2 3 4 5 6 7 "attributes_updates": [ { "key": "deviceName", "type": "path", "value": "Root\\.Objects\\.Device1\\.serialNumber" } ]

Subsection “RPC methods”

ThingsBoard allows sending RPC commands to devices connected directly to ThingsBoard or via Gateway.

Basic

Advanced

In order to add new RPC method, follow these steps: Click the “pencil” icon in the “RPC methods” section to add new RPC method; Click on “Add method” in the opened window; Fill in “Method name” field. If the method has arguments, click on “Add argument” button and select the type of argument. Fill in the “Value” field and click “Apply” button.

This subsection contains the configuration for RPC requests from ThingsBoard platform instance. Parameter Default value Description method multiply Name of method on OPC-UA server. arguments   Arguments for the method (if this parameter doesn’t exist, arguments will be taken from RPC request). … type integer Type of the argument. .. value 2 Value of the argument. This part of configuration will look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 "rpc_methods": [ { "method": "multiply", "arguments": [ { "type": "integer", "value": 2 }, { "type": "integer", "value": 4 } ] } ],

Also, every telemetry and attribute parameter has built-in GET and SET RPC methods out of the box, so you don’t need to configure it manually. See the guide.

Path types

A Path type refers to the hierarchical address within the OPC-UA server’s namespace. It is used to navigate to specific nodes in the server.

The path for the attribute value can be absolute or relative.

Absolute path

An absolute path specifies the full hierarchical address from the root of the OPC-UA server’s namespace to the target node.

Example:

Gateway expects the node to exist and the value of “Root.Objects.TempSensor.Temperature” to be 23.54.

Expression:

${Root\\.Objects\\.TempSensor\\.Temperature}

Converted data:

23.54

Relative path

A relative path specifies the address relative to a predefined starting point in the OPC-UA server’s namespace.

Example:

Gateway expects the node to exist and the value of “Root.Objects.TempSensor.Temperature” to be 23.56.

Device Node Expression:

Root\\.Objects\\.TempSensor

Expression:

${Temperature}

Converted data:

23.56

Identifier types

An Identifier type is a unique ID assigned to a node within the OPC-UA server. It is used to directly reference specific nodes without navigating through the namespace hierarchy.

The Identifier type in the OPC-UA connector configuration can take various forms to uniquely reference nodes in the OPC-UA server’s address space. Identifiers can be of different types, such as numeric (i), string (s), byte string (b), and GUID (g). Below is an explanation of each identifier type with examples.

• Numeric Identifier (i)

  A numeric identifier uses an integer value to uniquely reference a node in the OPC-UA server.

  Expression:

  ${ns=2;i=1235}

  Converted data:

  21.34

• String Identifier (s)

  A string identifier uses a string value to uniquely reference a node in the OPC-UA server.

  Expression:

  ${ns=3;s=TemperatureSensor}

  Converted data:

  21.34

• Byte String Identifier (b)

  A byte string identifier uses a byte string to uniquely reference a node in the OPC-UA server. This is useful for binary data that can be converted to a byte string.

  Expression:

  ${ns=3;b=Q2xpZW50RGF0YQ==}

  Converted data:

  21.34

• GUID Identifier (g)

  A GUID identifier uses a globally unique identifier (GUID) to uniquely reference a node in the OPC-UA server.

  Expression:

  ${ns=3;g=550e8400-e29b-41d4-a716-446655440000}

  Converted data:

  21.34

Next steps

Explore guides related to main ThingsBoard features:

• ThingsBoard IoT Gateway Features
• Data Visualization - how to visualize collected data.
• Device attributes - how to use device attributes.
• Telemetry data collection - how to collect telemetry data.
• Using RPC capabilities - how to send commands to/from devices.
• Rule Engine - how to use rule engine to analyze data from devices.