Contents
Note
The OPC UA adapters are provided for Microsoft Windows systems only.
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
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:
-
Drag the Adapters, Java Operators token from the Operators and Adapters drawer of the Palette view to the canvas.
-
Click on the canvas where you want to place the operator, then invoke the keyboard shortcut
O V. -
From the top-level menu, invoke >>.
-
-
In the search field, enter
OPCto narrow the list of adapters. -
Select the OPC UA adapter of interest and click .
In order run correctly, the adapters require that the Microsoft .NET Framework 4.8 or higher be installed on the machine.
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.
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 configuration file. Here is an example of such a section, containing all supported settings (long lines wrap to the next, for clarity):
name = "OPC-UA.conf"
type = "com.tibco.ep.streambase.configuration.adapter"
version = "1.0.0"
configuration = {
// An adapter group type defines a collection of EventFlow adapter configurations,
// indexed by adapter type.
AdapterGroup = {
// A collection of EventFlow adapter configurations, indexed by adapter type. This object
// is required and must contain at least one configuration.
adapters = {
// The root section for an EventFlow adapter configuration.
opc-ua = {
// Section list. This array is optional and has no default value.
sections = [
// A configuration for an EventFlow adapter named section.
{
// Section name. The value does not have to be unique; that is, you can have
// multiple sections with the same name in the same array of sections. This property
// is required.
name = "endpoint-definition"
// Section for setting adapter properties. All values must be strings. This object
// is optional and has no default value.
settings = {
id = "TestEndpoint"
// The discovery server to which to connect
discovery-uri = "opc.tcp://milo.digitalpetri.com:62541/milo"
// 0 to not re-attempt connection when the attempt fails, -1 to continuously re-attempt
num-reconnection-retries = "5"
reconnection-retry-interval-ms = "10000"
// Set to true to select the endpoint with the highest security level (a valid X509
// certificate will need to be provided below), false to use the lowest security
// (typically public anonymous access).
use-maximum-security = "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 X509 certificate if "use-maximum-security" above is set to true.
// Of course "application-certificate-store-path" can be adjusted to help locate this certificate.
application-certificate-store-path = "LocalMachine\\My"
application-certificate-subject-name = "CN=UA Client Test, DC=MYMACHINE"
application-certificate-thumbprint = "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 the epadmin encrypt secret command
username = ""
password = ""
// Modify these as needed
application-uri = "urn:localhost:TIBCO:MyApp"
product-uri = "http://tibco.com"
trusted-issuer-certificate-store-path = "LocalMachine\\Trusted UA Applications"
trusted-peer-certificate-store-path = "LocalMachine\\Trusted UA Applications"
rejected-certificate-store-path = "LocalMachine\\Rejected UA Certificates"
auto-accept-untrusted-certificates = "false"
reject-sha1-certificates = "false"
min-certificate-key-size = "1024"
add-application-certificates-to-trusted-store = "false"
send-certificate-chain = "true"
}
}
]
}
}
}
}
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.
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.
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.
Class name: Shows the fully qualified class name that implements the functionality of this operator. If you need to reference this class name elsewhere in your application, you can right-click this field and select Copy from the context menu to place the full class name in the system clipboard.
Start options: This field provides a link to the Cluster Aware tab, where you configure the conditions under which this operator starts.
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 Editor canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.
The OPC UA adapters have the following properties, with the exceptions noted for some properties only on particular adapters:
| Property | Data Type | Default | Description |
|---|---|---|---|
| OPC-UA Configuration | button | — |
Provides an Edit button. Click this to open
a configuration file named OPC-UA.conf file in the current project. If
the file does not exist, it is created in the project's |
| OPC Server Definition | combo box | Cleared |
REQUIRED. Specifies the ID of the OPC UA server to which to connect, as defined in the adapter configuration file. |
| Connect on Startup | check box | Cleared | CONTROL ADAPTER ONLY. Attempt to connect to the server when the application starts. |
| 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. |
Use the settings in this tab to allow this operator or adapter to start and stop based on conditions that occur at runtime in a cluster with more than one node. During initial development of the fragment that contains this operator or adapter, and for maximum compatibility with TIBCO Streaming releases before 10.5.0, leave the Cluster start policy control in its default setting, Start with module.
Cluster awareness is an advanced topic that requires an understanding of StreamBase Runtime architecture features, including clusters, quorums, availability zones, and partitions. See Cluster Awareness Tab Settings on the Using Cluster Awareness page for instructions on configuring this 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.
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.
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. |
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. |
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.
|
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. | |
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.
|
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.
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.
|
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. | ||
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. | ||
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. | ||
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.
|
||
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 fails if the input schema does not contain all the required fields, or if a valid OPC Server Definition hasn't been specified.
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.
The StreamBase installation includes a sample demonstrating the use of this operator. To load the sample in StreamBase, select > and look under the IoT section for an entry called OPC UA Adapters.