Ctrlk
Contact Uscybus.io
For the complete documentation index, see llms.txt. This page is also available as Markdown.

OPC UA Client

Configure Connectware as an OPC UA client to exchange data with OPC UA servers on your industrial equipment.

This page describes how Connectware can act as an OPC UA client. Connectware can also act as an OPC UA server.

For more information on OPC UA, see the OPC Foundation Reference.

For configuration reference, see:

Node IDs

You identify each OPC UA node by its nodeId or its browsePath. NodeIds follow the string encoding rules from the OPC UA specification (see OPC 10000-6, section 5.1.12).

NodeId Formats

Connectware supports three forms of NodeIds. Each form applies to read, write, and subscribe endpoints.

Form
Syntax
Example

Identifier only

<identifier>

i=2258

Namespace index

ns=<namespaceIndex>;<identifier>

ns=3;s=FastUInt2

Namespace URI

nsu=<namespaceURI>;<identifier>

nsu=http://microsoft.com/Opc/OpcPlc/;s=FastUInt2

The identifier-only form refers to a node in the default namespace (namespace index 0).

Use the namespace URI form when the namespace index of a server may change between deployments or restarts. Connectware resolves the URI to the current namespace index at runtime by querying the server's namespace array. The URI stays stable across server configuration changes, whereas the index depends on the server's namespace registration order.

Identifier Types

The <identifier> component uses a type prefix followed by the value:

Prefix
Type
Example

i=

Numeric

i=2258

s=

String

s=TemperatureSensor/Output

g=

GUID

g=09087e75-8e5e-499b-954f-f2a9603db28a

b=

Opaque

b=M/RbKBsRVkePCePcx24oRA==

Opaque identifiers are Base64-encoded byte strings.

OPC UA Subscriptions

OPC UA distinguishes between sessions, subscriptions, and monitored items.

  • Each Connectware connection creates exactly one session in the OPC UA terminology, where Connectware acts as a client towards the server.

  • Within one session, the set of data endpoints are grouped into subscriptions. A subscription carries parameters like publishInterval and maxNotificationsPerPublish that control the data flow between server and client.

  • Within each subscription, the actual data endpoints (also called nodes) are subscribed as monitored items. Monitored items are configured by parameters like nodeId, attributeId, and samplingInterval, which control how the server collects the data. Each network request for creating these can create one or multiple monitored items per request.

Connectware Subscriptions

Connectware abstracts this complexity by combining as many endpoints as possible into the same subscription and grouping monitored items creation into the same request. This is done according to the following criteria:

  • Each OPC UA Cybus::Connection resource creates exactly one session.

  • Within this session, all OPC UA Cybus::Endpoint resources with the same publishInterval property are combined into one subscription. This holds even across different service commissioning files using inter-service referencing, see here. Therefore, enabling or disabling additional services with additional endpoints will add or remove those endpoints from the currently available subscription.

  • Every OPC UA Cybus::Endpoint resource corresponds to one monitored item

  • Within one subscription and within the same service commissioning file, all endpoints (monitored items) with the same samplingInterval property are combined into one common creation request called CreateMonitoredItemsGroupRequest. This request works efficiently even for thousands of monitored items.

When endpoints are combined into one subscription, the subscription-level properties (requestedLifetimeCount, requestedMaxKeepAliveCount, maxNotificationsPerPublish, and priority) are taken from the first endpoint. Differing values on subsequent endpoints are ignored.

Server Limits on Monitored Items

Some OPC UA servers are known for imposing certain limits on the number of monitored items, either in total, or per subscription, or per request.

In particular, an embedded OPC UA server on a Siemens S7-1500 or S7-1200 PLC is known for certain restrictions, see System limits of OPC UA Server.

  • For example, the maximum number of monitored items that can be created in one request might be limited to 1000 nodes. Many servers advertise this limit through a capability node (nodeId ns=0;i=11714). Connectware reads this value during connection setup and splits larger requests automatically. See Setting the Maximum Monitored Items per Call.

  • Additionally, a maximum number of monitored items in total might be configured in the TIA Portal project. Unfortunately, there is no known way to look up this value except directly in TIA Portal. If such a value is set, Connectware cannot create more endpoints than this limit.

Setting the Maximum Monitored Items per Call

The maxMonitoredItemsPerCall property on the Cybus::Connection resource caps how many monitored items Connectware creates per request.

  • Unset (default): Connectware reads the server's limit at connection setup and matches it. If the server does not report a usable value, all monitored items go into a single request.

  • Set explicitly: Connectware always uses your value. This is useful when the server does not advertise a limit. If the value exceeds the server's reported limit, Connectware logs a warning and the server may reject the request.

The same batching applies on reconnect and resubscription. Each automatic split is written to the debug log.

Example

This is an example configuration snippet with three endpoints (without the connection configuration):

In the above example, two subscriptions will be created. One with publishInterval set to 1000ms and maxNotificationsPerPublish set to 100, and another with publishInterval set to 15000ms. The sampling of the individual source values will be set as expected by the specified samplingInterval property, but remember that OPC UA does not offer fixed data sampling but rather applies a change-of-value filter to each data point automatically.

Service Commissioning File Example

Basic Example

This is a simple OPC UA connectivity example that only subscribes to the “Server Status” node of an OPC UA server. The proposed node (endpoint) can also be used if the server would otherwise close the connection, which has been observed for some specific versions of OPC UA servers on a S7 PLC.

The example will need some OPC UA server available in your network:

opcua-simple-example.yml
854B
Open

