OPC UA Adapters

< Previous		Next >

Introduction

The TIBCO StreamBase® Adapter for OPC UA allows StreamBase to interact with data from an OPC UA (Open Platform Communications Unified Architecture) server. The adapters in this set include:

The OPC UA Control adapter, which is used to control the connection with the OPC UA server (connection, disconnection, server status, and so on).
The OPC UA Reader adapter, which is used to retrieve values from OPC UA Variable nodes.
The OPC UA Writer adapter, which is used to write values to OPC UA Variable nodes.
The OPC UA Subscriber adapter, which is used to subscribe to Variable nodes and get continuous updates when the nodes' values change.
The OPC UA Browser adapter, which is used to traverse the OPC UA server's node hierarchy and retrieve metadata for these nodes.

Placing an OPC UA Adapter on the Canvas

The OPC UA adapters are members of the Java Operators group in the Palette view in StreamBase Studio. Select the operator from the Insert an Operator or Adapter dialog, following these steps:

Open the Insert an Operator or Adapter dialog with one of the following methods:
1. Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.
2. Click on the canvas where you want to place the operator, then invoke the keyboard shortcut O V.
3. From the top-level menu, invoke Insert>Operator>Java.
In the search field, enter OPC to narrow the list of adapters.
Select the OPC UA adapter of interest and click OK.

Prerequisites

In order run correctly, the adapters require that the Microsoft .NET Framework 4.8 or higher be installed on the machine.

How the Adapters Work

All adapters have one input stream to receive commands. The schema for this command stream varies depending on the adapter type; each schema is described in a section below.

All adapters have an output stream to communicate status events (such as when an error occurs during the execution of a command). The schema for this stream is identical for all OPC UA adapter types and is described in a section below.

With the exception of the Control adapter, all adapters also have a second output port to emit the results of executing commands. For example, the Reader adapter uses this port to emit the value(s) it reads from the server.

Configuration

The different OPC UA operators share a connection to the same server, provided they are configured to do so. Each operator lists the servers available in the a combo box (see OPC UA Adapter Properties). The list's values are specified in a dedicated section of the application's adapter-configurations.xml file. Here is an example of such a section, containing all supported settings (long lines wrap to the next, for clarity):

<adapter-configurations>
  <!-- This section contains the configuration settings for the OPC-UA adapters -->
  <adapter-configuration name="opc-ua">
        
    <!--  Defines one OPC UA endpoint -->
    <section name="endpoint-definition">

      <setting name="id" val="TestEndpoint"/>

      <!-- The discovery server to which to connect -->
      <setting name="discovery-uri" val="opc.tcp://milo.digitalpetri.com:62541/milo"/>

      <!-- 0 to not re-attempt connection when the attempt fails, -1 to continously re-attempt -->
      <setting name="num-reconnection-retries" val="5"/>
      <setting name="reconnection-retry-interval-ms" val="10000"/>

      <!--
        Set to true to select the endpoint with the highest security level (a valid X.509
        certificate will need to be provided below), false to use the lowest security
        (typically public anonymous access).
      -->
      <setting name="use-maximum-security" val="false"/>

      <!--
        IMPORTANT! 
        'application-certificate-store-path' must point to a valid store in all cases.
                     
        'application-certificate-subject-name' and 'application-certificate-thumbprint'
        must point to a valid X.509 certificate if 'use-maximum-security' above is 
        set to true. Of course 'application-certificate-store-path' can be adjusted 
        to help locate this certificate.
      -->
      <setting name="application-certificate-store-path" val="LocalMachine\My"/>
      <setting name="application-certificate-subject-name" val="CN=UA Client Test, DC=MYMACHINE"/>
      <setting name="application-certificate-thumbprint" val="a306b24b05b28e7b3e2c4d23925c453e719a0b55"/>

      <!--
        Credentials to be used (if any) with the above certificate when
        connecting to the OPC UA server. You may leave these values empty
        to attempt access to public (or uncredentialed) servers/endpoints.
                     
        Note that 'password' value may be enciphered using StreamBase's 'sbcipher' command
      -->
      <setting name="username" val=""/>               
      <setting name="password" val=""/>
                                
      <!-- Modify these as needed  -->                
      <setting name="application-uri" val="urn:localhost:TIBCO:MyApp"/>
      <setting name="product-uri" val="http://tibco.com"/>
      <setting name="trusted-issuer-certificate-store-path" val="LocalMachine\Trusted UA Applications"/>
      <setting name="trusted-peer-certificate-store-path" val="LocalMachine\Trusted UA Applications"/>
      <setting name="rejected-certificate-store-path" val="LocalMachine\Rejected UA Certificates"/>
      <setting name="auto-accept-untrusted-certificates" val="true"/>
      <setting name="reject-sha1-certificates" val="false"/>
      <setting name="min-certificate-key-size" val="1024"/>
      <setting name="add-application-certificates-to-trusted-store" val="false"/>
      <setting name="send-certificate-chain" val="true"/>

    </section>
        
    <!-- Define other endpoints here -->          
  </adapter-configuration>
