Cybus::Node
Last updated
Last updated
© Copyright 2024, Cybus GmbH
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.
Property | Type | Required |
---|---|---|
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
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.
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.
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.
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
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
The state this resource should be in, after start-up.
is optional
type: enum
, must be one of enabled
, disabled
default: enabled
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
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.
Depending on the protocol type of the node, additional custom properties are available:
string
Required
string
Optional
object
Optional
object[]
Optional
integer
Optional
boolean
Optional
enum
Optional
string
Optional
object
Optional