Advanced Example

More complex example including an OPC UA server container from public Docker Hub:

opcua-example.yml
3KB
Open

Example with Method Endpoint

opcua-client-method-example.yml
3KB
Open

Output Format on Reading

When data is read from OPC UA, the output is provided as a JSON object with value and timestamp.

The given timestamp is the OPC UA “Source Timestamp” which was set on the data source side, see https://reference.opcfoundation.org/v104/Core/docs/Part4/7.7.3/

If 64-bit integers are used (which are unsupported in JSON but are supported in JavaScript by the BigInt class), the value is returned as a string containing the decimal number.

Output Format on Writing

Variables

When data is written to an OPC UA endpoint, you will receive the result of the operation on the /res topic like this:

The id field is only included if the original request contained an id. The value is returned unchanged and can be used to correlate request and response. This behavior applies to both read and write operations.

Method Calls

Method calls follow the same pattern as variable operations:

  1. Write the method call data to the /set topic.

  2. Receive the result on the /res topic.

Example

Input Format

Variables

When writing to an OPC UA variable, format the data as a JSON object.

Method Calls

Calling OPC UA methods follows the same pattern as writing to OPC UA variables.

The value has to include the input arguments like this. You can optionally include an id parameter.

Complex Data Types

OPC UA nodes can hold simple values (Boolean, Int32, String) or structured values (objects with fields, nested objects, arrays). Connectware maps structured OPC UA values to JSON objects, so you can read, subscribe, and write them using standard Cybus::Endpoint resources.

In OPC UA, complex data types are modeled as structured DataTypes and exchanged at runtime as ExtensionObjects. A complex data type is the logical definition of the data structure, while an ExtensionObject is the physical container used to transport that data over the network.

The following operations are supported for complex data types:

  • Read: Retrieve the current value of a complex variable node.

  • Write: Update a complex variable node with new structured data.

  • Subscribe: Receive notifications when a complex variable changes.

  • Method call: Invoke OPC UA methods with complex data type parameters.

Prerequisites

Before working with complex data types, ensure the following:

  • Identify the nodeId of the variable node that exposes the structured value on the OPC UA server.

  • For method calls, identify the nodeId of the corresponding method node.

  • Make sure the OPC UA server already defines the structured DataType for that node.

  • Know the exact structure of the DataType as defined on the server, including field names, nesting, scalar versus array definitions, and data types. The JSON payload used in Connectware must match this structure exactly.

  • Case sensitivity is important. Use the exact field name as defined on the OPC UA server. For example, if the field name is MachineName, then machineName will not work (OPC UA standard).

Example Structure

In the examples below, the complex value has this JSON structure:

When writing data, the JSON structure must match the data type defined on the OPC UA server for that node.

Service Commissioning File Example

No special configuration is required to work with complex data types. Use standard Cybus::Endpoint resources with the nodeId of the complex variable node:

Subscribing and Receiving Complex Values

  1. Create a Cybus::Endpoint with the nodeId of the complex variable node. No special configuration is required for structured data.

  2. Subscribe as usual using the nodeId.

  3. The structured object appears inside the value field of each message.

Incoming message format:

Writing a Complex Value to a Variable Node

To write complex data to a variable node, send the JSON object as the payload's value.

Example Topic

services/robot/writeRobotEndpoint/set

Payload

Put the structured object inside value.

Result

You will receive the operation result on the /res topic, same as writing primitives.

Calling a Method with a Complex Input Parameter

  1. Publish the method call payload to the endpoint /set topic.

  2. Read the call result on the /res topic.

Example Topic

services/robot/setRobotMethod/set

Payload

Include the structured object inside inputArguments. In this example, value holds the entire object as defined in the OPC UA method for the first argument.

Result

Method calls follow the same /set and /res pattern as variable writes.

Deadband Limitations

The deadbandType and deadbandValue options are generally not applicable to complex data types.

However, if a primitive numeric field inside a complex structure is accessible via its own variable node (i.e., having its own nodeId), you can create a separate endpoint for that specific node and apply deadband settings there.

Reconnection Behavior

In OPC UA connections, as with any network connections, the connection can be lost. When this happens, Connectware's OpcuaConnection will automatically switch into a reconnecting state and repeatedly try to re-establish the connection.

You can control the exact behavior of how often this is attempted by the optional connectionStrategy properties, see Connection Properties. The maxDelay property sets the maximum waiting time (delay) between consecutive retries, in milliseconds. The waiting time starts with the initialDelay value and is then increased step by step until reaching the maxDelay value.

Example with initially 500ms waiting time, increasing up to 10 seconds:

For further details, see the documentation of the internally used package backoff: https://www.npmjs.com/package/backoff

Events for OPC UA

Event subscriptions can be created in Connectware by adding the fields and eventTypes properties to the Cybus::Endpoint resource as shown in the example below.

The names for the fields should be qualified names. Often, this will require the field name to also contain a namespace identifier, for example 4:MyQualifiedName.3:SubitemQualifiedName. Additionally, the field names often need a sub-type, which can be specified using dot notation after the name.

opcua-events-example.yml
1KB
Open

Accessing Status Codes for Values

The quality of a data value in OPC UA is represented by predefined status codes. The statusCode is transferred to the $context object and can be retrieved within the Rule Engine of a Cybus::Endpoint via $context.raw.statusCode as shown in the example below.

opcua-status-codes-example.yml
1KB
Open
PreviousOPC UA
NextOPC UA Client Connection Properties

Last updated

Was this helpful?