</adapter-configurations>

A best practice is to define your endpoints in this file before placing operator instances on the canvas, so that the lists are already available in the Properties view and the operators can be configured right away.

OPC UA Adapter Properties

This section describes the properties you can set for the adapters, using the various tabs of the Properties view in StreamBase Studio.

In following section tables, the Property column shows each property name as found in the one or more adapter properties tabs of the Properties view for this adapter.

Use the StreamSQL names of the adapter's properties when using this adapter in a StreamSQL program with the APPLY JAVA statement.

OPC UA General Tab

Name: Use this required field to specify or change the name of this instance of this component, which must be unique in the current EventFlow module. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Operator: A read-only field that shows the formal name of the operator.

Start with application: If this field is set to Yes (default) or to a module parameter that evaluates to true, this instance of this operator starts as part of the JVM engine that runs this EventFlow fragment. If this field is set to No or to a module parameter that evaluates to false, the operator instance is loaded with the engine, but does not start until you send an epadmin container resume command (or its sbadmin equivalent), or until you start the component with StreamBase Manager.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

OPC UA Adapters Properties

The OPC UA adapters have the following properties, with the exceptions noted for some properties only on particular adapters:

Properties Tab

Property	Data Type	Default	Description	StreamSQL Property
OPC Server Definition	combo box	Cleared	REQUIRED. Specifies the ID of the OPC UA server to which to connect, as defined in `adapter-configurations.xml` (refer to the Configuration section for details on this file)	opcServerID
Connect on Startup	check box	Cleared	CONTROL ADAPTER ONLY. Attempt to connect to the server when the application starts.	connectOnStartup
Log Level	drop-down list	INFO	Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE.	LogLevel

Concurrency Tab

Use the Concurrency tab to specify parallel regions for this instance of this component, or multiplicity options, or both. The Concurrency tab settings are described in Concurrency Options, and dispatch styles are described in Dispatch Styles.

Caution

Concurrency settings are not suitable for every application, and using these settings requires a thorough analysis of your application. For details, see Execution Order and Concurrency, which includes important guidelines for using the concurrency options.

Input Ports

The adapters have a single input port which is used to receive commands. The schema for this port is different for each adapter; the schemas are described in this section.

OPC UA Control Adapter Input Port

This port is used to connect or disconnect from the configured server, and to get the current connection status. Results will be issued on the adapter's Status output port.

Field Name	Field Type	Description
command	string	REQUIRED. The command to execute. One of connect, disconnect, getconnectionstatus.

OPC UA Browser Adapter Input Port

The Browser adapter allows your application to traverse the data hierarchy of the OPC UA server. Using this port you can retrieve the metadata of one or more nodes (by specifying them by Node ID in the NodeList field). This metadata includes the node's class (Object, Variable, and so on), its access levels and a list of the nodes it references.

