.. _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 ` global parameter. This global parameter by default has the value ``services/`` where ```` 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//`` See the explanation at :ref:`Cybus::MqttRoot ` 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 `