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 Cybus::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
transaction	object	Optional
rules	object[]	Optional
qos	integer	Optional
retain	boolean	Optional
targetState	enum	Optional
topic	string	Optional
inputBuffering	object	Optional

parent

Reference to another Cybus::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 Cybus::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

    • transaction

The transaction value of the operation property only supports HTTP and OPC UA. For more information, see FlowSync.

transaction

This property is only available if operation is set to transaction. For more information on the operation property, see operation.

• is optional

• type: object

  • Property values:

    • timeout (optional)

      • Specifies the maximum duration to wait for a response in milliseconds.

      • Default: 2000

      • Type: Integer

    • timeoutErrorCode (optional)

      • The protocol-specific error code to return when a timeout occurs. Make sure to use valid error codes for the used protocol.

      • Default: 500

      • Type: Integer

    • timeoutErrorMessage (optional)

      • A custom message to return when the timeout occurs.

      • Type: String

      • Example: "Request timed out while waiting for response"

The transaction property only supports HTTP and OPC UA. For more information see FlowSync.

rules (experimental)

• is optional

• type: array of Rule Engine

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

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 (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

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 Cybus::MqttRoot global parameter. This global parameter by default has the value services/<serviceId> where <serviceId> is replaced with the actual ServiceID of the current service. Hence, in the default case the full node topic will expand to:

services/<serviceId>/<topic>

See the explanation at 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 Cybus::Mapping).

• is optional

• type: string

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:

• Cybus::Node::Opcua