BACnet

Configure Connectware to read from and write to BACnet devices.

BACnet is a data communication protocol for Building Automation and Control networks. 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.

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

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

For each BACnet data point you want to access, create a Cybus::Endpoint 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 and Endpoint Properties.

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.

3KB

bacnet-example.yml

Open

bacnet-example.yml

# ----------------------------------------------------------------------------#
# BACnet Service Commissioning File Example
# ----------------------------------------------------------------------------#
# Copyright: Cybus GmbH
# Contact: [e-mail]
# ----------------------------------------------------------------------------#
# 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

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.

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.

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.

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.

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.

BBMD support is experimental. Full support is planned for a future release.

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:

{ "value": "${VALUE}" }

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:

{
  "value": "${VALUE}",
  "timestamp": "${MS_SINCE_EPOCH}",
  "id": "${CORRELATION_ID}"
}