BACnet

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.

BACnet glossary (advanced reading)

Device
The device represents a server that is managing one or more BACnet Objects. A device has a unique device instance (which is sufficient for addressing if using the same network interface) and a unique (UDP-)<ip>:<port> address which can be used for addressing throughout the entire LAN. Technically, the device is an object with the name device. The device instance in fact is its object instance the with the additional requirement to be unique.
Object
An object reflects a physical hardware actor or sensor (i.e. an I/O device). BACnet defines a list of standardized object types (such as analog-input, analog-output, binary-input, binary-output, etc.). object types are identified by a fixed number or by a fixed ASCII string identifier (s.a.). Depending on the installation, a device may serve an arbitrary number of object instances of arbitrary type. A device may for example run 3 analog-inputs, 1 analog-value and two binary-outputs. An object is addressed by its type and a numeric instance ID which must only be unique within the device.
Property
Every object contains a type-dependent set of properties. The most important property every object possesses is the present-value property (this is conceptually very similar to other system’s process-variable (PV)). Like object types, the properties are identified by a fixed number or by a fixed ASCII string (like present-value). Examples of other properties are version, object-name. The property is the final data-endpoint that whose value can be read or written. The value type can be any scalar value, arrays of scalars or specific complex types (this depends on the object type).

Important

For unambiguously addressing any property the following information must be provided:
  1. deviceAddress (e.g. 192.168.2.160:43712)
  2. objectType (e.g. analog-input)
  3. objectInstance (e.g. 0)
  4. property (e.g. present-value)

Note

If only one device is running on a given host (with fixed IP) the port can be omitted from in the deviceAddress field.

Commissioning file specifics

A typical commissioning file for the BACnet protocol looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
# ----------------------------------------------------------------------------#
# Commissioning File
# ----------------------------------------------------------------------------#
# Copyright: Cybus GmbH (2017)
# Contact: support@cybus.io
# ----------------------------------------------------------------------------#
# Source Interface Definition - BACnet
# ----------------------------------------------------------------------------#
source:
  driver: bacnet
  connection:
    protocol: bacnet-ip
    deviceInstance: 1234
    deviceAddress: 192.168.241.233 # No port -> only one device can run here
  defaults:
    operation: subscribe
    interval: 1000
    property: present-value
    priority: 8 # Only evaluated for writing (highest: 1, lowest 16 = default)
# ----------------------------------------------------------------------------#
# Target Interface Definition - MQTT (Cybus Connectware Broker)
# ----------------------------------------------------------------------------#
target:
  driver: mqtt
  defaults:
    operation: write
    topicPrefix: io/cybus/bacnet
# ----------------------------------------------------------------------------#
# Mappings: For further addressing the objectType and objectInstance
# must be configured. The property name defaults to present-value (s.a.)
# ----------------------------------------------------------------------------#
mappings:
- source:
    description: Temperature Outside (north) [°C]
    objectType: analog-input
    objectInstance: 2796204
  target:
    topic: sensorOutside/north/temperature
- source:
    operation: write
    description: Target value during operation [%]
    objectType: analog-output
    objectInstance: 2796280
  target:
    operation: subscribe
    topic: target/operation/set

Available connection parameters

protocol
Required, must be bacnet-ip
deviceInstance
Required, integer number describing the device instance
deviceAddress
Required, <ip>:<port> of the device. Port can be skipped if only one device is available under the given IP address.

Available mappings parameters

interval
Optional, the poll interval in milliseconds
description
Optional, a textual description of the property
objectType

Required, standard BACnet object types are

analog-input
e.g. sensor input
analog-output
e.g. control output
analog-value
e.g. setpoint or other analog control system parameter
binary-input
e.g. switch input
binary-output
e.g. relay output
binary-value
e.g. binary (digital) control system parameter
calendar
e.g. defines a list of dates, such as holidays or special events, for scheduling
command
writes multiple values to multiple objects in multiple devices to accomplish a specific purpose, such as day-mode to night-mode, or emergency mode
device
properties tell what objects and services the device supports, and other device-specific information such as vendor, firmware revision
event-enrollment
describes an event that might be an error condition (e.g., “Input out of range”) or an alarm that other devices to know about. It can directly tell one device or use a Notification Class object to tell multiple devices
file
allows read and write access to data files supported by the device
group
provides access to multiple properties of multiple objects in a read single operation
loop
provides standardized access to a “control loop.”
multi-state-input
represents the status of a multiple-state process, such as a refrigerator’s On, Off, and Defrost cycles.
multi-state-output
represents the desired state of a multiple-state process (such as It’s Time to Cool, It’s Cold Enough and it’s Time to Defrost)
notification-class
contains a list of devices to be informed if an Event Enrollment object determines that a warning or alarm message needs to be sent
program
allows a program running in the device to be started, stopped, loaded and unloaded, and reports the present status of the program
schedule
defines a weekly schedule of operations (performed by writing to specified list of objects with exceptions such as holidays. Can use a Calendar object for the exceptions.
objectInstance
Required, integer number describing the object instance
property
Required, name of the property. Most important is present-value. Other typically available properties are: object-name, description, status-flags, units. On the device object the properties location, object-list and system_status are typically available.
priority
Optional, only effects during writing to BACnet and defines the priority (highest: 1, lowest 16 = default)
propertyTag

Optional, only effective during writing to BACnet and forces the data type of the provided value into the provided BACnet type (called propertyTag). The propertyTag is an integer value (enumeration) with the following choices:

  • NULL = 0
  • BOOLEAN = 1
  • UNSIGNED_INT = 2
  • SIGNED_INT = 3
  • REAL = 4
  • DOUBLE = 5
  • OCTET_STRING = 6
  • CHARACTER_STRING = 7
  • BIT_STRING = 8
  • ENUMERATED = 9
  • DATE = 10
  • TIME = 11
  • OBJECT_ID = 12

Output Format

If data is read from BACnet the output will be provided as JSON object

{
  "value": <value>,
  "timestamp": <msSinceEpoch>
}

Input Format

If data is written to BACnet is must be provided as JSON object

{ "value": <value> }