OPC UA Client

At the component level, you set general and shared configurations that are, then, inherited by the endpoints. It is the highest configuration level.

For example, a component may have security settings, credentials for authentication, urls for network connection and so forth.

Some components only have a few options, and others may have many. Because components typically have pre-configured defaults that are commonly used, then you may often only need to configure a few options on a component; or none at all.

You can configure components using:

You usually spend more time setting up endpoints because they have many options. These options help you customize what you want the endpoint to do. The options are also categorized into whether the endpoint is used as a consumer (from), as a producer (to), or both.

Configuring endpoints is most often done directly in the endpoint URI as path and query parameters. You can also use the Endpoint DSL and DataFormat DSL as a type safe way of configuring endpoints and data formats in Java.

A good practice when configuring options is to use Property Placeholders.

Property placeholders provide a few benefits:

The following two sections list all the options, firstly for the component followed by the endpoint.

If the server uses a dedicated discovery endpoint (e.g. /discovery), which may support different (less secure) security policies, then you can make use of this via the parameter discoveryEndpointSuffix, which will be appended to the endpointUri. Or by using an explicit discoveryEndpointUri.

The client uses the host and port information from the endpoint information, queried from the server. However in some situations this endpoint URI might be different, and wrong from the point of view of the connecting client (e.g. an internal hostname or internal port).

In this case it is possible to set the parameter(s) overrideHost or overridePort to true, which will take the discovered endpoint information, but override the host or port information with the value(s) of the original URI.

In order to define a target node a namespace and node id is required. In previous versions this was possible by specifying nodeId and either namespaceUri or namespaceIndex. However this only allowed for using string based node IDs. And while this configuration is still possible, the newer one is preferred.

The new approach is to specify a full namespace+node ID in the format ns=1;i=1 which also allows to use the other node ID formats (like numeric, GUID/UUID or opaque). If the node parameter is used the older ones must not be used. The syntax of this node format is a set of key=value pairs delimited by a semi-colon (;).

Exactly one namespace and one node id key must be used. See the following table for possible keys:

As the values generated by the syntax cannot be transparently encoded into a URI parameter value, it is necessary to escape them. However Camel allows to wrap the actual value inside RAW(…), which makes escaping unnecessary. For example:

The following routes monitor one node and write another, on the server of the OPC UA Server example. A consumer receives a DataValue for each change, and ${body.value.value} is the value. A producer writes the message body to its node:

A consumer can monitor several nodes with the nodes option instead of node (the two options cannot be combined). The consumer creates the monitored items of all nodes together and deletes them together when it stops. Every value arrives in its own exchange, and the CamelMiloNodeId header holds the node ID as it was configured.

The nodes option takes a comma-separated list of Node IDs. The entries are trimmed, empty entries are skipped and a node that is listed twice is monitored once:

A string node ID that contains a comma cannot be used in nodes; monitor it with the node option instead. Long lists can come from a property placeholder, for example nodes=RAW({{tags}}).

All nodes of the list share the samplingInterval, queueSize and omitNullValues options of the consumer and its monitor filter (monitorFilterType, dataChangeFilter*). Tags that need a different sampling interval or deadband need a consumer of their own.

A node that does not exist on the server does not affect the other nodes. A node that cannot be monitored is reported once with its status code and is not retried; restarting the route or a rebuilt connection to the server creates the monitored items again. A node whose namespace URI (nsu=) is not in the namespace table of the server is reported in the same way. The consumer delivers one exchange with the bad status code for such a node, and the CamelMiloNodeId header names it.

A data change with a Bad or Uncertain status is always delivered, even when its value is null; omitNullValues only omits a null value with a Good status. This includes the first notification of a monitored item: it carries the current value of the node, at startup and again after a reconnect, so it can be a Bad status such as Bad_WaitingForInitialData or the status of a milo-server item that was not written yet. To skip such a notification, a route filters on its status code (getStatusCode() of the DataValue body); a filter on isGood() would also drop the Bad status of a failed sensor.

The default omitNullValues=true also omits a null value with a Good status that follows a Bad status, so the route does not learn that the node recovered. Set omitNullValues=false for a node whose value can be null, such as a String.

