OPC UA

The service enables transfer of OPC UA node values and events from the source domain to the destination domain. In the destination domain either binary encoding over TCP, or JSON encoding over MQTT can be used to transport OPC UA data.

Known limitations

The limitations listed below will be resolved in future versions of the service.

• The only supported security policy is Basic256Sha256.
• The Downstream service ignores all received event updates when configured to use binary content encoding over TCP.

OPC UA server to OPC UA server

The Upstream service will connect to the OPC UA server in the source domain and subscribe to, or poll at an interval, the value of the configured nodes. These value updates will be sent to the Downstream service, which in turn will forward them to the OPC UA server in the destination domain.

When the Downstream service receives a value update from a node in the source OPC UA server, it will write the new value to a pre-existing node with the same ID in the destination OPC UA server.

OPC UA server to MQTT broker

The Upstream service will connect to the OPC UA server in the source domain and subscribe to, or poll at an interval, the value of the configured nodes. These value updates will be sent to the Downstream service, which in turn will forward them to the MQTT broker in the destination domain.

JSON format

The JSON format which is published to the MQTT broker is defined by the OPC UA specification.

Examples

Value

        {
            "MessageId": "71d3579b-2f6b-4b77-9e4f-36acc649d57d",
            "MessageType": "ua-data",
            "Messages": \[
                {
                    "DataSetWriterId": 1,
                    "MessageType": "ua-deltaframe",
                    "Payload": {
                        "MyVariableDisplayName": {
                            "SourceTimestamp": "2024-06-19T07:13:44.872Z",
                            "ServerTimestamp": "2024-06-19T07:13:45.872Z",
                            "Status": 0,
                            "Value": {
                                "Body": "5",
                                "Type": 8
                            }
                        }
                    },
                    "Timestamp": "2024-06-19T07:13:46.067Z"
                }
            \],
            "PublisherId": "Publisher1"
        }

Event

        {
            "MessageId": "35ba6267-2d32-4e82-b73f-20771b56f50d",
            "MessageType": "ua-data",
            "Messages": \[
                {
                "DataSetWriterId": 2,
                "MessageType": "ua-event",
                "Payload": {
                    "EventId": {
                        "Body": "M2ZmNzU2YjE3YWNkNGRjODhkNzdlMjRjZmI0YTk5ZjI=",
                        "Type": 15
                    },
                    "EventType": {
                        "Body": {
                            "Id": 2915
                        },
                        "Type": 17
                    },
                    "Message": {
                        "Body": {
                            "Locale": null,
                            "Text": "AlarmEventMessage"
                        },
                        "Type": 21
                    },
                    "Severity": {
                        "Body": 1,
                        "Type": 5
                    },
                    "SourceNode": {
                        "Body": {
                            "Id": 2253
                        },
                        "Type": 17
                    },
                    "SuppressedOrShelved": {
                        "Body": true,
                        "Type": 1
                    },
                    "Time": {
                        "Body": "2024-06-19T07:13:12.252Z",
                        "Type": 13
                    }
                },
                "Timestamp": "2024-06-19T07:13:12.260Z"
                }
            \],
            "PublisherId": "Publisher1"
        }

Configuration

In this section, the configuration parameters of the service is described in greater detail. Note that the configuration parameters differ greatly in the Downstream service, depending on what protocol is chosen. A separate section describes the parameters for each protocol choice.

Upstream parameters

General

Parameter	Description	Format
Node config	A CSV file containing configuration regarding which node values and/or events the service will subscribe to.	File. The expected format is described in CSV format.
Publish interval	The requested publishing interval defines the cyclic rate that the subscription is being requested to return notifications to the client. If the requested value is 0 or negative, the server shall revise with the fastest supported publishing interval in milliseconds.	Integer
Max values per message	Limits the number of values/events per message sent to Downstream service. If a value of 0 is provided, no limit is set.	Integer

Connection

Parameter	Description	Format
Endpoint URL	The URL of the server endpoint which the service will connect to. For example: opc.tcp://opcua-server1:53101/ua/data	String
Application URI	The globally unique identifier for the application instance. For example; urn:my-ddsystem1:opcua:client	String
Server certificate	The expected certificate of the remote server. If this certificate does not match a remote server's certificate, the connection will be rejected by the service. Note that if this parameter is left empty, the service will implicitly trust all servers.	File in DER format

Security

Parameter	Description	Format
Mode	The security mode to use when connecting to the remote OPC UA server.	Available options: None, Sign and Sign & Encrypt
Policy	The configured security policy determines which algorithms to use for signing, encryption and key derivation.	Available options: Basic256Sha256
Certificate	The service's certificate which will be presented to remote servers during secure connection establishment.	File in DER format
Private key	The private key of the provided certificate.	File in PEM format

