# BACnet Stack

## An open source BACnet protocol stack for embedded systems

## About this Project

This BACnet protocol stack library provides a BACnet application layer, network layer and media access (MAC) layer communications services. It is an open source, royalty-free library for an embedded system, Windows, Linux, or other operating system. Example BACnet client and server applications are included.

BACnet - A Data Communication Protocol for Building Automation and Control Networks - see bacnet.org. BACnet is a standard data communication protocol for Building Automation and Control Networks. BACnet is an open protocol, which means anyone can contribute to the standard, and anyone may use it. The only caveat is that the BACnet standard document itself is copyrighted by ASHRAE, and they sell the document to help defray costs of developing and maintaining the standard (similar to IEEE or ANSI or ISO).

For software developers, the BACnet protocol is a standard way to send and receive messages on the wire containing data that is understood by other BACnet compliant devices. The BACnet standard defines a standard way to communicate over a number of wires, known as Data Link/Physical Layers: Ethernet, EIA-485, EIA-232, ARCNET, and LonTalk. The BACnet standard also defines a standard way to communicate using UDP (IPv4 and IPv6) and TCP (HTTP for RESTful Web Services and HTTPS for Secure Connect).

There are other open source projects for BACnet:

- Yabe - Graphical explorer program for BACnet devices. Small graphical explorer program written in C#, for browsing BACnet devices. Currently supports both BACnet/IP, BACnet MSTP, and BACnet PTP. Basic functions for ReadProperty, WriteProperty, ReadPropertyMultiple, WritePropertyMultiple, I-Am, Who-Is, SubscribeCOV, Notify, AtomicWriteFile, AtomicReadFile, and more.
- VTS - visual test shell for Win32, used for Visually testing a BACnet implementation. It also includes a detailed network sniffer for BACnet messages, and the ability to send any BACnet services. The source code is in the public domain.
- Wireshark - an open source, cross platform protocol analyzer with BACnet support. The detailed BACnet support began in version 0.10.11 released on May 4, 2005 when Wireshark was known as Ethereal.
- BACnet4Linux - an LGPL BACnet application that requires Linux as the OS.
- BACnet Firewall Router -an application that combines BACnet routing capability with traffic management functions to carefully control access to building automation and control networks.
- BACpypes - a BACnet stack written in Python.
- BACsharp - a BACnet/IP stack written in C#.
- BACnet4J - a BACnet/IP stack written in Java that serves as the BACnet layer for Mango. Mango is open source Machine-to-Machine software (aka Industrial Control, SCADA, HMI, or domotics).

There are also commercial BACnet protocol source code libraries for BACnet that are designed for embedded use:

- Cimetrics TM - has a source library called BACstac/32 as part of their BACnet Protocol Stack SDK.
- Polarsoft - has a protocol stack source library for embedded use called FreeRangeTM and PolarSoft® FreeRange VSB (Very Small BACnet stack).
- SCADA Engine - The BACnet Linux Server is a complete BACnet Device running on the linux platform. The entire source code is available for custom applications and has been written in ANSI C which has been succesfully ported to Unix, VxWorks etc.
- BACnet Stack - Chipkin automation systems BACnet stack is an application layer BACnet library for an embedded system and application development.

## Licensing

Our BACnet protocol stack implementation is specifically designed for the embedded BACnet appliance, using a GPL with exception license (like eCos), which means that any changes to the core code that are distributed are made available, but the BACnet library can be linked to proprietary code without it becoming licensed under the GPL. See the eCos license overview for easy to read details about this exception to the GPL. The license does not require users to release the source code of any applications that are developed with this BACnet stack - only portions of the BACnet stack that have been modified. Note that those files in this BACnet stack that are expected to be modified are licensed using the MIT License.

The text of the GPL exception included in each source file is as follows:

> "As a special exception, if other files instantiate templates or use macros or inline functions from this file, or you compile this file and link it with other works to produce a work based on this file, this file does not by itself cause the resulting work to be covered by the GNU General Public License. However the source code for this file must still be made available in accordance with section (3) of the GNU General Public License."

