.. _user/services/structure/resources/node:

***********
Cybus::Node
***********


A *node* describes a single data point that is managed by a *server*. An
external client may read data from a node, or write data to a node.

In a concrete service, the data node will typically be mapped (using a
:ref:`user/services/structure/resources/mapping` resource) into an application
specific MQTT topic. The application-specific topic reflects either the data the
server is providing, or the data received at the server from an externally
connected client.

General Properties
==================

================= ============ ============
Property          Type         Required
================= ============ ============
`parent`_         ``string``   **Required**
`operation`_      ``string``   Optional
`rules`_          ``object[]`` Optional
`qos`_            ``integer``  Optional
`retain`_         ``boolean``  Optional
`targetState`_    ``enum``     Optional
`topic`_          ``string``   Optional
`inputBuffering`_ ``object``   Optional
================= ============ ============

parent
------

Reference to another :ref:`user/services/structure/resources/node` which is the
parent of this node, so that these relations define the hierarchical tree
structure of the data points. For the top-most nodes of the tree, this property
must refer to the :ref:`user/services/structure/resources/server` resource
instead of a node resource.

- is **required**
- type: ``string``

operation
---------

For nodes which provide or receive data from an external client, this property
defines the direction of the data flow.

- type: ``string``

  - The value of this property **must** be equal to one of the below:

    - ``serverProvides``
    - ``serverReceives``
    - ``serverProvidesReceives``

.. _rules:

rules (experimental)
--------------------

-   is optional
-   type: ``array`` of :ref:`user/services/structure/resources/rules`

You may specify rules to your payload here before providing it to or after
having received it from an external client.

.. _qos:

qos (experimental)
------------------

MQTT Quality of service for the internal messaging between data node of the
server and internal MQTT broker.

- is optional
- type: ``integer``

  - The value of this property **must** be equal to one of the below:

    - ``0``
    - ``1``
    - ``2``

-  default: ``0``

.. _retain:

retain (experimental)
---------------------

Whether the last message should be retained (last-value-cached) on the internal
MQTT broker.

-  is optional
-  type: ``boolean``, must be one of ``true``, ``false1``
-  default: ``false``

targetState
-----------

The state this resource should be in, after start-up.

-  is optional
-  type: ``enum``, must be one of ``enabled``, ``disabled``
-  default: ``enabled``

.. _user/services/structure/resources/node/topic:

topic
-----

Explicit topic name to which this node's MQTT address should be mapped.

.. note:: The provided topic name is prefixed with the value of the
          :ref:`Cybus::MqttRoot
          <user/services/structure/parameters/global/mqtt-root>` global parameter.
          This global parameter by default has the value ``services/<serviceId>``
          where ``<serviceId>`` is replaced with the actual
          :ref:`user/services/service-id` of the current service. Hence, in the
          default case the full node topic will expand to:

            ``services/<serviceId>/<topic>``

          See the explanation at :ref:`Cybus::MqttRoot
          <user/services/structure/parameters/global/mqtt-root>` if alternative
          topic structures are needed.

Providing a custom topic and avoiding an additional mapping resource
improves overall performance as the message has to travel one hop less.
Nodes with custom topics can still be mapped using a regular mapping
(see :ref:`user/services/structure/resources/mapping`).

-  is optional
-  type: ``string``

.. _user/services/structure/resources/node/inputBuffering:

inputBuffering
---------------

Each node is internally subscribing to the MQTT broker in order to receive data
from the broker and present it as the server node. This MQTT subscription can
optionally be managed through an individual
input buffer (also called *input queue*) to establish fine-grained control for
high data rate behaviour. By default, this input buffering is disabled and
instead all input data is handled on the global event queue, which works fine as
long as there is no risk of out-of-memory exceptions due to unexpected slow data
processing or forwarding.

When enabling the individual input buffer, the buffer properties determine the
behaviour in situations when the input buffer is filling up. The buffer is
filling up when the message arrival rate is larger than the processing data rate
or the forwarding (publishing) data rate. Or, in other words, the input buffer
is filling up if the messages arrive faster than how they can be processed or be
forwarded (published). If this situation happens for longer time durations, the
input buffer will reach its configured capacity limits and arriving messages
will be dropped, so that the system will not run into an uncontrollable
out-of-memory exception. This is a fundamental and unavoidable property of
distributed systems due to its finite resources. But the actual behaviour of the
input buffer can be adapted to the actual application scenario by setting the
properties in the ``inputBuffering`` section (optional).

Supported properties are (all optional):

  - ``enabled`` (type: `boolean`, default: ``false``) Enable or disable input buffering.
  - ``maxInputBufferSize`` (type: `integer`, default: ``5000``) Maximum number of
    input messages that are queued in the input buffer. Exceeding messages will
    be discarded. Adjust this to a higher value if you are handling bursty
    traffic.
  - ``maxConcurrentMessages`` (type: `integer`, default: ``2``) Maximum number
    of concurrently processed messages as long as the input buffer queue is
    non-empty.
  - ``waitingTimeOnEmptyQueue`` (type: `integer`, default: ``10``) Waiting time
    in milliseconds after the input buffer queue ran empty and before checking
    again for newly queued input messages. Regardless of this value, on
    non-empty input buffer queue all messages will be processed without waiting
    time in between until the queue is empty again.


Custom Properties
=================

Depending on the protocol type of the node, additional custom properties
are available:

- :ref:`Cybus::Node::Opcua <OpcuaNode>`