> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-node.md).

# Cybus::Node

Give OPC UA and HTTP clients access to one data point, and connect the data point to the MQTT topics of your service.

A **Cybus::Node** resource provides one data point on a [Cybus::Server](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-server.md). External clients read the value of the node or write values to it. A [Cybus::Mapping](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-mapping.md) usually connects the node to the MQTT topics of your application. These topics carry the data that the server provides to clients, or the data that it receives from them.

## Node Types

The resource type selects the server protocol and the kind of node. Each type adds its own properties to the properties on this page.

| Resource Type                 | Server | Protocol-Specific Properties                                                                                                |
| ----------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- |
| `Cybus::Node::Opcua`          | OPC UA | [OPC UA Node Properties](https://docs.cybus.io/connectors/servers/opc-ua-server/opcuanode.md)                               |
| `Cybus::Node::OpcuaObject`    | OPC UA | [OPC UA Object Node Properties](https://docs.cybus.io/connectors/servers/opc-ua-server-references/opcuaobjectnode.md)       |
| `Cybus::Node::OpcuaReference` | OPC UA | [OPC UA Reference Node Properties](https://docs.cybus.io/connectors/servers/opc-ua-server-references/opcuareferencenode.md) |
| `Cybus::Node::Http`           | HTTP   | [HTTP Node Properties](https://docs.cybus.io/connectors/servers/http-server/httpnode.md)                                    |

For complete examples, see [OPC UA Server](https://docs.cybus.io/connectors/servers/opc-ua-server.md), [OPC UA Server References](https://docs.cybus.io/connectors/servers/opc-ua-server-references.md), and [HTTP Server](https://docs.cybus.io/connectors/servers/http-server.md).

## Node Properties

| Property                          | Type       | Required     | Default         |
| --------------------------------- | ---------- | ------------ | --------------- |
| [parent](#parent)                 | `string`   | **Required** |                 |
| [operation](#operation)           | `enum`     | Optional     |                 |
| [transaction](#transaction)       | `object`   | Optional     |                 |
| [rules](#rules-experimental)      | `object[]` | Optional     |                 |
| [qos](#qos-experimental)          | `integer`  | Optional     | `0`             |
| [retain](#retain-experimental)    | `boolean`  | Optional     | `false`         |
| [targetState](#targetstate)       | `enum`     | Optional     | `enabled`       |
| [topic](#topic)                   | `string`   | Optional     | The resource ID |
| [inputBuffering](#inputbuffering) | `object`   | Optional     |                 |

### parent

The parent of the node. The parent relations of all nodes form the hierarchical tree of data points on the server. For a node at the top of the tree, reference the [Cybus::Server](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-server.md). For any other node, reference its parent node, for example `!ref machineFolder`.

* **Required**
* Type: `string`

### operation

The direction of the data flow between the node and the clients of the server. This property applies to nodes that provide data to or receive data from an external client. Each operation uses MQTT topics below the [topic](#topic) of the node.

* **Optional**
* Type: `enum`

The following values are available:

* `serverProvides`: Clients read the value. The node takes its value from the messages on `<topic>/write`.
* `serverReceives`: Clients write the value. The node publishes each value on `<topic>/read`.
* `serverProvidesAndReceives`: Clients read and write the value, with the topics of both operations.
* `transaction`: Clients send a request and wait for the response. The node publishes the request on `<topic>/treq` and waits for the response on `<topic>/tres`. Only HTTP and OPC UA nodes support this operation. See [FlowSync](https://docs.cybus.io/data-flows/flowsync.md).

For an HTTP node without `operation`, the `method` decides the operation. `GET` sets `serverProvides`, and every other method sets `serverReceives`.

### transaction

The settings of a transaction. They apply only when [operation](#operation) is `transaction`. Only HTTP and OPC UA nodes support transactions. See [FlowSync](https://docs.cybus.io/data-flows/flowsync.md).

* **Optional**
* Type: `object`

| Property              | Type      | Default                                                                                                | Description                                                                                                                     |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `timeout`             | `integer` | `10000` (10 seconds)                                                                                   | The maximum time in milliseconds that the node waits for the response. The minimum is `1000`.                                   |
| `timeoutErrorCode`    | `integer` | <p>HTTP: <code>504</code> (Gateway Timeout)<br>OPC UA: <code>2156199936</code> (BadRequestTimeout)</p> | The error or status code that the client receives when the transaction times out. Its value and meaning depend on the protocol. |
| `timeoutErrorMessage` | `string`  | `Flow did not finish in time`                                                                          | The message that the client receives when the transaction times out.                                                            |

For an example, see [Example 4 - Node with Timeout Error Code and Error Message (HTTP)](https://docs.cybus.io/data-flows/flowsync/flowsync-example-4.md).

### rules (experimental)

[Rule Engine](https://docs.cybus.io/data-flows/rule-engine/data-processing-rules.md) rules that transform a value that a client writes to the node, before the node publishes it. Rules do not apply to the values that the node provides to clients, or to transactions. You cannot use the `split` rule here, because it works only in a [Cybus::Mapping](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-mapping.md).

* **Optional**
* Type: `array` of rules

### qos (experimental)

The MQTT quality of service (QoS) between the node and the internal MQTT broker.

* **Optional**
* Type: `integer`
  * Allowed values: `0`, `1`, `2`
* Default: `0`

### retain (experimental)

Whether the internal MQTT broker retains the last message of the node, as a last-value cache.

* **Optional**
* Type: `boolean`
* Default: `false`

### targetState

The desired state of the node after startup.

* **Optional**
* Type: `enum`
  * Allowed values: `enabled`, `disabled`
* Default: `enabled`

### topic

A custom MQTT topic for the node. Connectware puts the value of the global parameter [Cybus::MqttRoot](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#cybus-mqttroot) in front of it, so the full topic is `services/<serviceId>/<topic>` by default. Here, `<serviceId>` is the [service ID](https://docs.cybus.io/data-flows/services/serviceid.md) of the service.

Without `topic`, Connectware uses the resource ID of the node in its place. To change the prefix, see [Custom Topic Prefix](https://docs.cybus.io/data-flows/service-commissioning-files/parameters.md#custom-topic-prefix).

If you set `topic` to the topic of your application, you need no [Cybus::Mapping](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-mapping.md) in between, and each message takes one hop less, which improves overall performance. You can still map a node that has a custom topic.

Nodes do not support the `asset` property of a [Unified Namespace](https://docs.cybus.io/unified-namespace/unified-namespace.md). To connect a node to the data of an asset, use a [Cybus::Mapping](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-mapping.md) with `asset` in place of `topic`. See [Topics of an Asset](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-asset.md#topics-of-an-asset).

* **Optional**
* Type: `string`
* Default: the resource ID

### inputBuffering

An input buffer of the node, also called input queue, for the messages that the node passes between the internal MQTT broker and its clients. Each node subscribes to the internal MQTT broker, so that it can present the data as a server node.

Input buffering is off by default. Without it, slow processing or forwarding can lead to an out-of-memory error. Turn it on when messages can arrive faster than the node processes or forwards them.

With input buffering on, the node processes 2 messages at a time and buffers up to 5000 messages. If messages arrive too fast for a longer time, the buffer fills up. The node then discards arriving messages instead of running out of memory. Resources are finite, so this cannot be avoided entirely.

* **Optional**
* Type: `object`

The `inputBuffering` object takes the following properties. Only `enabled` takes effect:

| Property                  | Type      | Default | Description                                                    |
| ------------------------- | --------- | ------- | -------------------------------------------------------------- |
| `enabled`                 | `boolean` | `false` | Turns input buffering on.                                      |
| `maxInputBufferSize`      | `integer` | `5000`  | Has no effect. The node always buffers up to 5000 messages.    |
| `maxConcurrentMessages`   | `integer` | `2`     | Has no effect. The node always processes 2 messages at a time. |
| `waitingTimeOnEmptyQueue` | `integer` | `10`    | Has no effect.                                                 |

## Example

The following OPC UA server has a `Machine` folder with two variables. Clients read `Temperature` and write `Setpoint`. The mapping connects both nodes to MQTT topics.

{% code lineNumbers="true" %}

```yaml
opcuaServer:
  type: Cybus::Server::Opcua

machineFolder:
  type: Cybus::Node::Opcua
  properties:
    parent: !ref opcuaServer
    browseName: Machine
    nodeId: ns=1;s=Machine
    nodeType: Object

temperature:
  type: Cybus::Node::Opcua
  properties:
    parent: !ref machineFolder
    browseName: Temperature
    nodeId: ns=1;s=Temperature
    nodeType: Variable
    dataType: Double
    operation: serverProvides

setpoint:
  type: Cybus::Node::Opcua
  properties:
    parent: !ref machineFolder
    browseName: Setpoint
    nodeId: ns=1;s=Setpoint
    nodeType: Variable
    dataType: Double
    operation: serverReceives

machineMapping:
  type: Cybus::Mapping
  properties:
    mappings:
      - subscribe:
          topic: machine/temperature
        publish:
          endpoint: !ref temperature
      - subscribe:
          endpoint: !ref setpoint
        publish:
          topic: machine/setpoint
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-node.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