Authentication

Parameter	Description	Format
Type	The authentication method to use when authenticating towards the remote OPC UA server.	Available options: Anonymous, Username & Password and Certificate
Username	The username to use when authenticating towards the remote OPC UA server.	String
Password	The password to use when authenticating towards the remote OPC UA server.	String
Certificate	The service's certificate which will be used to authenticate towards the remote server.	File in DER format
Private key	The private key of the provided certificate.	File in PEM format

Downstream common parameters

Parameter	Description	Format
Protocol	The encoding and transport protocol to use when forwarding incoming node value updates and events to its intended destination.	Available options: OPC UA and MQTT
Customization	An optional customization file to modify the service functionality. Customization files are provided by Advenica - please talk to your Advenica contact for more information.	File

Downstream OPC UA parameters

These are the parameters for OPC UA server to OPC UA server communication. Available when protocol OPC UA was chosen on Downstream. Data will be forwarded to a remote OPC UA server using binary encoding over the TCP protocol.

General

Parameter	Description	Format
Node config	A CSV file containing configuration regarding which node values and/or events the service will subscribe to.	File. The expected format is described in CSV format.
Publish interval	The requested publishing interval defines the cyclic rate that the subscription is being requested to return notifications to the client. If the requested value is 0 or negative, the server shall revise with the fastest supported publishing interval in milliseconds.	Integer

Connection

Parameter	Description	Format
Endpoint URL	The URL of the server endpoint which the service will connect to; For example: opc.tcp://opcua-server1:53101/ua/data	String
Application URI	The globally unique identifier for the application instance. For example; urn:my-ddsystem1:opcua:client	String
Server certificate	The expected certificate of the remote server. If this certificate does not match a remote server's certificate, the connection will be rejected by the service. Note if this parameter is left empty, the service will implicitly trust all servers.	File in DER format

Security

Parameter	Description	Format
Mode	The security mode to use when connecting to the remote OPC UA server.	Available options: None, Sign and Sign & Encrypt
Policy	The configured security policy determines which algorithms to use for signing, encryption and key derivation.	Available options: Basic256Sha256
Certificate	The service's certificate which will be presented to remote servers during secure connection establishment.	File in DER format
Private key	The private key of the provided certificate.	File in PEM format

Authentication

Parameter	Description	Format
Type	The authentication method to use when authenticating towards the remote OPC UA server.	Available options: Anonymous, Username & Password and Certificate
Username	The username to use when authenticating towards the remote OPC UA server.	String
Password	The password to use when authenticating towards the remote OPC UA server.	String
Certificate	The service's certificate which will be used to authenticate towards the remote server.	File in DER format
Private key	The private key of the provided certificate.	File in PEM format

Downstream MQTT parameters

These are the parameters for OPC UA server to MQTT broker communication. Available when protocol MQTT was chosen on Downstream.

Data will be forwarded to a remote MQTT broker using JSON encoding over the MQTT protocol.

General

Parameter	Description	Format
Quality of Service	The Quality of Service level for all messages published by the service.	Available options: At Most Once (0), At Least Once (1) and Exactly Once (2)
Topic	The MQTT topic to which the service will publish messages.	String
Publisher ID	A unique identifier which will be added to published messages, enabling identification or filtering of messages.	String

Connection

Parameter	Description	Format
Address	Address of the remote host, either an IP address or a hostname.	Internet host name, see RFC 1123, section 2.1
Port	TCP port that the service use to connect to the remote host.	Integer within range 1 - 65535
Client ID	A unique ID for the client to connect with.	String
Keepalive Interval	The interval between keepalive packets. If interval is 0, sending of keepalives is disabled.	Integer (seconds)

TLS

Parameter	Description	Format
TLS	A selection of TLS Modes is available. If set to TLS With Defaults the service will use built-in default certificates.	Available options: Off, TLS With Defaults, TLS With CA and TLS With Client Certificate
CA	File containing the CA certificate. This option is available when TLS With CA is selected, and allows you to upload your own trusted Certificate Authority that the service will use to validate the MQTT broker.	File in PEM format
Client certificate	File containing the client certificate. This option is available when TLS With Client Certificate is selected.	File in PEM format
Client key	File containing the client key. This option is available when TLS With Client Certificate is selected.	File in PEM format

Authentication

Parameter	Description	Format
Authentication type	A selection for which type of authentication the service will use with the MQTT broker.	Available options: Anonymous, Password.
Username	Username to be used when authenticating towards the remote server.	String
Password	Password to be used when authenticating towards the remote Server.	String

CSV format

Columns

All columns listed in the table below must be present in the node configuration CSV file, in the same order as they are listed. If this requirement isn't met, the service will reject the node configuration file.

Column	Mandatory	Description	Format
SourceNode	Yes	Can be either the qualified Node ID of a node on the server or a relative Browse Path to a node on the server.	See Node ID notation and Browse Path notation for information regarding the expected format
EnableValue	Yes	Boolean value indicating of the value of the node shall be fetched. If the value of this field is set to false, the values in the PollInterval, FilterType, FilterValue are ignored.	true, false
PollInterval	No	Enables fixed interval polling of the node value, at the provided interval. If this parameter is provided, subscription based retrieval of the value is disabled for this node.	Human readable time interval. For example: 1 day, 2 hours, 1h 20min 5s, 100ms
FilterType	No	The type of deadband filter to apply to the subscription of the node. This value is ignored if PollInterval has been provided. If this value is provided, FilterValue must also be provided.	Absolute, Percent
FilterValue	No	The threshold value to apply to the given filter type. Changes to the value of a node smaller than the threshold will no longer trigger the service to be notified.	Decimal point number
EnableEvent	Yes	Boolean value indicating if an event subscription to be set up for the node. If the value of this field is set to true, the values in the EventTypeId and EventFields must also be provided.	true, false
EventTypeId	No	The node ID of the event type to which the service will set up a subscription. All events with a child type of the configured event type, will also be triggered.	See Node ID notation for information regarding the expected format
EventFields	No	A list containing the browse names of all event fields which is to be included in event notifications.	Comma separated list

See the OPC UA specification for additional details regarding deadband filter configuration.

Examples

Typical event subscription to "Server" node

From the OPC UA specification:

"Any OPC UA Server that supports eventing shall expose at least one Node as EventNotifier. The Server Object defined in OPC 10000-5 is used for this purpose. Events generated by the Server are available via this Server Object"

The configuration below sets up an event subscription to the Server object node for all events, with the event fields defined by the base event type.

SourceNode,EnableValue,PollInterval,FilterType,FilterValue,EnableEvent,EventTypeId,EventFields
i=2253,false,,
,,true,i=2041,"EventId,EventType,SourceNode,SourceName,Time,Message,Severity"

Event subscription with a custom event field

Mostly the same as the example above but a custom EventTypeId is provided, and added a custom field from this event type has been added to the end of the EventFields list.

SourceNode,EnableValue,PollInterval,FilterType,FilterValue,EnableEvent,EventTypeId,EventFields
i=2253,false,,
,,true,ns=1;i=1000,"EventId,EventType,SourceNode,SourceName,Time,Message,Severity,1:BrowsePathToMyCustomField"

Value subscription with and without deadband filter

Configuration for subscriptions to node values (with and without filter).

SourceNode,EnableValue,PollInterval,FilterType,FilterValue,EnableEvent,EventTypeId,EventFields
ns=1;i=1,true,,,,false,,

ns=1;i=2,true,,Absolute,0.01,false,,

ns=1;i=3,true,,Percent,10.0,false,,

Value polling at a fixed interval

Configuration for polling of node values at different fixed intervals.

SourceNode,EnableValue,PollInterval,FilterType,FilterValue,EnableEvent,EventTypeId,EventFields
ns=1;i=1,true,1 second,,,false,,

ns=1;i=2,true,200ms,,,false,,

ns=1;i=3,true,1d 3h 4m,,,false,,

ns=1;i=4,true,12 hours,,,false,,

Node ID notation

There is an XML notation defined by the OPC UA XML Schema which represents a fully qualified NodeId. The format of the string is:

ns=<namespace index>;<identifier type>=<identifier>

Namespace index is formatted as a base 10 number, if the index is 0 the entire ns=0; clause can be omitted. The identifier type specifies the type of the value present in the identifier field, and can contain one of the values described in the table below.

Flag	Identifier type
i	Numeric
s	String
g	Guid
b	Opaque

The identifier contains the identifier value, encoded as string. The identifier is formatted using the XML data type mapping for the identifier type. Note that the identifier may contain any non-null UTF8 character including whitespace.

See the OPC UA specification for additional details.

Examples

ns=2;s=Humidity

i=1056

ns=1;g=09a87375-845e-4c9b-924f-fca9603db28a

ns=1;b=M/RbKBsRVkePCePcx24oRA=='

Browse Path notation

In the SourceNode column it is possible to specify the Relative Path part of an OPC UA Browse Path. All paths are relative from the Root node of the OPC UA system and must start with a reference type . or /.

The full syntax for Relative Paths as described by Part 4, Annex 2 of the OPC UA specification is supported.

Examples

/Objects/3:Simulation/3:Square

/2:Block&.Output

<<1:ConnectedTo>1:Boiler/1:HeatSensor