# Connect a BACnet controller

Configure a BACnet/IP device, create typed tags, publish the project, and verify its readings. Screens subscribe to the same tag paths.

## What the driver does — and its limits today.

- Speaks BACnet/IP (UDP, default 47808): one ReadProperty per tag per poll, WriteProperty at an optional priority, typed values into the tag engine.
- **Unicast, by IP.** You configure each controller's address — there is no Who-Is network scan.
- **No BBMD / foreign-device registration.** Devices only reachable through a BACnet router (MS/TP trunks, other subnets behind a BBMD) aren't addressable through this driver.

Prerequisites: a configured Thermite site with the CLI on PATH and HMI serving enabled, a reachable BACnet/IP controller (or the [device zoo](https://thermitescada.com/docs/device-zoo.md)'s VAV farm), its IP, and the object type + instance of each point — a third-party BACnet browser helps you confirm the object list first.

## Add the device.

```toml
# config/server.toml
[[devices]]
name = "ahu-1"                 # tags reference this via device = "ahu-1"
driver = "bacnet"
enabled = true

[devices.config]
host = "192.168.1.50"          # the controller's IP — required
port = 47808
poll_rate_ms = 1000
write_priority = 8             # optional: priority-array level for writes
```

## Define the tags.

The address is `<object>,<instance>[:<property>]` — comma before the instance, optional colon-property (default `present-value`). From the site root, run thermite project init bacnet-demo, then add tags/ahu1.toml. History recording also requires the gateway historian and a PostgreSQL connection; see Server configuration for those settings.

```toml
# projects/bacnet-demo/tags/ahu1.toml
[[tags]]
name = "Space Temp"
path = "ahu1/space_temp"
data_type = "f32"              # Analog present-value is Real → f32
device = "ahu-1"
address = "AV,1"
eng_units = "degF"
history = { enabled = true }

[[tags]]
name = "Occupancy"
path = "ahu1/occupied"
data_type = "i16"              # Binary present-value is enumerated 0/1 → i16, NOT bool
device = "ahu-1"
address = "BV,3"

[[tags]]
name = "Fan Speed Cmd"
path = "ahu1/fan_speed_cmd"
data_type = "f32"
device = "ahu-1"
address = "AO,2"              # AnalogOutput 2 — writable at write_priority
```

| Object (present-value) | Wire type | data_type |
| --- | --- | --- |
| Analog — AI / AO / AV | Real | `f32 (or f64)` |
| Binary — BI / BO / BV | Enumerated 0/1 | `i16 (or i32 / u16) — not bool` |
| MultiState — MSI / MSO / MSV | Unsigned | `i16 (or i32 / u16)` |
| :object-name, :description | CharacterString | `string` |

Use a supported wire-type conversion. A `bool` tag on a Binary object reads null with bad quality. Writes carry the tag's declared type onto the wire; the driver is not object-aware: `f32`→Real, `f64`→Double, `bool`→Boolean, `i16/i32/i64`→SignedInt, `u16`→UnsignedInt — there is no Enumerated encoding. For an Analog output declare `f32` so the write emits Real (not every device accepts Double for a Real present-value). Binary/MultiState writes are best-effort — an `i16` emits SignedInt, which lenient controllers accept and strict ones may reject; test against your device.

## Publish and verify.

Run the licensed or trial gateway with `thermite-server --site .` and publish the project. These curl examples use the default, disabled authentication; with authentication enabled, supply a session and the CSRF token for writes.

```sh
$ thermite project publish bacnet-demo
$ curl http://localhost:8400/p/bacnet-demo/api/tags/ahu1/space_temp
{ "type": "tag", "path": "ahu1/space_temp", "value": { "value": 71.4, "quality": "good", "timestamp": "2026-07-03T18:40:12.314Z" } }

# command the fan
$ curl -X PUT http://localhost:8400/p/bacnet-demo/api/tags/ahu1/fan_speed_cmd \
    -H "Content-Type: application/json" -d '{"value": 60.0}'
```

Check the device panel at `http://localhost:8400/admin/` (or `GET /api/devices`). One UDP subtlety: BACnet/IP is connectionless, so a wrong `host` shows *Connected* initially. Transport failures change it to *Reconnecting* after the polling round; APDU timeouts and retries apply to each read. On a screen, bind the same paths with `Thermite.subscribe("ahu1/space_temp", …)` — see [HMI screens](https://thermitescada.com/docs/screen-development.md).

## The four failure shapes.

### Device stuck Reconnecting, all tags bad

Transport failure. Wrong host/port, a firewall on UDP 47808, or the device is behind a BACnet router (unsupported). Confirm reachability with a BACnet browser from the same host.

### Connected, but one tag bad-quality

Tag-level error. The object doesn't exist, the alias is wrong, or data_type doesn't match the wire type (bool on a Binary object → use i16).

### A good reading is 0 or 1 where an analog value was expected

Check the object type: a Binary point returns 0/1. Unsupported wire-type/tag-type combinations produce null, bad-quality readings.

### A write errors on Binary/MultiState

An i16 tag sends SignedInt; a u16 tag sends UnsignedInt. The driver does not emit Enumerated. Confirm the device's accepted write encoding.

On a read error the server log names the tag, object, and property; on a write failure, the tag and device. Use these details to find the misconfigured point.