The consumers of a connection share one subscription on the server. When the server stops publishing for it (no notification or keep-alive within about one and a half keep-alive intervals), Camel checks whether the server still has the subscription. If the server does not confirm it, or when the server reports that the subscription timed out (Bad_Timeout), Camel deletes it and, once the server has confirmed that it is gone, creates it again in the existing session. A node that can no longer be monitored is reported as described above and does not affect the other nodes.

A route that is slow to process a value stops the publishing as well, because the client asks the server for more notifications only as the routes finish processing the ones it received. The subscription is then kept, unless the route takes longer than the lifetime of the subscription, which lets it time out on the server.

A check or a delete that fails because the connection was lost is left to the session recovery of the client, which restores the session once the server can be reached again. The subscription then resumes publishing, or it is created again as above when the server no longer has it. If the server no longer has the session either, for example after a restart, the subscription cannot be transferred to a new session and the connection is rebuilt. A network that drops silently can stop the publishing before the client notices that the connection is lost; if the network is back before that, the check reaches the server and is handled as above.

Any other failure of the delete, or a subscription that cannot be created again, rebuilds the connection to the server. After the subscription is recreated, every monitored item delivers its current value again, and value changes in between are not delivered.

It is possible to perform methods calls on OPC UA nodes. If the parameter method is set to the Node ID of a method call (the node ID must be set to the parent object in this case), then a method call will be performed instead of a write operation.

Input parameters are taken from the body:

The component provide a producer to read values from multiple opc-ua nodes. The Node-IDs will be defined in the header CamelMiloNodeIds as list of strings. (see Node-ID for the ID format).

Example:

The read is asynchronous. Without the CamelMiloAwait header, or defaultAwaitWrites=true on the endpoint, the route goes on before the values are in the body.

Built-in OPC UA data types are read and written transparently. Values whose node has a custom (server-defined) data type are instead returned as an org.eclipse.milo.opcua.stack.core.types.builtin.ExtensionObject, which can only be decoded (or, for writes, encoded) with an EncodingContext obtained from the underlying milo client.

The component does not decode these values automatically, because it cannot reliably determine which encoding context applies. Instead, the active OpcUaClient is exposed through MiloClientConnection.getOpcUaClient(), so you can obtain its encoding contexts and perform the encode/decode yourself:

When setting the allowing security policies is it possible to use the well known OPC UA URIs (e.g. http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15) or to use the Milo enum literals (e.g. None). Specifying an unknown security policy URI or enum is an error.

The known security policy URIs and enum literals are can be seen here: SecurityPolicy.java

When allowedSecurityPolicies is not set, the client accepts every security policy the server offers and uses the endpoint with the highest security level reported by the server, which can be None. To make sure the connection is secured, set allowedSecurityPolicies to the secured policies you expect the server to offer.

When the selected endpoint uses a security policy other than None, the client validates the certificate of the server when it opens the secure channel and the session. Configure the trusted certificates with one of these options:

With trustListDirectory, the client refuses a server certificate that:

A failed host name, key usage or extended key usage check is only logged. A certificate that does not chain up to a trusted certificate is written to rejected/certs, from where it can be moved to trusted/certs once it has been checked. A certificate refused for another reason is not written there. To use other checks, configure a certificateValidator, for example a DefaultClientCertificateValidator created with the ValidationCheck set you need.

If neither option is configured, the client does not connect to an endpoint that uses a security policy other than None. Setting trustAllCertificates to true makes the client accept any server certificate instead. This is insecure: the connection is encrypted, but the client does not authenticate the server it talks to.

When the server certificate cannot be validated, the client logs a WARN message that starts with Failed to connect, and tries again every 10 seconds, so a certificate moved to trusted/certs is used at the next attempt. A producer fails with IllegalStateException: No connected, whose cause gives the reason.

The same validator checks the server certificate that the user name and password are encrypted with. With the security policy None, the server is not authenticated, whatever the configuration.

A secured policy also requires a client certificate and key, configured with keyStoreUrl and the related options. For example: