OPC UA TCP

The OPC UA TCP Connection connects to an OPC UA server and supports browsing, reading and writing. The connection supports built-in and complex UA types, Alarms & Events, and Methods. Below are details on the connection, input, and output settings and supported features.

Connection Settings

Host, Port and Path

These settings control the IP address or hostname for the OPC UA Server, it’s port, and the path. The path is informational only and not used as part of the connection.

Mode

The connection supports two modes; Subscribe or Poll.

Subscribe is the default mode, and recommended for most cases. In this mode, a single subscription is created to monitor data changes for all tags. The server sends the data changes on each Subscription Rate interval. The changes are cached locally in the connection, and reads pull from this cache. This mode works with both polled and event based data flows. Polled flows read from the cache, and event flows are triggered any time there is a data change for a tag.

In Polled mode, all reads are performed on-demand, meaning an explicit read is sent to the server asking for the current tag values. Depending on the server, this can make it harder for the server to optimize communications to the device, and generally is not recommended. This mode also does not work with event based data flows.

Subscription Rate

This setting only applies for Subscribe mode, and controls how often the subscription reports data changes for tags. This is also the default tag scan rate used by the OPC UA server to monitor tags. Data is received from the OPC UA server no faster than this rate.

Security

Level of security required by the OPC UA Sever. Valid options are None, Basic256Sha256-Sign and Basic256Sha256-SignEncrypt.

Security Policy: None

The Intelligence Hub supports the ability to turn off security as allowed by the OPC UA specification. In this mode, all communication is no encrypted (public) and not signed (unverified).

Security Policy: Basic256Sha256-Sign and Basic256Sha256-SignEncrypt

When security is enabled for the connection (Sign or SignEncrypt), the Intelligence Hub behaves as follows:

1. Automatically creates an application instance certificate the first time it is run (named app-certificate-private-key).

2. Connects to servers using asymmetric security algorithms encryption to securely exchange public keys and create a secure connection.

3. Signs or Signs and Encrypts all requests before sending it to the server.

4. Decrypts (if applicable) and verifies the signature of all responses coming from the server.

Authentication Type

The level of authentication required by the OPC UA Server. Valid options are Anonymous and Username-Basic256.

Input Settings

Inputs have a number of types to read different data from the UA server. The types are summarized in the table. Some input types can be used in polled or event based data flows, and others can only be used in polled data flows.

The settings and details for each type are described below.

Inputs support all built-in UA types, as well as custom structures and enumerated types (i.e. ExtensionObject in the UA specification).

Type: Tag

A Tag input is used to read a single tag.

Type: Collection

A Collection is a read of one or more tags that can exist anywhere in the OPC UA address space. The result is returned as a complex object containing all the tag names and their values.

Each tag in the collection has the following settings. Use the Find button to browse for tags to add to the collection.

The collection has the following additional settings.

Type: Branch

A Branch input is a read on a branch node in the OPC UA server that returns the nodes children.

Below is an example of an OPC UA hierarchy and the result Branch read value.

// OPC UA Branch structure
- rootBranch
    - childBranch1
        - tag1
        - tag2
    - childBranch2
        - tag1

// The result of the read in JSON
"rootBranch": {
    "childBranch1": {
        "tag1": 100,
        "tag2": "hello world",
    },
    "childBranch2": {
        "tag1": 1.2
    }
}

Type: Method

Method inputs execute an OPC UA Method in the server. Methods can take arguments and return values. It is recommended to use the browse feature to find and configure method inputs.

Method Output Arguments Example

If a method returns two values and no output arguments are defined the read result looks as follows.

{
	"outputArguments": {
		"output0": 0,
		"output1": 0
	}
}

If two output arguments are defined “myArg1” and “myArg2” the result looks as follows.

{
	"outputArguments": {
		"myArg1": 0,
		"myArg2": 0
	}
}

Type: Event

Event inputs subscribe to Alarms and Events for a node, and allow configuration of what attributes are returned as part of the event.

Note the input does not request a refresh on the first read, and will not return the current state of conditions. The first read subscribes to the node with the event filter, and only returns a result when a new event is generated in the server.

The Find feature for the Attribute Filter setting browses the OPC UA server for all event and condition types, and available attributes.

Attribute Filter Examples

By default, when there are no attributes in the filter, the input subscribes to the base EventId, SourceName, Severity, Time, Message, ConditionName, and Retain attributes. EventId is converted to a GUID if possible. Below is an example read result from the default filter.

{
  "eventId": "18a12e4c-40f1-9f46-924b-d62bd3deab21",
  "sourceName": "ExclusiveLevelAlarmTrigger",
  "severity": 800,
  "time": "2024-03-15T17:51:09.448Z",
  "message": "Exclusive level alarm active in LowLow",
  "conditionName": "ExclusiveLevelAlarm",
  "retain": true
}

Now assume the Find feature is used to find Event/Condition types and select only the EventId, SourceName, and MyCustomAttribute attributes for the filter. The read result looks follows. Note MyCustomAttribute is not in the event data, so it’s ignored.

{
  "eventId": "18a12e4c-40f1-9f46-924b-d62bd3deab21",
  "sourceName": "ExclusiveLevelAlarmTrigger"
}

Output Settings

OPC UA outputs support writing to single tag or a branch. When writing to a branch, the out tries to match the write data to the OPC UA branch address space. Below is an example of how this mapping works.

// Example payload being written to OPC UA Output
{
    "branch1": {
        "tag1": 1,
        "branch2": {
            "tag2": 2,
            "branch3": {
                "tag3": 3
            } 
        }
    }
}

// Example OPC UA branch structure. In this example the payload's branch1.branch2.tag value maps to the branch and is 
// written. tag1 and tag3 do not map and are ignored. 
- branch1
    - branch2
        - tag2
        - branch3

Namespace Index, Identifier Type, and Identifier

The tag or root node the output writes to.

Data Type

The data type used for the write. OPC UA is generally very strict on matching the data type of the server and this option provides control over this from the client side. The following options exists:

• Auto: The client will browse or read the UA Server tags data type before the write and attempt to convert the write value to the UA Server required value. This option is often used when writing complex data to a branch
• Implicit: The client will use the data type of the value being written.
• Boolean, String, etc: Use this data type for the write.

If the output cannot convert that write type to the type specified by this setting, the write will fail and output an error to the logs.

Max Branch Depth

When writing to a branch, the output first does a browse to get the tags for the branch. This setting controls how deep the browse will traverse. From the above example, if the Max Branch Depth was set to 1, tag2 would not be browsed and written to, and would instead be ignored.

Cache Interval

Like the branch reads setting, this controls how often the browse cache is refreshed to detect changes in the branch.

Named Root

When disabled, the payload is mapped to the OPC UA server’s branch structure as expected. When enabled, this setting allows writing multiple Instances to a single branch, where the root branch has a child branches with each Instance name. This allows a single flow to send multiple instances to the same output. For example, assume the OPC UA root branch looks as follows. Enabling this setting will cause the write to map to rootBranch.instance1 versus just rootBranch.

- rootBranch
    - instance1
        - temp
    - instance2
        - temp