## The source code

The source code is written in C for portability, and includes unit tests (PC based unit tests) and example application code. Since the code is designed to be portable, it compiles with GCC as well as other compilers, such as Visual C++, MinGW, IAR, or MicroChip XC. The source code is also designed to be high quality, readable, understandable, and easy to use.

The BACnet protocol is an ASHRAE/ANSI/ISO standard, so this library adheres to that standard. BACnet has no royalties or licensing restrictions, and registration for a BACnet vendor ID is free.

## What the code does

The BACnet stack comes with example applications that can be run under Linux, Win32, MacOS, or BSD. There are also example projects for embedded systems and microcontrollers.

The unit tests use CMake and may be run with the command sequence:

`$ make test`

The unit test framework uses a slightly modified ztest, and the tests are located in the `test/` folder. The test coverage tool is LCOV. The HTML results of the unit testing coverage are available starting in the `test/build/lcoverage/index.html` file. The unit tests can be run on computer and run with every commit within the Continuous Integration environment.

The BACnet stack was functionally tested using a variety of tools as well as various controllers and workstations. It has been included in many products that successfully completed BTL testing.

## Demo BACnet Applications

Using the Makefile in the project root directory, a dozen sample applications are created that run under Windows or Linux. They use the BACnet/IPv4 datalink layer for communication by default, but could be compiled to use BACnet IPv6, Ethernet, ARCNET, or MS/TP.

To build all the demo applications under Linux/Unix/Cygwin using the BACnet/IP datalink layer, use the familiar make command:

`$ make clean all
`

You can also modify the Makefile variabiles from the command line to build with the BACnet MS/TP datalink layer, for example:

`$ make BACDL_DEFINE=-DBACDL_MSTP=1 clean all
`

To build all the demo applications under Windows with the BACnet/IP datalink layer and utilizing the MinGW tools from BASH:

`$ make win32
`

From Windows Command Line

`c:\> build.bat`

The library is also instrumented to use CMake which can generate a project or Makefiles for a variety of IDE or compiler. For example, to generate a Code::Blocks project:

`$ mkdir build $ cd build/ $ cmake .. -G"CodeBlocks - Unix Makefiles" c:\> mkdir build c:\> cd build/ c:\> cmake .. -G"CodeBlocks - MinGW Makefiles"`

The demo application accept command line arguments. To specify an array index of ALL, use "-1". To make a priority optional, use "0". The applications also use environment variables to set datalink layer preferences. Use `--help` on the command line to see more options.

`$ apps/server/bacsrv 123
BACnet Server Demo - Device #123
$ apps/readprop/bacrp
bacrp device-instance object-type object-instance property [index]
$ apps/writeprop/bacwp
bacwp device-instance object-type object-instance property priority index tag value [tag value...]
$ apps/readfile/bacarf
bacarf device-instance file-instance local-name
$ apps/writefile/bacawf
bacawf device-instance file-instance local-name
$ apps/reinit/bacrd
Usage: bacrd device-instance state [password]
Send BACnet ReinitializeDevice service to device.
$ apps/whohas/bacwh
Usage: bacwh object-type object-instance | object-name
Send BACnet WhoHas request to devices, and wait for responses.
$ apps/dcc/bacdcc
Usage: bacdcc device-instance state timeout [password]
Send BACnet DeviceCommunicationControl service to device.
$ apps/timesync/bacts
Received TimeSyncronization Request
2006/8/30 07:10:45.00
$ apps/ucov/bacucov
Usage: bacucov pid device-id object-type object-instance time property tag value [priority] [index]
$ apps/whois/bacwi
Usage: bacwi device-instance | device-instance-min device-instance-max
Send BACnet WhoIs request to devices, and wait for responses.
The device-instance can be 0 to 4194303, or -1 for ALL.
The device-instance can also be specified as a range.
`

The demos can be compiled for Win32 platform using MinGW - Minimalist GNU for Windows or any compiler build environment supported by CMake.

BACnet-Tools - the example applications are compiled for Windows and can be downloaded from SourceForge.