Field Name	Field Type	Description
NodeList	list<string>	REQUIRED. Contains a list of one or more nodes for which to retrieve metadata and node references. Each string is expected to represent the valid node id of an OPC UA node of any type. If an entry is left null, the root node of the server will be queried.

OPC UA Reader Adapter Input Port

This port instructs the adapter to retrieve the current value of the specified OPC UA nodes. These nodes are expected to be of class Variable (since they are the only nodes that can contain a value).

Field Name	Field Type	Description
NodeList	list<string>	REQUIRED. Contains a list of one or more Variable nodes for which to retrieve the value. Each string is expected to represent the valid node id of an OPC UA node of type Variable.
MaxAge	long	If set, specifies the maximum age of a value (in milliseconds) beyond which the server should attempt to read a fresh value from the data source. A `null` value (or a value of `0`) for this field means the server will attempt to read a fresh value for each specified node.

OPC UA Writer Adapter Input Port

Using this port you can change the current value of one or more OPC UA nodes of class Variable.

Each value is specified as a string, and will be automatically parsed and converted to the correct type (Int8, DateTime, LocalizedText and so forth) based on the target node's data type information. See this conversion table for more information on the supported types.

Field Name		Field Type	Description
NodeList		list<tuple>	A list of tuples, each tuple describing one Variable node to update along with the value(s) with which to update it.
^	NodeID	string	The ID of the node to update.
	Value	string	If this node represents a scalar value, this field is expected to contain the new value with which to update the node (if the value is set to null, the node's value will similarly set to null). If this node represents an array of values, this field is expected to be left null.
	ValueArray	list<string>	If this node represents an array of values, this field is expected to contain the list of the values with which to update the node's array (and may be left null to set the node's value to null). If this node represents a scalar value, this field is expected to be null.

OPC UA Subscriber Adapter Input Port

This port is used to start (and stop) monitoring one or more Variable nodes for changes in their value. Periodical updates are issued by the adapter for each of these subscriptions until the subscription is removed via an Unsubscribe command to this port. Multiple subscriptions may be active at the same time.

Each Subscribe command sent to this port results in a single subscription being created, which monitors updates to all the specified nodes. Upon successful creation of a subscription, a status tuple will be emitted to the adapter's Status port to indicate success and more importantly to report the new subscription's ID, which must be specified in an eventual Unsubscribe command to cancel this subscription.

Field Name	Field Type	Description
Action	string	REQUIRED. One of Subscribe, Unsubscribe.
NodeList	list<string>	REQUIRED. Contains a list of one or more Variable nodes to which to subscribe. Each string is expected to represent the valid node id of an OPC UA node of type Variable.
SubscriptionID	string	UNSUBSCRIBE ACTION ONLY. Identifies which subscription to which to unsubscribe. This ID is reported by the Subscribe action's Status output port when subscribing. This setting is ignored during Subscribe actions.
PollingInterval	int	SUBSCRIBE ACTIONS ONLY. Specifies the number of milliseconds between updates from the subscription. A `null` value, a negative value or a value of `0` for this field means the server will employ the shortest supported update interval.

Output Ports

Every adapter (except the Control adapter) has an output port to emit tuples resulting from executing queries. In addition, every adapter has an output port to receive status events.

Status Output Port (Common to all OPC UA operators)

The status port emits tuples that describe the status of processing each input tuple. The schema of the output tuple is as follows:

Field Name	Field Type	Description
Status	string	Describes this event (`Connected`, `Disconnected`, `Success, Error`, and so on).
Time	timestamp	The time at which this status tuple was generated.
Info	list<tuple>	Contains any additional information pertaining to this event. Each tuple has two fields, `Name` and `Value` to describe one informational entry.

OPC UA Browser Adapter Results Output Port

The Browser adapter allows your application to traverse the data hierarchy of the OPC UA server. Using this port emits tuples describing the metadata of one or more nodes. This metadata includes the node's class (Object, Variable, and so on), its access levels and a list of the nodes it references.

