.. _user/protocols/opcua/opcuaClient: *************** OPC UA Client *************** This page describes how the Connectware can act as an OPC UA client. The Connectware can also act as a :ref:`OPC UA server `. .. _user/protocols/opcua/opcuaClient/subscriptions: OPC UA Subscriptions ======================= OPC UA distinguishes between *session*, *subscriptions* and *monitored items*. - Each Connectware connection creates exactly one *session* in the OPC UA terminology, where the Connectware acts as a *client* towards the server. - Within one session, the set of data endpoints are grouped in *subscriptions*. A subscription carries parameters like `publishInterval` and `maxNotificationsPerPublish` so that it controls the data flow between server and client. - Within each subscription, the actual data endpoints (also called *nodes*) are subscribed as *monitored items*. The monitored items are configured by parameters like `nodeId`, `attributeId`, `samplingInterval`, so monitored items control the collection of the data by the server. Each network *request* for creating these can create one or multiple monitored items per request. Connectware Subscriptions -------------------------- The Connectware tries to abstract this complexity away, combining as many endpoints as possible into the same subscription, and also 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 :ref:`here `. Hence, enabling/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. This "create monitored items request" is working very efficiently also for thousands of monitored items. Due to its importance, the relation of the OPC UA terminology to Connectware resources is listed once more: Session One Cybus::Connection is exactly one session. (OPC UA reference: `5.6.1 Session `_) Subscription All Cybus::Endpoints with the same `publishInterval` in the same connection, regardless of service commissioning file. (OPC UA reference: `5.13.1 Subscription `_) Monitored items All Cybus::Endpoints. (OPC UA reference: `5.12.1 MonitoredItem `_) Create Monitored Items Request The monitored items within one service, one connection, and with the same `samplingInterval` are combined into a single "create monitored items request" (OPC UA reference: `5.12.2 CreateMonitoredItems `_) Subscription Limitations ^^^^^^^^^^^^^^^^^^^^^^^^^ 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 within one "create monitored items request" might limited to e.g. 1000 nodes. This limit can even be looked up in the OPC UA node with nodeId ``ns=0;i=11714``. On the Connectware side this limit must be taken into account by setting the property `maxMonitoredItemsPerCall` in the `Cybus::Connection` resource to the respective value. This will ensure to split larger requests so that all requests stay within this limit. * Also, some maximum number of monitored items in total might be configured in the TIAPortal project. Unfortunately it is not known how to look up this value except directly in TIAPortal. If such a value is set, it is not possible for the Connectware to create any larger number of endpoints than this value. Regarding the created *subscriptions*: As of today, *subscriptions* are combined only by the `publishInterval` parameter. The remaining properties related to subscriptions are currently taken only from the first endpoint to be subscribed, while differing settings at subsequent endpoints are currently ignored. This concerns the following endpoint properties: `requestedLifetimeCount`, `requestedMaxKeepAliveCount`, `maxNotificationsPerPublish`, `priority`. Example ^^^^^^^^ This is an example configuration snippet with three endpoints (without the connection configuration): .. code-block:: yaml :linenos: resources: spindleSpeed: type: Cybus::Endpoint properties: protocol: Opcua connection: !ref opcuaConnection subscribe: nodeId: "ns=1;s=spindleSpeed" publishInterval: 1000 samplingInterval: 100 maxNotificationsPerPublish: 100 powerConsumption: type: Cybus::Endpoint properties: protocol: Opcua connection: !ref opcuaConnection subscribe: nodeId: "ns=1;s=powerConsumption" publishInterval: 1000 maxNotificationsPerPublish: 50 samplingInterval: 1000 temperature: type: Cybus::Endpoint properties: protocol: Opcua connection: !ref opcuaConnection subscribe: nodeId: "ns=1;s=temperature" publishInterval: 15000 samplingInterval: 15000 In the above example, two subscriptions will be created. One with `publishInterval` set to 1000ms and `maxNotificationsPerPublish` set to 100, the other one with `publishInterval` set to 15.000ms. 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 a fixed data sampling but rather applies a change-of-value filter to each particular data point automatically. Security Settings ================= For production use, the connection to the OPC UA server should only be established using the security profile ``SignAndEncrypt``. Any other security profile bears the risk that the communication between client and server can easily get manipulated or compromised. Per default, the built-in OPC UA server only allows connections with ``SignAndEncrypt`` security setting enabled (in the property ``securityModes``). Please use your Connectware credentials when authenticating to the OPC UA server by Connectware username and password user token. .. _user/protocols/opcua/opcuaClient_connection: .. include:: ../../protocolSchemas/OpcuaConnection.rst .. _user/protocols/opcua/opcuaClient_endpoint: .. include:: ../../protocolSchemas/OpcuaEndpoint.rst .. _user/protocols/opcua/examples: Example Commissioning Files =========================== Simple 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: .. literalinclude:: opcua-simple-example.yml :language: yaml :linenos: Download: :download:`opcua-simple-example.yml` More complex example -------------------- More complex example including an OPC UA server container from public docker hub: .. literalinclude:: opcua-example.yml :language: yaml :linenos: Download: :download:`opcua-example.yml` Output Format On Reading ========================= If data is read from OPC UA the output will be provided as 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/ .. code:: json { "timestamp": "", "value": "value" } Note: If 64-bit integers are being used (which are unsupported in JSON, but are supported in Javascript by the BigInt class), the value is returned as a string that contains the decimal number. Output Format On Writing ========================= When data is written to an OPC-UA endpoint, you will get the result of the operation over the **/res** topic like this: .. code:: json { "id": 29194, "timestamp":1629351968526, "result": { "value":0 } } Input Format ============ If data is written to OPC UA it must be provided as JSON object .. code:: json { "value": "" } .. _user/protocols/opcua/reconnection: Reconnection Behaviour ====================== In OPC UA connections -- just with any network connections -- it can happen that the connection is lost. In that case the Connectware's OpcuaConnection will automatically switch into `reconnecting` state and repeatedly try to re-establish the connection. The exact behaviour on how often this is tried can be controlled by the optional ``connectionStrategy`` properties, see :ref:`user/protocols/opcua/opcuaClient_connection`. The important property is ``maxDelay`` which sets the maximum waiting time (delay) between consecutive re-tries, in milliseconds. The waiting time will start with the value ``initialDelay``, then be increased step by step, until the ``maxDelay`` value. Example with initially 500ms waiting time, increasing up to 10 seconds: .. code-block:: yaml :linenos: resources: myConnection: type: Cybus::Connection properties: protocol: Opcua connection: host: !ref opcuaHost port: !ref opcuaPort options: connectionStrategy: initialDelay: 500 maxDelay: 10000 For further details see also the documentation of the internally used package `backoff`, https://www.npmjs.com/package/backoff .. _user/protocols/opcua/opcuaClient/events: Events for OPC UA ====================== Event subscriptions can be created in the connectware by adding the properties ``fields`` and ``eventTypes`` 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`. Also, the field names often additionally need a `sub-type`, which can be specified using a dot notation after the name. .. literalinclude:: opcua-events-example.yml :language: yaml :linenos: Download: :download:`opcua-events-example.yml` 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. .. literalinclude:: opcua-statusCodes-example.yml :language: yaml :linenos: Download: :download:`opcua-statusCodes-example.yml`