OPC-UA

Capabilities

Capability	Support	Comment
OPC-DA protocol		See OPC-DA
OPC-UA client		OnSphere can only connect to a server and cannot function as a server.
OPC-UA Server		OnSphere can only connect to a server and cannot function as a server.
OPC-UA over TCP		This feature is supported
OPC-UA over HTTP		This feature is not supported yet
Encrypted message exchange		See Client security mode
Unencrypted message exchange		See Client security mode
Server certificate		See Server certificate
Client certificate		See Client certificate
Client authentication - anonymous		No client authentication - not recommended for production usage
Client authentication - username / password		See username/password auth
Client authentication - certificate		See Client authentication
Client authentication - token		This feature is currently not supported. In case of interest please contact us at info@sdn.ch
Connection state monitoring of server (device)		See Server connectivity monitoring
Reading value by subscription from OPC-UA device		See Reading values with subscription
Reading value by polling from OPC-UA device		See Reading values with polling
Polling with bulk request		Currently, the polling mode does not support request batching. See Reading values with polling
Trigger a `method` using polling to read from OPC-UA device		See Trigger method to read a value
Trigger `method` to write from OPC-UA device		See Trigger method to write a value
Writing value from OPC-UA device		See Writing values

Examples

Connect an OPC UA client to read, write and use methods from a server.

Concept

Overview

OnSphere allows you to easily read (Reading values with polling) and write (Writing values) data on an OPC-UA device. The status of connection between OnSphere and the OPC-UA device is also monitored. OPC-UA also implements the notion of methods thus you can trigger a method to get its result (Trigger method to read a value) or trigger a method to write the content of a value (Trigger method to write a value).

Everything in OPC-UA is stored as a hierarchy through Folders and Nodes. This means that when you will read, write or call a method on a OPC-UA device you will have to specify the nodeIdentifier path. If you want to define a custom root folder you can in the device.opc-ua file.

NodeIds

In OPC UA (Open Platform Communications Unified Architecture), a NodeId is a unique identifier that is used to address and reference individual nodes (objects, variables, methods, etc.) in the OPC UA server’s address space. The NodeId provides a way for clients and servers to refer to specific data points, objects, or services in a standardized and structured manner.

A NodeId consists of two parts:

Namespace (ns or nsu). It Defines the scope or context of the identifier. It helps avoid conflicts between identifiers by allowing multiple parties to define their own nodes in different namespaces:

ns (Namespace Index): Numeric namespace index that links to a nsu.
nsu (Namespace URI) : Namespace URI (a textual representation of the namespace).

Identifier. The actual unique identifier of the node within the namespace. There are four types of identifiers:

i: Integer identifier.
s: String identifier.
g: Globally unique identifier (GUID).
b: ByteString identifier.

You can declare a nodeId of owner.opc-ua or output.opc-ua as follow (raw string or json object):

“nodeId”: “nsu=http://example.com/FactoryNamespace/;s=TemperatureSensor”
“nodeId”: “ns=3;s=TemperatureSensor”
“nodeId”: { "ns"=3, "s"="TemperatureSensor" }
“nodeId”: { "nsu"="http://example.com/FactoryNamespace/", "s"="TemperatureSensor" }

In OnSphere, the server is query to resolve an nsu to an ns before building the NodeId.

OnSphere Type transformation

Opc Ua Type	OnSphere Type
String	TEXT
ByteString	TEXT
LocalizedText	TEXT
Boolean	BOOLEAN
Int16	NUMBER
UInt16	NUMBER
Int32	NUMBER
UInt32	NUMBER
Int64	NUMBER
UInt64	NUMBER
Float	DECIMAL
Double	DECIMAL

Note

If the type is not in the table above, it is not officially supported but it does not mean it won’t work.

Server connectivity monitoring

Concept

The connection state between the OPC-UA module and a server (named device) can be read as a BOOLEAN value from the OPC-UA device in the OnSphere hierarchy (e.g., root.opc_ua.device1). If the connection is not working, the state will be set to *false*.

Usage

Trigger an alarm if a server is unavailable, as this will prevent all subsequent values from being read correctly.

Examples

see Connect an OPC UA client to read, write and use methods from a server.

Authentication and authorization

Server certificate

To connect to a remote OPC-UA server, its certificate must be trusted. This is achieved by adding the server’s certificate to the external trusted store.

See certificate trust store

Client certificate

The OPC-UA protocol uses certificates from both the client and the server to enable encryption. A client certificate is mandatory, and by default, the module’s certificate is used.

Hint

To be valid the client certificate must have the following key-usage : nonRepudiation, digitalSignature, keyEncipherment, dataEncipherment, keyCertSign

For more details about the module certificate, refer to the dedicated chapter.

Hint

Some servers require a Certificate Revocation List (CRL) for the root ca.crt. In that case it has to be generated manually. See opc ua requirement for the crl in the official documentation.

If you wish to use a certificate other than the default, you can specify a clientCertificate in the configuration of your OPC-UA device.

SAN (subject alternative name)

This parameter is encoded into the certificate X509, and is used used to validate the client certificate on the server side. Its value must exactly match one of the certificate’s subject alternative names (SAN). Although it is theoretically possible to define multiple subject alternative names in the same certificate, most OPC-UA servers only support the first one, we recommend to use a single SAN value of type 6

This code show how to generate a X509 client certificate with necessary parameters

openssl req -newkey rsa:2048 -x509 -nodes -keyout server.key -out server.crt -subj "/C=US/ST=Arizona/L=Chandler/O=My Company/OU=IOT/CN=www.mycompany.com" -reqexts v3_req -extensions v3_req -config <(echo -e "[req]\ndistinguished_name = req_distinguished_name\nx509_extensions = v3_req\nprompt = no\n\n[req_distinguished_name]\nC = US\nST = Arizona\nL = Chandler\nO = My Company\nOU = IOT\nCN = www.mycompany.com\n\n[v3_req]\nbasicConstraints = CA:FALSE\nsubjectKeyIdentifier = hash\nauthorityKeyIdentifier = keyid:always,issuer\nkeyUsage = nonRepudiation, digitalSignature, keyEncipherment, dataEncipherment, keyCertSign\nextendedKeyUsage = TLS Web Server Authentication, TLS Web Client Authentication\nsubjectAltName = @alt_names\n\n[alt_names]\nDNS.1 = localhost\nIP.1 = 127.0.0.1\nURI.1 = urn:open62541.client1.application") -sha256 -days 3650

This site provides an excellent reference for generating certificates.

Client authentication

Client authentication in OPC UA can be achieved using different methods. One approach involves using a certificate for signing and encrypting communication, which also serves as the authentication mechanism. Another method enhances user authentication by incorporating a username and password, providing an additional layer of identity verification.

Client security mode

The OPC-UA protocol uses client and server certificates to sign and encrypt communications. However, the session can be switched to an unencrypted mode by setting the security mode to “None.”

For more details, refer to the device.opc-ua file.

Warning

Using unencrypted and unsigned communication in production is strongly discouraged.

Reading values with polling

Concept

Values are updated using a polling frequency (defaults to 10 seconds), meaning that the value will take at most pollingFrequency to detect an error reading the value and report it. The module allows you to read a node by defining a owner.

Please note the following: there is no request batching in polling mode. If the system is polling 20,000 points, it will generate 20,000 read requests for each “polling interval.” Polling is more suitable for a small number of values. For larger datasets, it is recommended to use subscription.

Usage

Read a temperature sensor value each 30 minutes to create graphs.

Reading values with subscription

Concept

In contrast to permanently reading information (polling), OPC UA provides a more elegant functionality, a so called Subscription. OnSphere let’s you subscribe to data changes of Variable Values (Value attribute of a Variable). The module allows you to subscribe on a node by defining a owner.

A UA server may support queuing of data samples or events. The queue size, i.e. the maximum number of values which can be queued, can be configured for each monitored item.

Usage

A typical use case involves reacting to a device when its value changes, especially for pulse-based signals like a presence detector.

Writing values

Concept

The module allows you to write on an OPC-UA device on demand. OnSphere allows OPC-UA writing through callbacks: define your output and simply reference it in a callback.

Examples

You can refer to this example Connect an OPC UA client to read, write and use methods from a server. for a working example

Usage

A typical use case would be to control the speed of a motor.

Trigger method to read a value

Concept

A method can be used to extract a value and use it inside OnSphere.

Note

OnSphere handles reading periodically. Every changes in-between readings are lost.

Usage

A typical use case would be to monitor a temperature of a boiler.

Trigger method to write a value

Concept

OnSphere allows you to write on an OPC-UA device on demand. OnSphere allows OPC-UA writing through callbacks: define your output and simply reference it in a callback.

Warning

You can only pass one argument to methods you call.

Usage

A typical use case would be to start a boiler.