> 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/connectors/shop-floor-connectors/bacnet.md). # BACnet BACnet is a data communication protocol for **B**uilding **A**utomation and **C**ontrol **net**works. A data communication protocol is a set of rules governing the exchange of data over a computer network. The rules take the form of a written specification that spells out what is required to conform to the protocol. For more information, see [BACnet.org](https://www.bacnet.org/). ## Concepts BACnet organizes data into a three-level hierarchy: a device hosts objects, and each object exposes properties that you read from or write to. ### Device The device represents a server that manages one or more BACnet objects. A device has a unique device instance number, which is sufficient for addressing when using the same network interface, and a unique UDP port as its device address in the format `${IP_ADDRESS}:${PORT}`, which can be used for addressing throughout the entire LAN. Technically, the device is itself an object with the name `device`, and the device instance is its object instance with the additional requirement to be unique. ### Object An object reflects a physical hardware actor or sensor, such as an I/O device. BACnet defines a list of standardized object types, such as `analog-input`, `analog-output`, `binary-input`, and `binary-output`. Object types are identified by a fixed number or by a fixed ASCII string identifier. Depending on the installation, a device may serve an arbitrary number of object instances of arbitrary type. For example, a device may host three `analog-input` objects, one `analog-value`, and two `binary-output` objects. An object is addressed using its type and numeric instance ID, which must be unique within the device. ### Property Every object contains a type-dependent set of properties. The most important `property` has the name `present-value`, which every object exposes. Other typical properties are `object-name`, `description`, and `status-flags`. Like object types, properties are identified by a fixed number or by a fixed ASCII string, for example `present-value`. A property is the addressable data point at which values are read or written. Depending on the object type, a property value can be a scalar, an array of scalars, or a more complex structure. ## Minimum Configuration Two resources are required to read from or write to a BACnet device: a connection to the device, and one or more endpoints for its data points. Create a [Cybus::Connection](/data-flows/service-commissioning-files/resources/cybus-connection.md) resource for the target BACnet device. In its `connection` property, set: * `deviceAddress` — the device's IP address and UDP port, for example `192.168.1.100:47808` * `deviceInstance` — the device's unique BACnet instance number, for example `27335` {% hint style="warning" %} ## When you can skip the port If only one BACnet device is running on the host and its IP is fixed, you can omit the port and provide just the IP address: * With port: `192.168.1.100:47808` * Without port: `192.168.1.100` {% endhint %} For each BACnet data point you want to access, create a [Cybus::Endpoint](/data-flows/service-commissioning-files/resources/cybus-endpoint.md) resource that references the connection. In its `read`, `write`, or `subscribe` properties, set: * `objectType` — the BACnet object type, for example `analog-input` * `objectInstance` — the numeric instance of the object on the device, for example `2` * `property` — the property to read or write, for example `present-value` For all parameters, see [Connection Properties](/connectors/shop-floor-connectors/bacnet/bacnetconnection.md) and [Endpoint Properties](/connectors/shop-floor-connectors/bacnet/bacnetendpoint.md). ## Service Commissioning File Example The following example demonstrates how to configure a BACnet connection with endpoints for read, write, and subscribe operations on BACnet objects. {% file src="/files/VJqz8DOhj1mv6IqnQ8ol" %} {% code title="bacnet-example.yml" lineNumbers="true" expandable="true" %} ```yaml # ----------------------------------------------------------------------------# # BACnet Service Commissioning File Example # ----------------------------------------------------------------------------# # Copyright: Cybus GmbH # Contact: support@cybus.io # ----------------------------------------------------------------------------# # Source Interface Definition - BACnet # ----------------------------------------------------------------------------# description: | Sample commissioning file for BACnet protocol connectivity and data mapping metadata: name: BACnet Protocol Connectivity icon: https://www.cybus.io/wp-content/uploads/2019/03/Cybus-logo-Claim-lang.svg provider: cybus homepage: https://www.cybus.io version: 0.0.1 parameters: IP_Address: type: string default: 192.168.1.100 Port_Number: type: number default: 47808 Device_Instance: type: number default: 2000 initialReconnectDelay: type: integer default: 1000 maxReconnectDelay: type: integer default: 30000 factorReconnectDelay: type: integer default: 2 resources: # Define the connection to the device. bacnetConnection: type: Cybus::Connection properties: protocol: Bacnet targetState: connected connection: deviceInstance: !ref Device_Instance deviceAddress: !sub '${IP_Address}:${Port_Number}' connectionStrategy: initialDelay: !ref initialReconnectDelay maxDelay: !ref maxReconnectDelay incrementFactor: !ref factorReconnectDelay # The BACnet protocol supports endpoints of type read, write, and subscribe. # Below are examples of how to configure such operations. # Read endpoint bacnetReadBinaryOutput: type: Cybus::Endpoint properties: protocol: Bacnet connection: !ref bacnetConnection read: objectType: binary-output objectInstance: 303 property: present-value # Write endpoint bacnetWriteBinaryOutput: type: Cybus::Endpoint properties: protocol: Bacnet connection: !ref bacnetConnection write: objectType: binary-output objectInstance: 303 property: present-value priority: 8 propertyTag: 7 # Subscription endpoint bacnetSubscribeBinaryOutput: type: Cybus::Endpoint properties: protocol: Bacnet connection: !ref bacnetConnection subscribe: objectType: binary-output objectInstance: 303 property: present-value interval: 1000 ``` {% endcode %} ## Handling Slow or Unreliable Devices You can adapt BACnet timing behavior to slow, unreliable, or congested networks in two ways: request-level tuning via APDU properties, and connection-level tuning via `connectionStrategy`. ### APDU Timing and Retries Three properties on the connection control per-request timing: * `apduTimeoutMs` — how long to wait for a device reply before timing out and retrying. * `apduRetries` — how many times a request is resent before giving up. * `sweepIntervalSeconds` — how often stuck transaction slots are reclaimed. For defaults and permitted ranges, see [Connection Properties](/connectors/shop-floor-connectors/bacnet/bacnetconnection.md). Common adjustments: * For slow or legacy controllers such as Trend IQ4, Andover, or Desigo PXC100, and for congested or remote networks, raise `apduTimeoutMs` to `8000`–`10000`. Values that are too low cause premature retries and unnecessary traffic. * For fast, reliable devices where you want to fail fast, lower `apduRetries` to `1`–`2`. For flaky or wireless links, raise it to `5` or higher. * `sweepIntervalSeconds` is an advanced safety valve. Keep the default unless you observe transaction slot exhaustion when many devices become unresponsive at once. {% hint style="warning" %} ## These settings are shared across all connections These tuning properties are applied per protocol-mapper instance, not per connection. The first BACnet connection that starts within an instance sets the values; conflicting values on later connections are ignored and logged as a warning. Set these properties consistently across all BACnet connections in the same protocol-mapper instance, or split device classes into separate instances (for example, one instance for fast devices and another for slow legacy controllers) so that each instance can carry its own timing profile. {% endhint %} ### Reconnect Backoff If a connection to a BACnet device drops, Connectware retries with an exponential backoff. Tune the backoff via the `connectionStrategy` property on the connection: `initialDelay`, `maxDelay`, and `incrementFactor`. Defaults suit most deployments. Increase `maxDelay` on unreliable WAN links to avoid tight retry loops when a device is offline for extended periods. For defaults and permitted values, see [connectionStrategy](/connectors/shop-floor-connectors/bacnet/bacnetconnection.md#connectionstrategy-object). ## Reaching Devices on Remote Subnets To reach BACnet/IP devices on a remote subnet, set the `bbmd` property on the connection to register Connectware as a foreign device with a BACnet Broadcast Management Device (BBMD). See [bbmd](/connectors/shop-floor-connectors/bacnet/bacnetconnection.md#bbmd-object). {% hint style="warning" %} BBMD support is experimental. Full support is planned for a future release. {% endhint %} ## Input and Output Formats ### Input Format on Write To write data to BACnet, publish a JSON message to the endpoint's `/set` topic with the following structure: {% code lineNumbers="true" %} ```json { "value": "${VALUE}" } ``` {% endcode %} ### Output Format on Write No response message is written to the `/res` topic of the endpoint for write operations. ### Output Format on Read For a read endpoint, you can include a correlation `id` in the request payload to match responses to specific requests. Results are published to the endpoint's `/res` topic in the following format: {% code lineNumbers="true" %} ```json { "value": "${VALUE}", "timestamp": "${MS_SINCE_EPOCH}", "id": "${CORRELATION_ID}" } ``` {% 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/connectors/shop-floor-connectors/bacnet.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.