Skip to content

OPC-UA Device Service Component

The OPC-UA Device Service components integrate the OPC-UA protocol with Edge Xrt. For further reading about the OPC-UA protocol, see the OPC Foundation website.

The OPC-UA Device Service components support the following features:

  • Secure and unsecure connections to a remote OPC-UA server
  • Reading and writing to an OPC-UA endpoint
  • Monitored Item Service for monitoring Data Change Items and Event Items
  • TranslateBrowsePathsToNodeIds Service
  • Method Call Service
  • Browse Service
  • Device Discovery
  • Profile Generation

Note

XRT can be configured to automatically group schedules together creating larger batched readings, improving efficiency and throughput. For information on how to configure this feature please refer to the AutoBatchSize and AutoBatchTimeout settings described in Device Service Component Configuration.

OPC-UA Device Service Configuration

Note

The core components required for running OPC-UA (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

With those components assigned, there are also the following optional OPC-UA Driver options that can be used to configure the device service:

OPC-UA Driver Options

Parameter Type Description Default Value
LDSName String The device names of the Local Discovery Servers (LDS) added to Xrt. Multiple servers can be specified by separating the device names with a semi-colon. Empty

A template of the OPC-UA Device Service configuration file is provided where the driver options have been set to demonstrate their usage:

{
  "Library": "libxrt-opcua-device-service.so",
  "Factory": "xrt_opcua_device_service_factory",
  "Name": "opc_ua",
  "TelemetryTopic": "xrt/devices/opc_ua/telemetry",
  "RequestTopic": "xrt/devices/opc_ua/request",
  "ReplyTopic": "xrt/devices/opc_ua/reply",
  "DiscoveryTopic": "xrt/devices/opc_ua/discovery",
  "StateDir": "./deployment/state",
  "ProfileDir": "./deployment/profiles",
  "Scheduler": "sched",
  "Logger": "logger",
  "ThreadPool": "pool",
  "Bus": "bus",
  "Driver": {
    "LDSName": "lds-server1;lds-server2",
  }
}

OPC-UA Device Profile

Details on general profile usage can be found on the Device Profiles page

The following sections will cover how device resources are mapped to OPC-UA nodes.

Attributes

The attributes used in an OPC-UA device resource are described in the following table:

Attribute Description Valid Values Mandatory
nodeAttribute The node attribute that the resource is referencing String - See the Node Attribute section for valid values Yes, unless browseStartNodeId is defined
nodeId The identifier of the node in the OPC-UA server See NodeId Yes, unless browseStartNodeId is defined
dataTypeId The node identifier of the OPC-UA data type of the value attribute See NodeId No, only required if nodeAttribute equals "value"
browseStartNodeId See NodeId No
browsePath The name of a child node qualified with a namespace URI, relative to either the `browseStartNodeId` attribute String No, only required if browseStartNodeId is set
browsePathNamespaceIndex The namespace index of the node in the OPC-UA server A valid UInt16 value No, only required if browseStartNodeId is set

Node Attributes

This section contains the available node attributes and their descriptions. To access a node's attribute, set the nodeAttribute resource attribute to the name of the node attribute.

Note

Some node attributes can be specific to different node types.

Generic Node Attributes

Attribute Data Type Description
nodeId NodeId The NodeId of the node.
nodeClass NodeClass The NodeClass of the node.
browseName QualifiedName The BrowseName of the node.
displayName LocalizedText The DisplayName of the node.
description LocalizedText The Description of the node.
writeMask UInt32 The WriteMask of the node.
userWriteMask UInt32 The UserWriteMask of the node.
references ReferenceDescription[] The ReferenceTypes of the node.

Object NodeClass Attributes

Attribute Data Type Description
event Event dependent The resource that a node's events are received on.
eventNotifier Boolean Used to indicate if the Node can be used to subscribe to Events or the read / write historic Events.

Variable NodeClass Attributes

Attribute Data Type Description
value Any The Variable nodes value
dataType NodeId NodeId of the DataType definition for the Value Attribute
valueRank Int32 This Attribute indicates whether the Value Attribute of the Variable is an array and how many dimensions the array has. Reference.
arrayDimensions UInt32[] NodeId of the DataType definition for the Value Attribute
accessLevel Byte The variable node's access level. Reference.
userAccessLevel Byte The variable node's user access level. Reference.
minimumSamplingInterval Double The variable node's sampling interval for it's value. Reference.
historizing Boolean If the Server is actively collecting data for the history of the Variable. Reference.
Variable Node Value Attribute

The value attribute is how a device service interacts with a Variable nodes value.

This resource requires an extra resource attribute: dataTypeId. This allows the device service to correctly convert the OPC-UA value to an Xrt DataType, if the device service natively supports that OPC-UA data type. If the device service does not natively support an OPC-UA data type, then the device service will use a node's referenceTypes to resolve how to interact with a node.

Value Attribute Get Request Options

This table describes additional options that can be provided when performing a get request for a resource where the nodeAttribute attribute is set to value.

Name Data Type Description Required Default
useReferences Boolean Use a nodes referenceTypes to resolve how to interact with the value. If dataTypeId is equal to the id of ExtensionObject, then this will default to true N false
depth Byte The maximum depth of references that will be navigated N 5

When useReferences is set to true, the object returned will be of type: Unknown.

An example of a get request with these options set is provided below:

{
  "client": "example",
  "request_id": "1",
  "op": "device:get",
  "device": "example-device",
  "resource": "example-resource-value-attribute",
  "options" : {
    "useReferences" : true,
    "depth" : 5
  },
  "type": "xrt.request:1.0"
}

Method NodeClass Attributes

Attribute Data Type Description
executable Boolean Indicates if the Method Node's method is executable. Reference.
userExecutable Boolean Indicates if the Method Node's method is executable taking user access rights into account. Reference.
method Variant[] The resource used to interact with a node's method.
Method Node Method Attribute

The method attribute signifies a resource that is used to call a Method Node's method. Options on a get request are required.

Method Attribute Get Request Options

This table describes additional options for a get request that can be provided in the options field of a get request to a method attribute.

Name Data Type Description Required Default
objectNodeId NodeId The nodeId of the Object or ObjectType on which the Method is invoked. Y N/A
inputs Variant[] A list of input arguments to the method. N []

ObjectType NodeClass Attributes

Attribute Data Type Description
isAbstract Boolean Indicates if the ObjectType is an abstract type. Reference.

VariableType NodeClass Attributes

Attribute Data Type Description
arrayDimensions UInt32[] NodeId of the DataType definition for the Value Attribute

ReferenceType NodeClass Attributes

Attribute Data Type Description
isAbstract Boolean Indicates if the ReferenceType is an abstract type. Reference.
symmetric Boolean Indicates whether or not the meaning of the ReferenceType is the same for both the SourceNode and TargetNode. Reference.
inverseName LocalizedText The inverse name of the Reference Reference.

DataType NodeClass Attributes

Attribute Data Type Description
isAbstract Boolean Indicates if the DataType is an abstract type. Reference.

View NodeClass Attributes

Attribute Data Type Description
event Event dependent The resource that a node's events are received on.
eventNotifier Boolean Used to indicate if the Node can be used to subscribe to Events or the read / write historic Events.

Example resources

This device resource allows for read/write access to the Server state node's description:

{
    "name": "ServerStateDescription",
    "description": "The Server State node's description",
    "attributes": {
        "nodeId": {
            "namespaceIndex": 0,
            "identifier" : "2259",
            "identifierType": "NUMERIC"
        },
        "nodeAttribute" : "description",
    },
    "properties": {
        "valueType": "object",
        "readWrite": "RW"
    }
}

This device resource allows for read/write access to the Server state node value:

{
    "name": "ServerState",
    "description": "The Server State node's value",
    "attributes": {
        "nodeId": {
            "namespaceIndex": 0,
            "identifier" : "2259",
            "identifierType": "NUMERIC"
        },
        "nodeAttribute" : "value",
        "dataTypeId" : {
            "namespaceIndex": 0,
            "identifier" : "852",
            "identifierType": "NUMERIC"
        } 
    },
    "properties": {
        "valueType": "Int32",
        "readWrite": "RW"
    }
}

Device Commands

See the Device Profiles page for details on how to define device commands for grouping device resources for fewer requests.

OPC-UA Device Provisioning

The following section will explain how to configure a device for the OPC-UA Device Service.

Note

For information on dynamic device additions, removals and updates please see the MQTT API Guide.

Provisioning

To provision an OPC-UA device, the OPC-UA protocol must be used along with the Address protocol property which specifies the address of the OPC-UA server.

A basic example of an OPC-UA device provision within the devices.json file is provided below:

{
   "OPCUASimulator": {
    "name": "OPCUASimulator",
    "profileName": "opc-ua-simulator-profile",
    "protocols": {
      "OPC-UA": {
        "Address": "localhost:49947"
      }
    }
  }   
}

Device Protocol Properties

There are some additional protocol properties that can be used to configure a device:

Parameter Type Description Default Value
Address String Mandatory

The URI of the OPC-UA server in the following format:

<myServerAddress>:<serverPort><endpointPath> e.g 127.0.0.1:4840/Endpoint 		N/A
SecurityPolicy String Optional

The security policy for the connection's SecureChannel. Valid values are as follows:
  • None
  • Basic256
  • Basic128Rsa15
  • Basic256Sha256
  • Aes128Sha256RsaOaep
None
SecurityMode String Optional

The message security mode used with secure connections to the OPC-UA server. Valid values are as follows:
  • None
  • Sign
  • SignEncrypt
None
Username String Optional

The username to be used during connection to an endpoint 		N/A
Password Base64-encoded String Optional

The password associated with the username used during connection to an endpoint 		N/A
ApplicationURI String Optional

The URI associated with any certificate used to connect to the remote OPC-UA server 		Empty
Certificate String Optional

The name of the DER file containing the certificate to configure security policies for the client. 		N/A
PrivateKey String Optional

The name of the DER file containing the private key to configure security policies for the client. 		N/A
RequestedSessionTimeout UInt32 Optional

The suggested timeout, in milliseconds (ms), for inactive sessions created between the device service and an OPC-UA server endpoint. 		1200000
SessionKeepAliveInterval Float64 Optional

The interval (ms) at which the client sends requests to keep the session alive. 		1000
RootNode NodeId Optional

The starting point for the Browse and TranslateBrowsePathsToNodeIds Service. 		The servers root folder node
ConnectionReadingPostDelay UInt64 Optional

Delay (ms) to receiving monitored item readings after the device is added 		0
ReadBatchSize UInt16 Optional

Default batch size for grouping read requests. This value will be used if the servers capabilities can not be accessed. 		10
WriteBatchSize UInt16 Optional

Default batch size for grouping write requests. This value will be used if the servers capabilities can not be accessed. 		10
NodesPerBrowse UInt16 Optional

Default number of nodes that are requested in a browse request. This value will be used if the servers capabilities can not be accessed. 		5
ClientIterateInterval UInt32 Optional

Interval (Nanoseconds) between client iterations to handle asynchronous events and session/connection management. Decreasing this value can improve the rate at which the device service receives and handles asynchronous events e.g. when a large number of subscriptions have been created. However, values that are too low may be inefficient and can greatly increase the CPU usage of the service. 		100000 (100 ms)

Configuring Security

A Certificate and PrivateKey must be provided to configure security policies for the client. This is always required when using a SecurityPolicy other than None. This may also be required in other circumstances, for example, when a Username and Password are used to connect to a device and the token policy requires a security policy other than None.

OPC-UA Datatype Mappings

Unknown Types

  • Xrt DataType: Object

The device service does not natively support all OPC-UA types. Any data type node identifier that corresponds to an unknown type will be represented as an Unknown data type:

Name Data Type Description Mandatory
data Variant The value of the variable node. N
* Variant or Unknown This is the value of the node that is referenced. There can be more than one entries of this type in an Unknown data type N

* The field name is the display name of the referenced value.

Basic Types

OPC-UA Data Type Xrt Data Type
Boolean Bool
SByte Int8
Byte UInt8
Int16 Int16
UInt16 UInt16
Int32 Int32
UInt32 UInt32
Int64 Int64
UInt64 UInt64
Float Float32
Double Float64
String String
DateTime Int64
Guid String
ByteString String
XmlElement String
StatusCode UInt32
Duration Float64
UtcTime Int64
LocaleId String

NodeId

Field Type Mandatory
namespaceIndex UInt16 Y
identifier String | UInt32 - determined by identifierType Y
identifierType NodeId Identifier Type Y

NodeId Identifier Type

Valid values for a NodeId Identifier type are:

  • STRING
  • NUMERIC
  • BYTESTRING
  • GUID

Example

{
    "identifier": 7, 
    "identifierType": "NUMERIC", 
    "namespaceIndex": 0
}

ExpandedNodeId

Field Type Mandatory
namespaceURI String Y
serverIndex UInt32 Y
nodeId NodeId Y

Example

{
    "namespaceURI" : "http://opcfoundation.org/UA/",
    "serverIndex" : "0",
    "nodeId" : {
            "identifier": 7, 
            "identifierType": "NUMERIC", 
            "namespaceIndex": 0
        }
}

QualifiedName

Field Type Mandatory
namespaceIndex UInt16 Y
name String Y

Example

{
    "namespaceIndex" : 0,
    "name" : "example name"
}

LocalizedText

Field Type Mandatory
local String Y
text String Y

Example

{
    "local" : "en-US",
    "text" : "example localized text"
}

ExtensionObject

Field Type Mandatory
encoded String Y
content Extension Object Content Y

Extension Object Content

Encoded

Field Type Mandatory
dataTypeId NodeId Y
data dataTypeId dependant Y

Decoded

Field Type Mandatory
dataTypeId NodeId Y
body String N

Examples

Encoded Content

{
    "encoded" : true,
    "content" : {
        "dataTypeId" : {
            "identifier" : 1,
            "identifierType" : "NUMERIC",
            "namespaceIndex" : 0,
        },
        "data" : "True"
    }
}
Decoded Content

{
    "encoded" : false,
    "content" : {
        "dataTypeId" : {
            "identifier": 7,
            "identifierType": "NUMERIC",
            "namespaceIndex": 0
        },
        "body" : "#n$q"
    }
}

DataValue

Field Type Mandatory
value dataTypeId dependant N
dataTypeId NodeId Y, if value is present.
status StatusCode N
sourceTimestamp DateTime N
serverTimestamp DateTime N
sourcePicoseconds UInt16 N
serverPicoseconds UInt16 N

Example

{
    "value" : true,
    "dataTypeId" : {
        "identifier" : 1,
        "identifierType" : "NUMERIC",
        "namespaceIndex" : 0
    },
    "status" : 0,
    "sourceTimestamp" : 1652092767,
    "serverTimestamp" : 1652092789,
    "sourcePicoseconds" : 6,
    "serverPicoseconds" : 42
}

Variant

Field Type Description Mandatory
dataTypeId NodeId The dataTypeId of the data field Y
data Depended on the value of dataTypeId The variants data. This can be a one dimensional array or scalar. Y
dimensions UInt32[] An array describing the size of each dimension of the data. This should only be present if the data field is an array. N

Example

{
    "dataTypeId" : {
        "identifier" : 1,
        "identifierType" : "NUMERIC",
        "namespaceIndex" : 0
    },
    "data" : [true, false, true, false, true, true],
    "dimensions" : [2,3]
}

DiagnosticInfo

Field Type Mandatory
symbolicId Int32 N
namespaceURI Int32 N
localizedText Int32 N
locale Int32 N
additionalInfo String N
innerStatusCode StatusCode N
innerDiagnosticInfo DiagnosticInfo N

NodeClass

Valid Values

Value OPC-UA Nodeclass
0 Unspecified
1 Object
2 Variable
4 Method
8 ObjectType
16 VariableType
32 ReferenceType
64 DataType
128 View

StructureType

Value OPC-UA StructureType
0 Structure
1 StructureWithOptionalFields
2 Union

ReferenceDescription

Field Type Description Mandatory
referenceTypeId NodeId Y
isForward Boolean Y
expandedNodeId ExpandedNodeId Y
browseName QualifiedName Y
displayName LocalizedText Y
nodeClass NodeClass Y
typeDefinition ExpandedNodeId Y

Example

{
    "browseName": {
        "name": "HasOrderedComponent",
        "namespaceIndex": 0
    },
    "displayName": {
        "local": "",
        "text": "HasOrderedComponent"
    },
    "expandedNodeId": {
        "namespaceURI": "",
        "nodeId": {
            "identifier": 49,
            "identifierType": "NUMERIC",
            "namespaceIndex": 0
        },
        "serverIndex": 0
    },
    "isForward": true,
    "nodeClass": "referenceType",
    "referenceTypeId": {
        "identifier": 45,
        "identifierType": "NUMERIC",
        "namespaceIndex": 0
    },
    "typeDefinition": {
        "namespaceURI": "",
        "nodeId": {
            "identifier": 0,
            "identifierType": "NUMERIC",
            "namespaceIndex": 0
        },
        "serverIndex": 0
    }
}

ServerState

Value OPC-UA StructureType
0 Running
1 Failed
2 NoConfiguration
3 Suspended
4 Shutdown
5 Test
6 CommunicationFault
7 Unknown

OPC-UA Device Service Interaction

Any sections contained within the part of the guide are to describe protocol specific functionality of the device service.

For information on how to dynamically execute reads, writes, setting up schedules, triggering device discovery and much more, please refer to the MQTT API Guide.

For interactive examples of the OPC-UA Device Services refer to OPC-UA Xrt Example. Following the instructions in the above links will demonstrate many of the features available when running the device service using an OPC-UA simulator.

OPC-UA Server Discovery

To set up discovery:

  1. Set the device service driver option LDSName to include the name of the LDS device you will add.

  2. Add a device to the OPC-UA Device Service with the same name as you added to LDSName in step 1. This device's protocol properties should contain the address of the local discovery server and any other protocol properties required to connect to the server.

After following these steps, the device service should have the ability to discover any servers registered with that LDS.

Discovery Options

To be included under options in a device add or device scan request.

nodeAttributeWhiteList

  • Sets the whitelist for node attributes to be incuded in the discovered profile.
  • Defaults to all attributes
  • Expected value: A list of node attribute
valid attribute values
  • nodeId
  • nodeClass
  • browseName
  • displayName
  • description
  • writeMask
  • userWriteMask
  • references
  • value
  • dataType
  • valueRank
  • arrayDimensions
  • accessLevel
  • userAccessLevel
  • minimumSamplingInterval
  • historizing
  • event
  • eventNotifier
  • executable
  • userExecutable
  • method
  • containsNoLoops
  • isAbstract
  • symmetric
  • inverseName
Example
"options" : {
    "nodeAttributeWhiteList" : ["nodeId", "displayName", "value"]
}

nodeClassWhiteList

  • Sets the whitelist for node classes to be incuded in the discovered profile.
  • Defaults to all node classes
  • Expected value: A list of node classes
valid values
  • object
  • variable
  • method
  • objectType
  • variableType
  • referenceType
  • dataType
  • view
Example
"options" : {
    "nodeClassWhiteList" : ["object", "variable", "method"]
}

OPC-UA Subscriptions

Subscriptions are created by auto events and provide the ability to monitor variable and event nodes. When the monitored item's value is updated on the server, the device service will receive a notification and will post the updated value. The server will poll this monitored item at a configurable interval rate.

To set up an OPC-UA monitored item it is similar to how a schedule is configured. The main differences are that the interval property is ignored, and there is an extra field called options. There should be a Subscription field which can contain options for the subscription.

Subscription Setting Description Valid Values
Interval The interval at which the server will poll the monitored resource. UInt32 Value

An example of how an OPC-UA subscription can be made is provided below as a static configuration in the schedules.json file.

{
    "subscription": {
      "name":"example-schedule",
      "device":"ExampleDevice",
      "resource":["Resource1", "Resource2"],
      "options": {
          "Subscription": {
            "Interval" : 1500
          }
      }
    }
}

To change the interval at which the server will poll the monitored resource, set the Interval property to your desired polling rate.

Note

The polling rate is ultimately decided by the server, meaning that it can ignore this value when creating a new subscription to the monitored resource.

Run the OPC-UA Device Service

Standalone on Command Line

Find details on how to run the OPC-UA Device Service on the Run Device Services page.

Docker Container

Find details on how to run OPC-UA Device Service in a docker container at Run OPC-UA Docker