To build the demo applications under Linux, such as Ubuntu, you may need to install some build tools. There are two ways to install all the build tools needed to compile the BACnet stack and the demo applications using the APT package manager. The first way uses the configure script:

`$ sudo ./configure`

The second way to install the build tools is using bash-aptfile:

`$ sudo tools/bash-aptfile/bin/aptfile aptfile`

## BACnet services supported matrix

The BACnet stack currently implements the following services listed in the the table. Services are added as needed for a variety of implemetations. With the services that are implemented, you could build a BACnet device that meets the standardized profile for a BACnet Smart Sensor, BACnet Smart Actuator, or a BACnet Application Specific Controller.

BACnet Service | Initiate | Execute
Who Is | Yes | Yes
I Am | Yes | Yes
Who Has | Yes | Yes
I Have | Yes | Yes
Who Am I | - | -
You Are | - | -
Read Property | Yes | Yes
Read Property Multiple | Yes | Yes
Write Property | Yes | Yes
Write Property Multiple | Yes | Yes
Write Group | Yes | Yes
Device Communication Control | Yes | Yes
ReinitializeDevice | Yes | Yes
Atomic Read File | Yes | Yes
Atomic Write File | Yes | Yes
Time Synchronization | Yes | Yes
UTC Time Synchronization | Yes | Yes
Subscribe COV | Yes | Yes
Confirmed COV Notification | Yes | Yes
Unconfirmed COV Notification | Yes | Yes
Read Property Conditional | - | -
Read Range | Yes | Yes
Get Alarm Summary | - | Yes
Get Event Information | Yes | Yes
Get Enrollment Summary | - | -
Acknowledge Alarm | - | Yes
Confirmed Event Notification | - | Yes
Unconfirmed Event Notification | - | Yes
Unconfirmed Text Message | - | -
Confirmed Text Message | - | -
Add List Element | Yes | Yes
Remove List Element | Yes | Yes
Create Object | Yes | Yes
Delete Object | Yes | Yes
Unconfirmed Private Transfer | Yes | Yes
Confirmed Private Transfer | Yes | Yes
VT Open | - | -
VT Data | - | -
VT Close | - | -

## BACnet Objects

The BACnet stack currently implements an example Device Object, and handles all of the ReadProperty and ReadPropertyMultiple inquiries for the required Device Object properties. The stack handles Who-Is inquiries with an I-Am, WhoHas with I-Have, and handles reject messages for services not currently supported or implemented by your device. There is built-in handling for DeviceCommunicationControl.

The example handlers interact with example objects by way of the Device object. There are example objects for the developer to use as a template when customizing the objects for their device.

File Objects are conditionally included in the demonstation applications. The files can be accessed using WriteProperty, ReadProperty, Who-Has, AtomicWriteFile, or AtomicReadFile services.

BACnet Object | Code Example
Accumulator | Yes
Analog Input | Yes
Analog Output | Yes
Analog Value | Yes
Averaging | -
Binary Input | Yes
Binary Output | Yes
Binary Value | Yes
Calendar | Yes
Command | Yes
Device | Yes
Event Enrollment | -
File | Yes
Group | -
Life Safety Point | Yes
Life Safety Zone | Yes
Loop | Yes
Multi-state Input | Yes
Multi-state Output | Yes
Multi-state Value | Yes
Notification Class | Yes
Program | -
Pulse Converter | -
Schedule | Yes
Trend Log | Yes
Access Door | Yes
Event Log | -
Load Control | Yes
Structured View | Yes
Trend Log Multiple | -
Access Point | Yes
Access Zone | Yes
Access User | Yes
Access Rights | Yes
Access Credential | Yes
Credential Data Input | Yes
CharacterString Value | Yes
DateTime Value | -
Large Analog Value | -
BitString Value | -
OctetString Value | Yes
Time Value | Yes
Timer | Yes
Integer Value | Yes
Positive Integer Value | Yes
Date Value | -
DateTime Pattern Value | -
Time Pattern Value | -
Date Pattern Value | -
Network Security | -
Global Group | -
Notification Forwarder | -
Alert Enrollment | -
Channel | Yes
Lighting Output | Yes
Network Port | Yes
Binary Lighting Output | Yes
Elevator Group | -
Escalator | -
Lift | -
Staging | -
Audit Log | -
Audit Reporter | -
Color | Yes
Color Temperature | Yes