Field Name			Field Type	Description
Nodes			list<tuple>	The list of all the nodes retrieved, in the order in which they were requested in the input tuple's `NodeList` field.
^	NodeID		string	The OPC UA ID of the browsed node.
	NodeClass		string	The class of this node (Object, Variable, and so on).
	DisplayName		string	The display name of the node.
	BrowseName		string	The browse name of the node.
	Description		string	The description the browsed node.
	AccessLevel		string
	UserAccessLevel		string
	WriteMask		string
	UserWriteMask		string
	MinimumSamplingInterval		int	The minimum interval at which the value of this node can be polled.
	ErrorCode		int	Error code (used when there is a problem reading this node).
	ErrorMessage		string	Error message (used when there is a problem reading this node).
	References		list<tuple>	The list of child nodes referenced by this node.
	^	ReferenceType	string	The type of reference represented by this entry.
		NodeID	string	The ID of the referenced (target) node.
		NodeClass	string	The type of the target node (Object, Variable, and so on).
		DisplayName	string	The display name of the target node.
		BrowseName	string	The browse name of the target node.
Input			tuple	The command tuple sent to the input port that triggered this result.

OPC UA Reader Adapter Results Output Port

The Reader adapter allows your application to query the current value attribute of one or more Variable nodes on the OPC UA server. See this conversion table for a list of supported types.

Each returned entry will be a string representation of the value, along with its data type and some additional metadata. Using this information the application can then parse the string into the desired type (Int32, Double, Timestamp, and so on) as required.

If a given node's value is an array rather than a scalar, the ValueArray (of type list<string>) field will be used instead of the Value field. Note that only arrays of rank 1 are supported.

If an error occurs when reading a node specified in the input tuple's NodeList field, the StatusCode field will provide an error code.

Note

Many OPC UA servers use case-sensitive node IDs.

Field Name		Field Type	Description
Values		list<tuple>	The list of all the values retrieved, in the order in which they were requested in the input tuple's `NodeList` field.
^	NodeID	string	The OPC UA ID of the Variable node containing this value.
	Value	string	The value if the data type of this Variable node's VALUE attribute is non-null and a scalar, or null if the attribute is null or if its rank is 1 or more (that is, if it represents an array of values).
	ValueArray	list<string>	If the value's rank is 1 (that is, the data type is an simple array of scalars) this field will contain the array while the `Value` field will be set to `null`. If the value is a scalar, this field will be set to `null`. Arrays of rank greater than 1 are not supported.
	ValueRank	int	-1 if the value is a scalar type, 1 if it's an array of scalars. The rank may also be greater than 1 in the case of multi-dimensional arrays, but such arrays are not supported so the actual `Value` and `ValueArray` fields will not be set in those cases.
	DataType	string	The data type of the value, or in the case of an array, the data type of the array's elements. See this conversion table for supported data types and their expected conversion to StreamBase types.
	SourceTimestamp	Timestamp	The source timestamp associated with this value.
	ServerTimestamp	Timestamp	The server timestamp associated with this value.
	StatusCode	string	Indicates whether the read operation was successful and the value is valid (`Good`) or some error value to indicate there was a problem.
Input		tuple	The command tuple sent to the input port that triggered this result.

OPC UA Writer Adapter Results Output Port

The Writer adapter allows your application to set or update the value attribute of one or more Variable nodes on the OPC UA server. See this conversion table for a list of supported types.

The output on this port informs on the result of the write operation for each specified node (Good in the case of success, or some other value related to the reason for failure).

Field Name		Field Type	Description
WriteStatus		list<tuple>	The list of the result of writing each entry, in the order in which they were requested in the input tuple's `NodeList` field.
^	NodeID	string	The OPC UA ID of the Variable node to which the write operation was attempted.
^	StatusCode	string	Indicates whether the write operation was successful (`Good`) or some error value to indicate there was a problem.
Input		tuple	The command tuple sent to the input port that triggered this result.

OPC UA Subscriber Adapter Results Output Port

