.. _OPCUA:

OPC-UA Interface
================

The OPC-UA interface is provided by the :ref:`vnx.opc_ua.Server` and :ref:`vnx.opc_ua.Proxy` modules.

They allow to access internal modules via OPC-UA method calls,
as well as call methods on another OPC-UA server via a :ref:`LUA_script` for example.


Server
------

To enable the :ref:`vnx.opc_ua.Server` set the following config option:

.. code-block:: sh
	
	cd ~/pilot
	echo true > config/local/enable_opcua_server

The server will listen on the address ``opc.tcp://0.0.0.0:4840``.
The port ``4840`` is the default port for OPC-UA but you can also configure a
different port.

The server module is called ``OPC_UA_Server``, so it can be configured
:ref:`as usual <Configuration>`
by a config file ``config/local/OPC_UA_Server.json``.

Exports
#######

* Pilot modules and their methods are advertised by the server as OPC-UA services.
  The methods can be called according to the OPC-UA specification.
  The list of exported services is given by the config key ``export_services``.
* Pilot topics are advertised as OPC-UA variables and continually updated whenever
  a new value is published.
  The list of exported topics is given by the config key ``export_topics``.


To expand any of these lists, put a snippet like this in the configuration file:

.. code-block:: javascript
	
	{
		"export_services+": [
			"AnotherModule",
			...
		],
		"export_topics+": [
			"another.topic",
			...
		]
	}

In order to `replace` any of the lists, omit the respective ``+`` character.


Security
########

The OPC-UA server supports encrypted communication. To enable it, you have to
create or obtain a certificate and put the path in the configuration.
You should also consider revisiting the key ``security_policies`` and adjust it
to your needs.

.. code-block:: javascript

	{
		"certificate_file": "/some/path/to/server_cert.der",
		"private_key_file": "/some/path/to/server_key.der",
		"security_policies": [
			"NONE",
			"BASIC_256_SHA_256",
			"AES_128_SHA_256_RSA_OAEP"
		]
	}


Proxy
-----

To run a :ref:`vnx.opc_ua.Proxy` which connects to another OPC-UA server
create the following config file ``config/local/opcua_proxy_map``:

.. code-block:: javascript
	
	[
		["OPC_UA_Proxy_1", "opc.tcp://127.0.0.1:4840"],
		...
	]

The above proxy will be available unter the module name ``OPC_UA_Proxy_1``, see :ref:`LUA_script` for examples on how to use it.

:ref:`As usual <Configuration>`, the module can be configured
by a config file ``config/local/OPC_UA_Proxy_1.json``.


Security
########

You can configure encrypted communication of the Proxy module. First obtain or
generate a certificate and put the path in the configuration file. You should
also consider chooosing a reasonable value for the key ``security_mode``.

.. code-block:: javascript

	{
		"certificate_file": "/some/path/to/client_cert.der",
		"private_key_file": "/some/path/to/client_key.der",
		"security_mode": "SIGN_AND_ENCRYPT"
	}



Certificates
------------

To create self-signed certificates for the server and the proxy side, use the
script provided by the open62541 project
`here <https://github.com/open62541/open62541/tree/c95fe0f2e0f0433763a23c01958fbdb876e84250/tools/certs>`__
as follows::

	python create_self-signed.py -k 4096 -c server -u urn:open62541.server.application
	python create_self-signed.py -k 4096 -c client -u urn:open62541.client.application

The ``-u`` switch sets the application URI that must match the one configured
in the module. The values given here are the defaults.


Data Types
----------

Primitive data types are directly mapped to their OPC-UA counter parts, such as ``int`` to ``INT32``, ``float`` to ``FLOAT``, etc.
``string`` is directly mapped to a OPC-UA ``STRING``. Arrays of said types are directly mapped to OPC-UA arrays.

Anything else will be converted to JSON and transported via a ``LocalizedText`` object, with the ``locale`` set to ``JSON``.