.. _user/protocols/opcua/opcuaServer:

***************
OPC UA Server
***************

This page describes how the Connectware can act as an OPC UA server. The
Connectware can also act as a :ref:`OPC UA client <user/protocols/opcua/opcuaClient>`.

To run an OPC UA server, the commissioning file must contain a *server* resource
of type ``Cybus::Server::Opcua``. This will start an OPC UA server that can be accessed
by OPC UA clients. From the OPC UA client, this server is reachable by the
following address:

``opc.tcp://<connectwareHost>:4841<resourcePath>``

Note: The OPC UA server provided by the Connectware uses the non-standard port
number 4841 (whereas standard OPC UA uses port 4840) in order to avoid port
number collisions on computers where another OPC UA server is already running.
Also note: The Connectware can run exactly one instance of an OPC UA server, not
multiple instances.

If your Connectware instance is running on a system that is reachable by a DNS
hostname, this hostname must be specified in the ``hostname`` property,
so that the server is reachable from outside of the Connectware docker network.
The value `localhost` is not valid in this case, as `localhost` refers to the
local Docker container but not the host itself, which means this name is not
reachable from other containers or the host system.

Additionally, the property ``resourcePath`` is important when when connecting
to the OPC UA server. This property defines the prefix of the connection string
and defaults to the value ``/UA/CybusOpcuaServer``. Please note that this string
has to be added to the URL when connecting from a client to the OPC UA Server.
Otherwise the client might not be able to connect successfully.

The server configuration is specified by the properties of the server resource.
The actual data points (*nodes* in OPC UA) are specified by defining resources
of type ``Cybus::Node::Opcua``, one resource for each node. The nodes are
structured in a tree-like hierarchy. There must be exactly one *root node*,
which has its ``parent`` property set as a reference to the *server* object. All
other nodes reference either the root node or other intermediate nodes as
``parent``, forming a tree of nodes on the OPC UA Server.

Nodes can be defined within the same service as the OPC UA server, or also in
other services using inter-service referencing using the :ref:`service-id
<user/services/service-id>`. It is thus possible to add or remove nodes while
the OPC UA server is running, by adding more service commissioning files.

.. _user/protocols/opcua_server:

.. include:: ../../protocolSchemas/OpcuaServer.rst


.. _user/protocols/opcua_dataNode:

.. include:: ../../protocolSchemas/OpcuaNode.rst

Example Commissioning File
==========================

Download: :download:`opcua-server-example.yml`

.. literalinclude:: opcua-server-example.yml
  :language: yaml
  :linenos:


Output Format
=============

If the server receives data from an external OPC UA client, the output on the
internal MQTT broker will be provided as JSON object:

.. code:: json

  {
    "timestamp": "<unix timestamp in ms>",
    "value": "value"
  }

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

If the server should provide data to an external OPC UA client, the message on
the internal MQTT broker must be published in this format:

.. code:: json

  {
    "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 must be given as a
string that contains the decimal number.