A minimal, copy-paste-friendly example showing how to implement the BACnet B-SA (BACnet Smart Actuator) device profile in C++ using the CAS BACnet Stack. It listens on BACnet/IP (UDP 47808), answers ReadProperty requests, accepts WriteProperty to its commandable outputs, and is discoverable via Who-Is / I-Am. Each output does what the winning command says: a heating valve brings the temperature to the commanded setpoint, a relay follows its command, a drive runs at the commanded speed, and each reports back through an input. A disconnected valve shows up as a fault a client can read. The valve, relay and drive are a Simulation; everything BACnet does with them is real.
Download a prebuilt binary (Windows and Linux x64) - or build it yourself, see Build below.
- TUTORIAL.md - how to extend this example and how to review it for conformance. Read it when you start turning this into your own device.
- docs/PICS.md - the Protocol Implementation Conformance Statement: every object, every property, and who answers it.
Versions: this document describes example v1.3.0, built and verified against CAS BACnet Stack 6.0.23 (
6.x@64b2cfac5), at Protocol_Revision 30, with the vendoredcommon/helper at v3.4.0. Running the example prints all three - if what it prints disagrees with this line, trust the program and checkCHANGELOG.md.
B-SA (BACnet Smart Actuator), defined in Annex L.4.4 of ANSI/ASHRAE 135-2024, is the next step up from the Smart Sensor - the standard describes it as "a simple control device with limited resources; it is intended for specific applications." In practice that is an inexpensive, fixed-function actuator (a valve, a damper, a relay, a setpoint) that reports state and accepts commands from a controller.
A B-SA device answers ReadProperty and accepts WriteProperty to its commandable outputs - that is what distinguishes an actuator from a sensor. It does not have to support alarming / event reporting, scheduling, or trending, and this example implements none of them on purpose.
What this example does with a command: it stores the write in the
output's Priority_Array, the stack resolves Present_Value from it, and the
actuator Simulation drives its (simulated) equipment from that same resolved
value - so a client sees the command take effect on the matching input, not
just read back.
But it is still a full BACnet device. Even the simplest profile must present the standard object model - a Device object, a Network Port object (every device needs one), and its objects - and each object must expose all of its required properties. The CAS BACnet Stack generates most of those automatically (Object_Identifier, Object_Type, Status_Flags, Object_List, Protocol_*, ...); this example supplies the handful that are application-specific. The result is conformant for Protocol_Revision 30. docs/PICS.md lists every property and who answers it.
A BACnet output object's Present_Value is not written directly. Instead it is
commandable: it is resolved from a 16-slot Priority_Array plus a
Relinquish_Default.
- A
WriteProperty(Present_Value, value, priority)storesvaluein slotpriority(1 = highest .. 16 = lowest). If the client omits the priority, BACnet uses 16. - A
WriteProperty(Present_Value, NULL, priority)relinquishes that slot. - The stack reports the value in the highest-priority non-null slot as the
effective
Present_Value; if every slot is null, it reportsRelinquish_Default.
This lets several controllers command the same output at different priorities
(e.g. a manual override at priority 8 beats a normal command at 16) and cleanly
hand control back by writing NULL. The application just stores the array (see the
Commandable struct in main.cpp); the stack does the priority resolution.
Device 389002 "Chipkin Example B-SA" (Vendor 389 - Chipkin Automation Systems)
β
βββ Analog Input 1 "Bronze" Present_Value 21.5 -> follows the setpoint (REAL, degrees Celsius; read-only)
βββ Binary Input 1 "Emerald" Present_Value follows Binary Output 1 (0 = inactive / 1 = active; read-only)
βββ Multi-State Input 1 "Hot Pink" Present_Value follows Multi-State Output 1 (state, 1..3; read-only)
βββ Analog Output 1 "Chartreuse" Present_Value 20.0 (REAL setpoint, 10.0 .. 30.0 C; WRITABLE, commandable)
βββ Binary Output 1 "Fuchsia" Present_Value inactive (0/1 relay; WRITABLE, commandable)
βββ Multi-State Output 1 "Indigo" Present_Value 1 (speed, 1..3; WRITABLE, commandable)
βββ Network Port 1 "Vermilion" the BACnet/IP port (required on every device)
The three input objects (Bronze, Emerald, Hot Pink) are the shared minimum
every example in this series carries; here each is the feedback of one
output. The three output objects (Chartreuse, Fuchsia, Indigo) are the B-SA
additions; their Present_Value starts at the Relinquish_Default (no slots
commanded yet). Object names follow this series' colour-naming convention
(Device is always "Chipkin Example B-SA").
What a B-SA is for, in one sentence, from Annex L.4.4 of ANSI/ASHRAE 135-2024:
"Ability to allow modification of some or all of its BACnet objects by another
device" - a controller (the Peer - any BACnet client, or the Python client
in tests/) commands an output, and the actuator does what
the winning command says:
- The Peer writes Analog Output 1
Present_Value=24.0at priority 8. The valve opens and the temperature (Analog Input 1) climbs 1.0 C a second until it reads24.0. - A second Peer writes
19.0at priority 12. Priority 8 still wins:Present_Valuestays24.0,Priority_Array[12]holds19.0, and the temperature does not move. - The first Peer relinquishes priority 8 (writes NULL). Priority 12 wins now:
the temperature falls to
19.0. Relinquish priority 12 and the output returns to itsRelinquish_Default,20.0- and so does the temperature. - Binary Output 1 and Multi-State Output 1 work the same way; Binary Input 1 (the relay's feedback contact) and Multi-State Input 1 (the drive's speed) follow the winning command within a second.
- Failure Mode - a command it must refuse. A setpoint outside
Min_Pres_Value..Max_Pres_Value(10.0 .. 30.0), a Binary Output value other than 0/1, or a Multi-State Output state outside 1..3 gets Errorproperty/value-out-of-range, and nothing moves. A WriteProperty to an input gets Errorproperty/write-access-denied. - Failure Mode - a disconnected actuator. When the valve actuator is
disconnected, Analog Output 1
Reliabilityreadsno-output(6, "No physical device is connected to the Output object", clause 12.1) and the FAULT bit of itsStatus_Flagsis TRUE (clause 12.3.7). Commands are still accepted into thePriority_Array, but the temperature does not move. Reconnect it andReliabilityreturns tono-fault-detected, FAULT clears, and the valve obeys the winning command.
A real smart actuator drives a valve motor, a relay coil and a variable-speed
drive, and reads back what they did. This example has none of them, so it
simulates them - non-BACnet scaffolding, outside the BACnet Surface, in
section 1b of main.cpp (ActuatorSimulationTick(), called beside
BACnetStack_Tick()). Once a second:
- the heating valve moves the temperature (Analog Input 1) up to 1.0 C toward the winning Analog Output 1 setpoint;
- the relay's feedback contact (Binary Input 1) takes the winning Binary Output 1 command;
- the drive's speed (Multi-State Input 1) takes the winning Multi-State Output 1 command.
"Winning" is ResolvedCommand(): the highest-priority commanded slot, else
Relinquish_Default - the same answer the stack gives for Present_Value
(clause 19.2).
The disconnected valve is a test-only hook, not a feature: if the
environment variable CAS_EXAMPLE_TEST_ACTUATOR_FAULT_FILE names a file, the
valve actuator counts as disconnected for as long as that file exists. The Wire
Tests create and delete it. Nothing on the network can disconnect it.
To port the example to hardware, replace ActuatorSimulationTick() with code
that drives your outputs from ResolvedCommand() and samples your feedback
inputs, and set Reliability from your output driver's own diagnostics.
The example implements exactly the capabilities below - and nothing more, which is the point of a profile example.
| BIBB | Description | Supported |
|---|---|---|
| DS-RP-B | Data Sharing - ReadProperty - B | β |
| DS-WP-B | Data Sharing - WriteProperty - B | β |
| DM-DDB-B | Device Management - Dynamic Device Binding - B | β |
| DM-DOB-B | Device Management - Dynamic Object Binding - B | β |
| Service | Notes |
|---|---|
| ReadProperty | Responds to property reads (DS-RP-B). |
| WriteProperty | Accepts writes to the commandable outputs' Present_Value (DS-WP-B). |
| Who-Is / I-Am | Answers Who-Is with I-Am, and broadcasts an I-Am on start-up (DM-DDB-B). |
| Who-Has / I-Have | Answers Who-Has with I-Have (DM-DOB-B). |
| Object type | Instance | Name | Access |
|---|---|---|---|
| Device | 389002 | Chipkin Example B-SA | - |
| Analog Input | 1 | Bronze | read-only |
| Binary Input | 1 | Emerald | read-only |
| Multi-State Input | 1 | Hot Pink | read-only |
| Analog Output | 1 | Chartreuse | writable (commandable) |
| Binary Output | 1 | Fuchsia | writable (commandable) |
| Multi-State Output | 1 | Indigo | writable (commandable) |
| Network Port | 1 | Vermilion | - |
Every required property of every object, and who answers it, is in docs/PICS.md.
This example builds against the CAS BACnet Stack, which is a commercial Chipkin
product - it is not free or open source, and there is no public/trial build.
The stack is referenced here as the private git submodule
submodules/cas-bacnet-stack; you can only fetch and build it once you have a CAS
BACnet Stack license and access to that repository.
To get the CAS BACnet Stack (and access to build this example), contact Chipkin: https://store.chipkin.com/services/stacks/bacnet-stack or sales@chipkin.com.
You do not need a stack licence to read this example, or to run a prebuilt release binary. The licence is what lets you build it - that is the part the stack submodule gates.
This is a self-contained project. It ships:
main.cpp- the example device.common/- the shared helper (UDP, callbacks, CLI, keyboard) vendored in.CMakeLists.txt- the build, the same on Windows, Linux, and macOS.docs/PICS.md- the conformance statement.tests/- the Wire Tests (see Wire Tests), andwiretest/, the series' shared Python harness they are written against (vendored, likecommon/).submodules/cas-bacnet-stack/- the CAS BACnet Stack as a git submodule (private; requires a license - see above). Its sources are compiled into the executable, so there is no library or DLL to build, ship, or install.
- A C++17 compiler (MSVC, GCC, or Clang).
- CMake >= 3.15.
- Git (to fetch the stack submodule).
- C++ compiler - install Visual Studio Community (free) and select the "Desktop development with C++" workload.
- CMake - from https://cmake.org/download/, or
winget install Kitware.CMake.
- Debian/Ubuntu:
sudo apt install build-essential cmake git - macOS:
xcode-select --installandbrew install cmake
CMake only, and the same two commands on every platform:
git clone --recursive https://github.com/chipkin/BACnetProfileExample-B-SA-CPP.git
cd BACnetProfileExample-B-SA-CPP
cmake -B build -S .
cmake --build build --config ReleaseAlready cloned without --recursive? Run git submodule update --init --recursive
first - the build needs the stack submodule.
The first build takes a few minutes - it compiles the entire CAS BACnet Stack (~600 source files) into the executable. Rebuilds after that are incremental and take seconds.
If your CAS BACnet Stack lives somewhere other than the bundled submodule, point
CMake at it: cmake -B build -S . -D CAS_STACK_DIR=/path/to/cas-bacnet-stack.
# Linux / macOS
./build/BACnetExampleBSA
# Windows
.\build\Release\BACnetExampleBSA.exeExpected output:
BACnet B-SA (Smart Actuator) Example - C++ v1.3.0
CAS BACnet Stack version: 6.0.23.0
Common helper (common/) version: 3.4.0
FYI: Listening for BACnet/IP on UDP port 47808 (Network Port 1).
TX 21 bytes to 192.168.3.255:47808 (broadcast) (Network Port 1) - Unconfirmed: I-Am
FYI: Device 389002 ("Chipkin Example B-SA") ready. Vendor ID 389. Press 'h' for help.
The TX line is the start-up I-Am the device broadcasts to announce itself. It
goes to the local subnet broadcast address (here 192.168.3.255, computed
from the Network Port's interface), not the global 255.255.255.255. As clients
talk to the device you'll see RX ... bytes from ... and TX ... bytes to ...
lines showing the traffic; a WriteProperty to an output also prints a line such
as WriteProperty: Analog Output 1 (Chartreuse) <- 24.00 @ priority 8.
The device listens on UDP 47808 (BACnet/IP). Allow that port through your
firewall. To use a different port, pass --port (see below).
A wall of red
Error:lines at start-up is expected and is not your bug - it is the stack's own debug logging (the device hearing its own broadcast I-Am, and a one-time BACnet/SC UUID notice). TUTORIAL.md explains both.
| Option | Default | Meaning |
|---|---|---|
--port <n> |
47808 |
UDP port to listen on (BACnet/IP). |
--deviceID <n> |
389002 |
The device's BACnet instance number (BACnet requires this to be configurable). |
--help, -h |
- | Show usage and exit. |
--version |
- | Print the example, stack, and common/ helper versions, then exit. |
While the example runs, these keys are available:
| Key | Action |
|---|---|
h |
Show the version information and this command list. |
q |
Quit. |
| up arrow | Disturb the simulated temperature (Analog Input 1, Bronze) up by 1.1. |
| down arrow | Disturb the simulated temperature (Analog Input 1, Bronze) down by 1.1. |
The up/down keys push the simulated temperature off its setpoint; within a few seconds the valve brings it back, and a client re-reading Analog Input 1 sees both.
Use a BACnet client such as the CAS BACnet Explorer:
- Discover - send a Who-Is. The device replies with I-Am from instance 389002 (vendor 389). It also broadcasts an I-Am at start-up.
- Browse the object model - the device shows eight objects: the Device
(
Chipkin Example B-SA), three inputs, three outputs, and the Network Port (Vermilion). Reading the Device'sObject_Listreturns all eight. - Read the Device - ReadProperty
389002->Object_Namereturns"Chipkin Example B-SA";Protocol_Revisionreturns30;Descriptionreturns the profile description string. - Read a sensor - ReadProperty Analog Input
1->Present_Valuereturns20.0once the valve has settled at the default setpoint (it starts at21.5);Unitsreturnsdegrees-Celsius;Object_Namereturns"Bronze". - Command an output (the B-SA test) - ReadProperty Analog Output
1->Present_Valuereturns20.0(itsRelinquish_Default, nothing commanded yet). Now WriteProperty Analog Output1Present_Value=24.0at priority8. Re-readPresent_Value: it returns24.0, andPriority_Array[8]shows24.0. Read Analog Input1for a few seconds: it climbs to24.0. WritePropertyPresent_Value=NULLat priority8to relinquish;Present_Valuereturns to20.0, and so does Analog Input1. Repeat for Binary Output1("Fuchsia", active/inactive - watch Binary Input1) and Multi-State Output1("Indigo", state 1..3 - watch Multi-State Input1). - Confirm the profile boundary - a WriteProperty to a read-only input (e.g. Analog Input 1) is rejected. That is correct: inputs are sensors.
For a property-by-property review against the conformance statement, see TUTORIAL.md.
The checks above, automated: a Python BACnet client (the Peer) drives the running example over BACnet/IP from outside it. Python 3 standard library only.
| Script | What it proves |
|---|---|
discovery_test.py |
Who-Is, the Device's Object_List, then for every object its Property_List and a ReadProperty of every property it lists - every read comes back as a value. |
commanding_test.py |
The Profile Function. Commands each output at two priorities; Present_Value, Priority_Array and Current_Command_Priority follow the winning command, and the feedback input follows it too - through a lower-priority write that must change nothing, two relinquishes, and back to Relinquish_Default. Fails against an example that only stores commands. |
failure_modes_test.py |
The Failure Modes. Disconnects the valve actuator: Reliability no-output, Status_Flags FAULT, a command accepted but not obeyed; reconnects it: all clear, the valve obeys. Then out-of-range writes (value-out-of-range, nothing moves) and a write to an input (write-access-denied). |
Run them all:
python3 tests/run_wire_tests.py --exe build/BACnetExampleBSA # Linux/macOS
python tests\run_wire_tests.py --exe build\Release\BACnetExampleBSA.exe # WindowsIt ends with ALL WIRE TESTS PASSED (exit 0). CI runs it on Linux after the
smoke test. tests/README.md says what each check proves.
There is one example repository per standardized device profile in ASHRAE 135-2024 Annex L. An example marked β is blocked: the stack cannot yet perform that profile's function through its customer interface, and the example's README says what it does today. Pick the profile your device claims, then the language you build in. "Ask" means the example hasn't been built yet for that language - contact Chipkin if you need one.
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-SS Smart Sensor | B-SS-CPP | B-SS-Node | B-SS-CS | B-SS-Rust | B-SS-Python | B-SS-Go |
| B-SA Smart Actuator | B-SA-CPP | Ask | Ask | Ask | Ask | Ask |
| B-ASC Application Specific Controller | B-ASC-CPP | B-ASC-Node | Ask | Ask | Ask | Ask |
| B-AAC Advanced Application Controller | B-AAC-CPP | Ask | Ask | Ask | Ask | Ask |
| B-BC Building Controller | B-BC-CPP | Ask | Ask | Ask | Ask | Ask |
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-LSC Life Safety Controller | B-LSC-CPP π§ | Ask | Ask | Ask | Ask | Ask |
| B-ALSC Advanced Life Safety Controller | B-ALSC-CPP | Ask | Ask | Ask | Ask | Ask |
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-ACC Access Control Controller | B-ACC-CPP | Ask | Ask | Ask | Ask | Ask |
| B-AACC Advanced Access Control Controller | B-AACC-CPP | Ask | Ask | Ask | Ask | Ask |
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-LD Lighting Device | B-LD-CPP | Ask | Ask | Ask | Ask | Ask |
| B-LS Lighting Supervisor | B-LS-CPP | Ask | Ask | Ask | Ask | Ask |
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-EM Elevator Monitor | B-EM-CPP | Ask | Ask | Ask | Ask | Ask |
| B-EC Elevator Controller | B-EC-CPP | Ask | Ask | Ask | Ask | Ask |
| B-AEC Advanced Elevator Controller | B-AEC-CPP | Ask | Ask | Ask | Ask | Ask |
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-AS Authorization Server | B-AS-CPP β blocked on stack #2043 | Ask | Ask | Ask | Ask | Ask |
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-BBMD Broadcast Management Device | B-BBMD-CPP | Ask | Ask | Ask | Ask | Ask |
| B-ACDC Access Control Door Controller | B-ACDC-CPP | Ask | Ask | Ask | Ask | Ask |
| B-ACCR Access Control Credential Reader | B-ACCR-CPP β blocked on stack #3934 | Ask | Ask | Ask | Ask | Ask |
| B-RTR Router | B-RTR-CPP | Ask | Ask | Ask | Ask | Ask |
| B-GW Gateway | B-GW-CPP | Ask | Ask | Ask | Ask | Ask |
| B-DAP Device Address Proxy | B-DAP-CPP β blocked on stack #2032 | Ask | Ask | Ask | Ask | Ask |
| B-SCHUB BACnet/SC Hub | B-SCHUB-CPP | Ask | Ask | Ask | Ask | Ask |
| B-GENERAL General device (Annex L.8) | (satisfied by every example above) | β | β | β | β | β |
Client-side profiles.
| Profile | C++ | Node.js | C# | Rust | Python | Go |
|---|---|---|---|---|---|---|
| B-OD Operator Display | B-OD-CPP | Ask | Ask | Ask | Ask | Ask |
| B-OWS Operator Workstation | planned | β | β | β | β | β |
| B-AWS Advanced Operator Workstation | planned | β | β | β | β | β |
| B-XAWS Extended Advanced Operator Workstation | planned | β | β | β | β | β |
| B-LSAP Life Safety Annunciator Panel | planned | β | β | β | β | β |
| B-LSWS Life Safety Workstation | planned | β | β | β | β | β |
| B-ALSWS Advanced Life Safety Workstation | planned | β | β | β | β | β |
| B-ACSD Access Control Security Display | planned | β | β | β | β | β |
| B-ACWS Access Control Workstation | planned | β | β | β | β | β |
| B-AACWS Advanced Access Control Workstation | planned | β | β | β | β | β |
| B-LOD Lighting Operator Display | planned | β | β | β | β | β |
| B-ALWS Advanced Lighting Workstation | planned | β | β | β | β | β |
| B-LCS Lighting Control Station | planned | β | β | β | β | β |
| B-ALCS Advanced Lighting Control Station | planned | β | β | β | β | β |
| B-ED Elevator Display | planned | β | β | β | β | β |
| B-EWS Elevator Workstation | planned | β | β | β | β | β |
| B-AEWS Advanced Elevator Workstation | planned | β | β | β | β | β |
π§ = in progress. β = Blocked Example (blocked on the named stack gap). "Ask" = not yet built for that language; contact Chipkin if you need it. Profile definitions: ANSI/ASHRAE 135-2024 Annex L. BIBB definitions: Annex K. Get the stack: https://store.chipkin.com/services/stacks/bacnet-stack.
- ANSI/ASHRAE Standard 135 (BACnet) - the protocol standard. Object model (Clause 12), services (Clause 15), BACnet/IP (Annex J), device profiles (Annex L). Purchase / preview via the ASHRAE store.
- What is BACnet? - Chipkin's introduction: https://docs.chipkin.com/protocols/bacnet/.
- CAS BACnet Stack - product page and documentation: https://store.chipkin.com/services/stacks/bacnet-stack.
- CAS BACnet Explorer - client for testing this device: https://store.chipkin.com/products/tools/cas-bacnet-explorer.
- B-SS (Smart Sensor) example - the read-only sibling this builds on: https://github.com/chipkin/BACnetProfileExample-B-SS-CPP.
- Shared helper used by this example -
common/README.md.
See also TUTORIAL.md, docs/PICS.md, CHANGELOG.md, and AGENTS.md.