## Getting Involved

If you want to contribute to this project, join us via GitHub.com or via SourceForge.net and create a fork or branch, and eventually a pull request to have your code or document considered for inclusion.

If you find a bug in this project, please tell us about it at SourceForge.net Bugs or Github.com Issue

If you have a support request, you can post it at SourceForge.net Support

If you have a feature request, you can post it at SourceForge.net Feature Request

If you have a problem getting this library to work for your device, or have a BACnet question, post the question to the Open Discussion, Developers, or Help forums at SourceForge.net Forums

More details about the project can be found on the BACnet Source Forge Project Page

There is documentation that describes the mechanisms in the BACnet Stack. I wrote up some answers to some frequently asked questions. Of course, there are a handful of text files in the doc directory of the project with more useful information.

BACnet Stack released files download

You can get the latest BACnet protocol stack source code using the Git version control system. The main development branch is at: https://sourceforge.net/p/bacnet/src/ci/master/tree/. This has the absolute latest code and features. Anyone doing development on the BACnet protocol stack should be using this branch. The stable release tags are at: https://sourceforge.net/p/bacnet/src/ref/master/tags/. This matches the released version downloadable through SourceForge. Anyone doing project development using the BACnet protocol stack should be using the tags branch and an appropriate version tag. The custom and vendor branches are at: https://sourceforge.net/p/bacnet/src/ref/master/branches/.

## BACnet Developer Resources

There are a number of resources that can help you develop a BACnet product or project.

- VTS - visual test shell for Win32, used for Visually testing a BACnet implementation. It also includes a detailed network sniffer for BACnet messages, and the ability to send any BACnet services. The source code is in the public domain.
- Wireshark - an open source, cross platform protocol analyzer with BACnet support. The detailed BACnet support in began in version 0.10.11 released on May 4, 2005 when Wireshark was known as Ethereal. Also, BACnet MS/TP capture support was added in Wireshark version 1.1.0. The demo application mstpcap can be used to capture BACnet MS/TP using an RS-485 converter, and save the data to a capture file that can be viewed with Wireshark or live capture with Wireshark.
- Ubuntu Linux or Debian Linux - my development platforms of choice. Linux makes a great development platform because all the necessary development tools are included.

BACnet Developer Help

## Products and Projects that use this BACnet Stack

Did you develop a product using this BACnet stack?

Beremiz - an integrated development environment for machine automation. It is Free Software, conforming to IEC-61131 among other standards.

BACnet Development Kit - An Atmel ATmega644 based development kit designed to kickstart BACnet MS/TP development.

Digital Lighting Management - offers connectivity without complexity for remote system management and control of lights and plug loads. Just one device in each room network has to be connected to a BACnet MS/TP segment for centralized control.

CSWorks - a development framework for building web-based HMI (Human Machine Interface), SCADA (Supervisory Control And Data Acquisition), EMI (Enterprise Manufacturing Intelligence) and M2M (Machine to Machine) software applications.

SCInterface™ = Sensor Control Interface - middleware platform for managing legacy and modern-day sensors through a centralized interface.

BACnetSim - a portable implementation of the BACnet data communication protocol. BACnetSim is meant for embedded devices and use MS/TP as the media access layer. BACnetSim is a fork of bacnet-stack-0.0.1

Building Controls Virtual Test Bed - a software environment that allows coupling different simulation programs including Dymola, EnergyPlus, MATLAB/Simulink and Radiance for co-simulation, and to couple these programs to control systems.

The coelostat in the Linde + Robinson Laboratory at Caltech.

ASHRAE® and BACnet® are registered trademarks of the American Society of Heating, Refrigerating and Air-Conditioning Engineers, Inc., 180 Technology Parkway NW, Peachtree Corners, Georgia 30092 US.

Website updated 04-November-2024 by Steve Karg.