.. _user/protocols/opcua:

******
OPC UA
******

**O**\pen **P**\latform **C**\ommunications **- U**\nified **A**\rchitecture, or
OPC UA for short, describes a machine-to-machine (M2M) communication protocol
developed by the `OPC Foundation <https://opcfoundation.org/>`_. It is widely
used for communication with industrial equipment and systems for data collection
and control.

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/opcuaServer>`.

Subscription Strategies
=======================

OPC UA distinguishes between *subscriptions* and *monitors*. A subscription
carries parameters like `publishInterval` and `maxNotificationsPerPublish` so
that it controls the data flow between server and client. Multiple monitors can
be added to each subscription, with parameters like `nodeId`, `attributeId`,
`samplingInterval`, so monitors control the *gathering* of the data by the
server.

The Connectware tries to abstract this complexity away and automatically
combines monitors to as few subscriptions as possible. *Important*: As of today,
subscriptions are combined only by the `publishInterval` parameter. Other
subscription parameters such as `maxNotificationsPerPublish` will be taken only
from the first mapping, and subsequently ignored.

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.


Example:

.. 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, 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.

.. _user/protocols/opcua_connection:

.. include:: ../protocolSchemas/OpcuaConnection.rst


.. _user/protocols/opcua_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
=============

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": "<unix timestamp in ms>",
    "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.

Input Format
============

If data is written to OPC UA it must be provided as JSON object

.. code:: json

  {
    "value": "<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_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