Skip to content

OPC-UA Device Service Component

The OPC-UA Device Service components integrate the OPC-UA protocol with 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
  • Browse Service

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 specifed 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
nsIndex Mandatory

The namespace index of the node in the OPC-UA server 		UInt16
nodeID Optional

The identifier of the node in the OPC-UA server 		Valid values are as follows:
  • string
  • guid
  • bytestring
  • uint32
IDType Optional

The data type used for the nodeID attribute 		Valid values are as follows:
  • STRING
  • NUMERIC
  • BYTESTRING
  • GUID
startNode Optional

The name of the starting node for the translation of browse path to node ID 		The nodeID in the following format:

<namespaceIndex>;<IDType>=<nodeID>
browsePath Optional

The name of a child node qualified with a namespace URI, relative to either the startNode attribute or the RootNode protocol property 		String
monitored Optional

Specifies whether the defined nodes in a remote server are monitored using OPC-UA subscriptions

Set to true to monitor the nodes 		Valid values are as follows:
  • true
  • false (default)
publishInterval Optional

Applies only when monitored is set to true

The value in milliseconds of the publishing interval requested when creating a new subscription ID 		Double
objectType Optional

This is used to specify the data type of a node if there is not a one to one mapping between the OPC-UA protocol specific data type and an XRT data type. See Data Types for more information on the supported mappings. 		String Valid values are as follows:
  • Primitive (default)
  • DateTime

Example resources

The device resource below allows for read access to the Server state node found in OPC-UA servers, accessed using it's namespace, node ID and ID Type.

{
    "name": "ServerState",
    "description": "The Server State",
    "attributes": {
        "nodeID": "2259",
        "nsIndex": 0,
        "IDType": "NUMERIC"
    },
    "properties": {
        "valueType": "Int32",
        "readWrite": "R"
    }
}

Similarly, we could also represent this node using its browse path. The ServerStatus node's parent is the Server Node which has a namespace of 0 and an numeric identifier of 2253.

{
    "name": "ServerState",
    "description": "The Server State",
    "attributes": {
        "nsIndex": 0,
        "startNode" : "0;i=2253",
        "browsePath" : "ServerStatus"
    },
    "properties": {
        "valueType": "Int32",
        "readWrite": "R"
    }
}

If we want to set up a subscription to monitor changes in the value of this item we can add the monitored attrubute. We can set the interval at which changes in this value are tested by the server with the publishInterval attribute.

{
    "name": "ServerState",
    "description": "The Server State",
    "attributes": {
        "nodeID": "2259",
        "nsIndex": 0,
        "IDType": "NUMERIC",
        "monitored": true,
        "publishInterval": 10000,
    },
    "properties": {
        "valueType": "Int32",
        "readWrite": "R"
    }
}

Data Types

When the remote OPC-UA server receives a request, it returns a value with an OPC-UA type. Depending on the ValueRank attribute of a Node, the XRT Data Type can either be an XRT primitive or array type. If the ValueRank of a node is Scalar then use the primitive type, for any other ValueRank use the array type. The following tables lists the supported OPC-UA data types and their equivalent XRT data type:

OPC-UA Primitive Data Types

OPC-UA Data Type XRT Data Type
Boolean Bool/BoolArray
SByte Int8/Int8Array
Byte UInt8/UInt8Array
Int16 Int16/Int16Array
UInt16 UInt16/UInt16Array
Int32 Int32/Int32Array
UInt32 UInt32/UInt32Array
Int64 Int64/Int64Array
UInt64 UInt64/UInt64Array
Float Float32/Float32Array
Double Float64/Float64Array
String String/StringArray

OPC-UA Protocol Specific Data Types

OPC-UA Data Type XRT Data Type
DateTime Int64/Int64Array

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
Security String Optional

The security policy to be used for connecting to the OPC-UA server Valid values are as follows:
  • None
  • Basic128Rsa15
  • Basic256Sha256
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
SecurityMode String Optional

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

The name of the DER file containing the certificate to use when establishing a secure connection 		certificate.der
PrivateKey String Optional

The name of the DER file containing the private key to use when establishing a secure connection 		private_key.der
RequestedSessionTimeout UInt32 Optional

The suggested timeout for sessions created between the device service and an OPC-UA server endpoint in milliseconds 		1200000
RootNode String Optional

The starting point for the TranslateBrowsePathsToNodeIds Service and the full server tree browse functionality in the following format:

<namespaceIndex>;<IDType>=<nodeID> e.g 3;i=42 		The servers root folder node
BrowseSubFilter String Optional

Describes the node types to be subscribed to as part of the browse functionality Valid values are as follows:
  • All
  • Variable
  • Event
 Empty
BrowseDepth UInt8 Optional

Represents the maximum depth of the server tree browse for this device 		0
BrowsePublishInterval Double Optional

The value to use for the requested publish interval when setting up system-generated subscriptions 		0.0
ConnectionReadingPostDelay UInt64 Optional

Delay (in milliseconds) to receiving monitored item readings after the device is added 		0

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.

OPC-UA Auto-events

Auto events, in the OPC-UA Device Service, provide the ability create subscriptions to monitor variable and event nodes. When the monitored item's value is updated on the server, the device service will recieve 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

Back to top