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 number (which is sufficient for addressing if using the same network interface) and a unique UDP port as device address (in the format <ip-address>:<port-number>) 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 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 using its type and 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 that exists in every object is the present-value property. This is conceptually very similar to the process-variable (PV) of other industry protocols. Like object types, the properties are identified by a fixed number or by a fixed ASCII string (e.g. present-value). Examples of other properties are version or object-name. The property is the final data-endpoint where values can be read from or written to. The value type can be any scalar value, arrays of scalars or specific complex types (this depends on the object type).
For unambiguously addressing any data endpoint (in BACnet: property) the following information must be provided:
At the Cybus::Connection:
deviceAddress
(e.g. 192.168.2.160:43712)deviceInstance
(e.g. 27335)
At the Cybus::Endpoint:
objectType
(e.g. analog-input)objectInstance
(e.g. 2)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 the deviceAddress field.
Connection Properties¶
localInterface
(string)¶
Local interface used to receive data
Default: "eth0"
Examples: "lo"
, "eth0"
deviceAddress
(string, required)¶
Device address as UDP network address in the form ip-address:port-number. The port can be skipped if only one device is available under the given IP address
Example: "192.168.2.114:40426"
connectionStrategy
(object)¶
If a connection attempt fails, retries will be performed with increasing delay (waiting time) in between. The following parameters control how these delays behave.
Properties of the connectionStrategy
object:
initialDelay
(integer)¶
Delay (waiting time) of the first connection retry (in milliseconds). For subsequent retries, the delay will be increased according to the parameter incrementFactor which has a default value of 2.
Default: 1000
Additional restrictions:
Minimum:
1000
maxDelay
(integer)¶
Maximum delay (waiting time) to wait until the next retry (in milliseconds). The delay (waiting time) for any subsequent connection retry will not be larger than this value. Must be strictly greater than initialDelay.
Default: 30000
incrementFactor
(integer)¶
The factor used to increment initialDelay up to maxDelay. For example if initialDelay is set to 1000 and maxDelay to 5000 the values for the delay would be 1000, 2000, 4000, 5000.
Default: 2
Additional restrictions:
Minimum:
2
Endpoint Properties¶
objectType
(string, enum, required)¶
Identifier of the BACnet object type of this endpoint
This element must be one of the following enum values:
analog-input
analog-output
analog-value
binary-input
binary-output
binary-value
calendar
command
device
event-enrollment
file
group
loop
multi-state-input
multi-state-output
notification-class
program
schedule
Example: "analog-input"
objectInstance
(integer, required)¶
Integer number to describe the concrete object instance that should be accessed
Example: 1
property
(string, required)¶
The name of this property. The most common property has the name present-value. Other typically available property names are: object-name, description, status-flags, units. On the device object the properties location, object-list and system_status are typically available
Example: "present-value"
cronExpression
(string)¶
The Cron expression used to poll the endpoint. (For examples, see: https://github.com/node-cron/node-cron)
Examples: "1,2,4,5 * * * *"
, "1-5 * * * *"
, "*/2 * * * *"
,
"* * * January,September Sunday"
priority
(integer)¶
Only effective during writing to BACnet: Defines the priority (highest: 1, lowest 16 = default)
Example: 16
Additional restrictions:
Maximum:
16
propertyTag
(integer)¶
Only effective during writing to BACnet: Forces the data type of the provided value into the provided BACnet type (called propertyTag). The propertyTag is an integer value (enumeration), please see the documentation for the encoding
Example: 4
Example Configuration¶
The following example demonstrates how to configure a simple BACnet connection and endpoint that subscribes to an analog-input BACnet object.
Download: bacnet-example.yml
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 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 | # ----------------------------------------------------------------------------# # BACnet Commissioning File Example # ----------------------------------------------------------------------------# # Copyright: Cybus GmbH (2021) # 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.10.30 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: # Lets 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 example on how to configure such operations. # Read endpoint bacnetReadBinaryOutput: type: Cybus::Endpoint properties: protocol: Bacnet connection: !ref bacnetConnection # Specifying the topic here instead of using a Mapping block allow us to remove an extra hop. 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 |
Input Format¶
To write data to BACnet a request must be sent to the MQTT endpoint of the service
using a /set
suffix providing a JSON object with the following format:
{ "value": "<value>" }
No response message is written to the /res topic of the Endpoint for this protocol.
Output Format on Read¶
For a read endpoint, additionally a correlation id (id) can be set in the payload of the message request, to ensure the correct identification of responses to specific requests.
When data is read results are published to the /res topic of the Endpoint. The output message is an object with the following format:
{
"value": "<value>",
"timestamp": "<msSinceEpoch>"
"id": "<correlation id>"
}