The Subscriber adapter allows your application to monitor the current value attribute of one or more Variable nodes on the OPC UA server (see this conversion table for a list of supported types). Once a subscription is active, tuples will be emitted periodically to report on the monitored nodes' values.

Each returned entry in the tuple will be a string representation of the value, along with its data type and some additional metadata. Using this information the application can then parse the string into the desired type (Int32, Double, Timestamp, and so on) as required.

If a given node's value is an array rather than a scalar, the ValueArray (of type list<string>) field will be used instead of the Value field. Note that only arrays of rank 1 are supported.

If an error occurs when reading a node specified in the input tuple's NodeList field, the StatusCode field will provide an error code.

Note

Many OPC UA servers use case-sensitive node IDs.

Field Name		Field Type	Description
SubscriptionID		long	The ID of this subscription, as assigned by the server. Use this value in the SubscriptionID field of Unsubscribe commands to cancel this subscription and stop monitoring the associated nodes.
Values		list<tuple>	The list of all the values retrieved, in the order in which they were requested in the input tuple's `NodeList` field.
^	NodeID	string	The OPC UA ID of the Variable node containing this value.
	Value	string	The value if the data type of this Variable node's VALUE attribute is non-null and a scalar, or null if the attribute is null or if its rank is 1 or more (that is, if it represents an array of values).
	ValueArray	list<string>	If the value's rank is 1 (that is, the data type is an simple array of scalars) this field will contain the array while the `Value` field will be set to `null`. If the value is a scalar, this field will be set to `null`. Arrays of rank greater than 1 are not supported.
	ValueRank	int	-1 if the value is a scalar type, 1 if it is an array of scalars. The rank may also be greater than 1 in the case of multi-dimensional arrays, but such arrays are not supported so the actual `Value` and `ValueArray` fields will not be set in those cases.
	DataType	string	The data type of the value, or in the case of an array, the data type of the array's elements. See this conversion table for supported data types and their expected conversion to StreamBase types.
	SourceTimestamp	Timestamp	The source timestamp associated with this value.
	ServerTimestamp	Timestamp	The server timestamp associated with this value.
	StatusCode	string	Indicates whether the read operation was successful and the value is valid (`Good`) or some error value to indicate there was a problem.

Data Conversion

Because different nodes may contain values of different types, the various OPC UA operators represent each value as a string, but also provide metadata such as data type and array rank to inform on their actual representation in the OPC server. Using this information the StreamBase application can parse the string values into more representative types, for example to add the value of two nodes that are of type Double in the server.

The following table lists the various OPC UA data types, and the StreamBase types into which the values can be parsed.

OPC UA Type	StreamBase Type into which the string representation can be parsed
Boolean	boolean
Byte, SByte, Int16, Int32, UInt16	int
Int64, UInt64	long
ByteString	blob
Float, Double	double
DateTime	timestamp
Guid, LocalizedText, NodeId, QualifiedName, StatusCode, String, XmlElement	string
Single-dimensional array (array of rank 1)	A list<string> where each element can be parsed according to the type of the scalar contained in the OPC array
Variant	If the Variant represents one of the above types, it will be unwrapped into one of the above types
DataValue, DiagnosticInfo, ExpandedNodeId, ExtensionObject	Not supported.
Multi-dimensional array (array of rank 2 or greater)	Not supported.

Typechecking and Error Handling

Typechecking fails if the input schema does not contain all the required fields, or if a valid OPC Server Definition hasn't been specified.

Suspend and Resume Behavior

Upon suspension, the OPC UA adapters finish processing the current tuple, outputs the result tuple(s), then pauses waiting for input.

Upon resumption, the OPC UA adapters continue processing with the next input tuple.

In either case, any database connection is not modified.

OPC UA Adapter Sample

The StreamBase installation includes a sample demonstrating the use of this operator. To load the sample in StreamBase, select File>Load StreamBase Sample and look under the IoT section for an entry called OPC UA Adapters.

Back to Top ^