Skip to content

Commit 8ac7a2d

Browse files
jscott3201jscott3201
committed
Docs upates
1 parent 6b0cfb1 commit 8ac7a2d

File tree

8 files changed

+3542
-51
lines changed

8 files changed

+3542
-51
lines changed

‎README.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ A complete BACnet protocol stack (ASHRAE 135-2020) written in Rust, with first-c
99

1010
- **Full BACnet/IP stack** — async client and server with 30+ service types
1111
- **5 transports** — BACnet/IP (UDP), BACnet/IPv6 (multicast), BACnet/SC (WebSocket+TLS with hub), MS/TP (serial), Ethernet (BPF)
12-
- **64 object types** — All standard BACnet objects including Analog/Binary/MultiState I/O, Device, Schedule, Calendar, Trend Log, Notification Class, Loop, Access Control, Lighting, Life Safety, Elevator, Color, Color Temperature, and more
12+
- **65 object types** — All standard BACnet objects including Analog/Binary/MultiState I/O, Device, Schedule, Calendar, Trend Log, Notification Class, Loop, Access Control, Lighting, Life Safety, Elevator, Color, Color Temperature, and more
1313
- **HTTP REST API + MCP server** — `bacnet-gateway` crate with REST endpoints and Model Context Protocol tools for LLM-driven BACnet interaction
1414
- **BTL compliance test harness** — 3,808 tests covering 100% of BTL Test Plan 26.1 across all 13 sections
1515
- **Python bindings** — async client, server, and SC hub with full API parity via PyO3
@@ -318,7 +318,7 @@ crates/
318318
bacnet-transport/ BIP, BIP6, BACnet/SC + Hub, MS/TP, BBMD, Ethernet, Loopback
319319
bacnet-network/ Network layer routing, router tables
320320
bacnet-client/ Async client with TSM, segmentation, discovery
321-
bacnet-objects/ BACnetObject trait, ObjectDatabase, 64 object types
321+
bacnet-objects/ BACnetObject trait, ObjectDatabase, 65 object types
322322
bacnet-server/ Async server (RP/WP/RPM/WPM/COV/Events/DCC/CreateObject/TimeSynchronization)
323323
bacnet-gateway/ HTTP REST API + MCP server gateway (Axum + rmcp)
324324
bacnet-btl/ BTL compliance test harness (BTL Test Plan 26.1, 3808 tests, all 13 sections)
@@ -442,10 +442,15 @@ Minimum Rust version: 1.93
442442

443443
## Documentation
444444

445-
- [CLI Reference](docs/CLI.md)
446-
- [Rust API Reference](docs/rust-api.md)
447-
- [Python API Reference](docs/python-api.md)
448-
- [Benchmark Results](Benchmarks.md)
445+
- [Gateway Reference](docs/gateway.md) — HTTP REST API, MCP server, configuration, authentication
446+
- [Rust API Reference](docs/rust-api.md) — all 9 published crates with examples
447+
- [Python API Reference](docs/python-api.md) — 42+ async client methods, 61 server object types
448+
- [WASM/JS API Reference](docs/wasm-api.md) — BACnet/SC thin client for browsers
449+
- [CLI Reference](docs/CLI.md) — interactive shell and one-shot commands
450+
- [BTL Test Harness](docs/btl.md) — 3,808 compliance tests, 5 commands, Docker topologies
451+
- [Benchmark Results](Benchmarks.md) — 9 suites with throughput, latency, and memory
452+
- [Architecture Guide](docs/architecture.md) — crate graph, packet flow, concurrency model
453+
- [Changelog](CHANGELOG.md)
449454
- [Examples](examples/)
450455

451456
## License

‎docs/CLI.md‎

Lines changed: 213 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ cargo install bacnet-cli --features sc-tls
2222

2323
| Flag | Default | Description |
2424
|------|---------|-------------|
25-
| `-i, --interface <IP>` | `0.0.0.0` | Network interface IP to bind |
25+
| `-i, --interface <IP>` | (see below) | Network interface IP to bind |
2626
| `-p, --port <PORT>` | `47808` | BACnet UDP port |
2727
| `-b, --broadcast <IP>` | `255.255.255.255` | Broadcast address for WhoIs |
2828
| `-t, --timeout <MS>` | `6000` | APDU timeout in milliseconds |
@@ -39,6 +39,23 @@ cargo install bacnet-cli --features sc-tls
3939

4040
Output auto-detects: tables in TTY, JSON when piped.
4141

42+
**Interface selection:** When launching the interactive shell without `--interface` on BACnet/IP, the CLI lists available network interfaces and prompts you to select one. For one-shot commands without `--interface`, it defaults to `0.0.0.0`.
43+
44+
## Target Resolution
45+
46+
Commands that take a `<target>` argument accept several formats:
47+
48+
| Format | Example | Description |
49+
|--------|---------|-------------|
50+
| IPv4 address | `192.168.1.100` | Direct BIP target (default port 47808) |
51+
| IPv4:port | `10.0.1.5:47809` | Direct BIP target with explicit port |
52+
| IPv6 bracket | `[fe80::1]` | Direct BIP6 target (default port 47808) |
53+
| IPv6:port | `[fe80::1]:47809` | Direct BIP6 target with explicit port |
54+
| Device instance | `1234` | Looks up address from discovered device cache |
55+
| DNET:instance | `2:1234` | Routed device (network:instance) |
56+
57+
When using a device instance number, the device must have been previously found via `discover`. In the shell, you can set a default target with the `target` command to omit the target argument from subsequent commands.
58+
4259
## Commands
4360

4461
### Interactive Shell
@@ -48,17 +65,63 @@ bacnet # launch interactive REPL
4865
bacnet shell # same as above
4966
```
5067

51-
The shell supports command history, tab completion, and all commands below.
68+
The shell provides:
69+
70+
- **Tab completion** for commands, object types, and property names
71+
- **Command history** (saved to `~/.bacnet_history`) with history-based hints
72+
- **Default target** via the `target` command (omit target from subsequent commands)
73+
- **BBMD auto-renewal** at 80% of TTL when registered via `register`
74+
- **Colored output** (green for success/values, red for errors, cyan for addresses, dimmed for labels)
75+
- **Quoted string support** in arguments (e.g., `write 10.0.1.5 av:1 on "Zone Temp"`)
76+
77+
Shell-only commands:
78+
79+
```bash
80+
target 192.168.1.100 # set default target
81+
target 1234 # set default target by device instance
82+
target clear # clear default target
83+
target # show current default target
84+
85+
status # show session state (transport, local address,
86+
# default target, BBMD registration, device count)
87+
88+
help # list all commands
89+
exit # exit the shell (also: quit, Ctrl-D)
90+
```
91+
92+
**Command aliases in shell:** `whois`=discover, `whohas`=find, `rp`=read, `rpm`=readm, `rr`=read-range, `wp`=write, `wpm`=writem, `cov`=subscribe, `dcc`=control, `ack`=ack-alarm, `ts`=time-sync
5293

5394
### Device Discovery
5495

5596
```bash
56-
bacnet discover # discover all devices
57-
bacnet discover 1000-2000 # discover devices in instance range
58-
bacnet discover --wait 5 # wait 5 seconds for responses
97+
bacnet discover # discover all devices
98+
bacnet discover 1000-2000 # discover devices in instance range
99+
bacnet discover --wait 5 # wait 5 seconds for responses (default: 3)
100+
bacnet discover --target 192.168.1.100 # directed (unicast) WhoIs
101+
bacnet discover --dnet 2 # target a specific remote network
102+
bacnet discover --bbmd 10.0.0.1 # register as foreign device before discovering
103+
bacnet discover --bbmd 10.0.0.1 --ttl 300 # BBMD registration with TTL (default: 300s)
104+
```
105+
106+
**Discover flags:**
107+
108+
| Flag | Default | Description |
109+
|------|---------|-------------|
110+
| `--wait <N>` | `3` | Seconds to wait for responses |
111+
| `--target <ADDR>` | | Send directed WhoIs to a specific IP address |
112+
| `--dnet <N>` | | Target a specific remote network number |
113+
| `--bbmd <ADDR>` | | Register as foreign device with BBMD before discovering (BIP only) |
114+
| `--ttl <N>` | `300` | TTL in seconds for BBMD foreign device registration |
115+
116+
```bash
117+
bacnet find "Zone Temp" # find objects by name (WhoHas)
118+
bacnet find --name "Zone Temp" # same, explicit flag
119+
bacnet find "Zone Temp" --wait 5 # wait 5 seconds for responses
120+
```
59121

60-
bacnet find --name "Zone Temp" # find objects by name (WhoHas)
61-
bacnet devices # list cached discovered devices
122+
```bash
123+
bacnet devices # list cached discovered devices
124+
bacnet whois-router # send Who-Is-Router-To-Network
62125
```
63126

64127
### Reading Properties
@@ -67,23 +130,60 @@ bacnet devices # list cached discovered devices
67130
bacnet read 192.168.1.100 ai:1 pv # read present-value
68131
bacnet read 192.168.1.100 analog-input:1 present-value # full names work too
69132
bacnet read 192.168.1.100 device:1234 object-name
133+
bacnet read 192.168.1.100 ai:1 ol[3] # read array index (object-list[3])
134+
bacnet read 192.168.1.100 ai:1 all # read ALL properties via RPM
70135

71-
# Read multiple properties
136+
# Read multiple properties (ReadPropertyMultiple)
72137
bacnet readm 192.168.1.100 ai:1 pv,object-name ao:1 pv
73138

74139
# Read range (trend logs, lists)
75140
bacnet read-range 192.168.1.100 trend-log:1 log-buffer
141+
bacnet read-range 192.168.1.100 trend-log:1 # defaults to log-buffer
76142
```
77143

144+
**Aliases:** `rp` = read, `rpm` = readm, `rr` = read-range
145+
78146
### Writing Properties
79147

80148
```bash
81-
bacnet write 192.168.1.100 av:1 pv 72.5 # write a value
82-
bacnet write 192.168.1.100 av:1 pv 72.5 --priority 8 # with priority
149+
bacnet write 192.168.1.100 av:1 pv 72.5 # write a float value
150+
bacnet write 192.168.1.100 av:1 pv 72.5 --priority 8 # with priority (1-16)
83151
bacnet write 192.168.1.100 bv:1 pv true # boolean
152+
bacnet write 192.168.1.100 bv:1 pv active # enumerated (active=1)
84153
bacnet write 192.168.1.100 av:1 pv null --priority 8 # relinquish
154+
bacnet write 192.168.1.100 av:1 on "\"Zone Temp\"" # character string
155+
bacnet write 192.168.1.100 av:1 pv 72.5@8 # inline priority syntax
156+
bacnet write 192.168.1.100 av:1 pv enumerated:3 # explicit enumerated
157+
bacnet write 192.168.1.100 sc:1 pv date:2024-03-15 # date value
158+
bacnet write 192.168.1.100 sc:1 pv time:14:30:00 # time value
159+
bacnet write 192.168.1.100 nc:1 pv object:ai:1 # object identifier value
160+
```
161+
162+
**Write multiple properties (shell only):**
163+
164+
```bash
165+
writem 192.168.1.100 av:1 pv=72.5,desc="Zone Temp" av:2 pv=68.0
85166
```
86167

168+
**Aliases:** `wp` = write, `wpm` = writem
169+
170+
**Value formats:**
171+
172+
| Format | Example | BACnet Type |
173+
|--------|---------|-------------|
174+
| `null` | `null` | Null |
175+
| `true` / `false` | `true` | Boolean |
176+
| `active` / `inactive` | `active` | Enumerated (1/0) |
177+
| Integer | `42`, `-5` | Unsigned / Signed |
178+
| Float | `72.5`, `1e10` | Real |
179+
| Quoted string | `"hello"` | CharacterString |
180+
| `enumerated:N` | `enumerated:3` | Enumerated |
181+
| `date:YYYY-MM-DD` | `date:2024-03-15` | Date (use `*` for unspecified) |
182+
| `time:HH:MM:SS[.hh]` | `time:14:30:00` | Time (use `*` for unspecified) |
183+
| `object:type:inst` | `object:ai:1` | ObjectIdentifier |
184+
185+
Inline priority: append `@N` to any value (e.g., `72.5@8`, `null@16`).
186+
87187
### COV Subscriptions
88188

89189
```bash
@@ -92,34 +192,103 @@ bacnet subscribe 192.168.1.100 ai:1 --confirmed # confirmed COV
92192
bacnet subscribe 192.168.1.100 ai:1 --lifetime 300 # 5-minute subscription
93193
```
94194

195+
Subscribes and then watches for COV notifications in real time. Press Ctrl+C to stop watching.
196+
197+
**Alias:** `cov` = subscribe
198+
199+
### Alarms and Events
200+
201+
```bash
202+
bacnet alarms 192.168.1.100 # get event/alarm summary
203+
204+
bacnet ack-alarm 192.168.1.100 ai:1 --state 1 # acknowledge an alarm
205+
bacnet ack-alarm 192.168.1.100 ai:1 --state 1 --source "operator" # custom source
206+
```
207+
208+
**ack-alarm flags:**
209+
210+
| Flag | Default | Description |
211+
|------|---------|-------------|
212+
| `--state <N>` | (required) | Event state to acknowledge (0=normal, 1=fault, etc.) |
213+
| `--source <S>` | `bacnet-cli` | Acknowledgment source string |
214+
215+
**Alias:** `ack` = ack-alarm
216+
95217
### Device Management
96218

97219
```bash
98220
# Communication control
99221
bacnet control 192.168.1.100 disable --duration 5
222+
bacnet control 192.168.1.100 disable-initiation
100223
bacnet control 192.168.1.100 enable
224+
bacnet control 192.168.1.100 disable --password secret
101225

102226
# Reinitialize
103-
bacnet reinit 192.168.1.100 coldstart --password secret
227+
bacnet reinit 192.168.1.100 coldstart
228+
bacnet reinit 192.168.1.100 warmstart --password secret
229+
bacnet reinit 192.168.1.100 start-backup
230+
bacnet reinit 192.168.1.100 activate-changes
231+
```
232+
233+
**Control actions:** `enable`, `disable`, `disable-initiation`
234+
235+
**Control flags:**
104236

237+
| Flag | Description |
238+
|------|-------------|
239+
| `--duration <M>` | Duration in minutes |
240+
| `--password <P>` | Password string |
241+
242+
**Aliases:** `dcc` = control
243+
244+
**Reinit states:** `coldstart`, `warmstart`, `start-backup`, `end-backup`, `start-restore`, `end-restore`, `abort-restore`, `activate-changes`
245+
246+
**Reinit flags:**
247+
248+
| Flag | Description |
249+
|------|-------------|
250+
| `--password <P>` | Password string |
251+
252+
```bash
105253
# Time synchronization
106254
bacnet time-sync 192.168.1.100
107255
bacnet time-sync 192.168.1.100 --utc
108256

109257
# Create/delete objects
110258
bacnet create-object 192.168.1.100 av:100
111259
bacnet delete-object 192.168.1.100 av:100
112-
113-
# Alarms and events
114-
bacnet alarms 192.168.1.100
115-
bacnet ack-alarm 192.168.1.100 ai:1 --state 1
116260
```
117261

262+
**Alias:** `ts` = time-sync
263+
118264
### File Transfer
119265

120266
```bash
121-
bacnet file-read 192.168.1.100 1 --count 4096 --output data.bin
122-
bacnet file-write 192.168.1.100 1 firmware.bin --start 0
267+
bacnet file-read 192.168.1.100 1 --output data.bin # save to file
268+
bacnet file-read 192.168.1.100 1 --start 0 --count 4096 # with range
269+
bacnet file-write 192.168.1.100 1 firmware.bin # write file
270+
bacnet file-write 192.168.1.100 1 firmware.bin --start 0 # with offset
271+
```
272+
273+
**file-read flags:**
274+
275+
| Flag | Default | Description |
276+
|------|---------|-------------|
277+
| `--start <N>` | `0` | Start position in file |
278+
| `--count <N>` | `1024` | Byte count to read |
279+
| `--output <PATH>` | | Save data to file (otherwise hex-dumps to stdout) |
280+
281+
**file-write flags:**
282+
283+
| Flag | Default | Description |
284+
|------|---------|-------------|
285+
| `--start <N>` | `0` | Start position in file |
286+
287+
### Network and Routing
288+
289+
```bash
290+
bacnet whois-router # send Who-Is-Router-To-Network
291+
bacnet devices # list cached discovered devices
123292
```
124293

125294
### BBMD Management
@@ -133,6 +302,8 @@ bacnet register 192.168.1.1 --ttl 300 # register as foreign device
133302
bacnet unregister 192.168.1.1 # unregister from BBMD
134303
```
135304

305+
In the interactive shell, `register` also starts a background auto-renewal task that re-registers at 80% of the TTL (e.g., every 240 seconds for a 300-second TTL). The renewal runs silently in the background and prints a dimmed confirmation on each renewal. Use `unregister` or `status` to check registration state.
306+
136307
### Packet Capture
137308

138309
Requires the `pcap` feature (included in Linux pre-built binaries). Live capture requires root/sudo on most systems.
@@ -178,6 +349,8 @@ bacnet capture --device eth0 --filter "host 10.0.0.1" --decode --save filtered.p
178349
| `--count <N>` | Stop after N packets |
179350
| `--snaplen <N>` | Max bytes per packet (default: 65535) |
180351

352+
Note: `--read` and `--device` are mutually exclusive; `--quiet` requires `--save`.
353+
181354
**Output example (summary):**
182355
```
183356
12:34:56.789 192.168.1.100:47808 -> 192.168.1.255:47808 ORIGINAL_BROADCAST_NPDU WHO_IS
@@ -215,16 +388,23 @@ bacnet --sc --sc-url wss://hub:443 --sc-cert cert.pem --sc-key key.pem read 00:0
215388
| `bi` | binary-input |
216389
| `bo` | binary-output |
217390
| `bv` | binary-value |
218-
| `mi` | multi-state-input |
219-
| `mo` | multi-state-output |
220-
| `mv` | multi-state-value |
391+
| `msi` | multi-state-input |
392+
| `mso` | multi-state-output |
393+
| `msv` | multi-state-value |
221394
| `dev` | device |
222-
| `file` | file |
223-
| `schedule` | schedule |
224-
| `calendar` | calendar |
225-
| `tl` | trend-log |
395+
| `sc` | schedule |
396+
| `cal` | calendar |
226397
| `nc` | notification-class |
227-
| `loop` | loop |
398+
| `trn` | trend-log |
399+
| `lo` | loop |
400+
| `lp` | life-safety-point |
401+
| `lsp` | life-safety-point |
402+
| `acc` | accumulator |
403+
| `pi` | pulse-converter |
404+
| `prg` | program |
405+
| `cmd` | command |
406+
407+
All BACnet object types are also accepted by full name in kebab-case (e.g., `analog-input`, `notification-forwarder`, `color-temperature`) or by numeric value.
228408

229409
## Property Shorthand
230410

@@ -233,10 +413,16 @@ bacnet --sc --sc-url wss://hub:443 --sc-cert cert.pem --sc-key key.pem read 00:0
233413
| `pv` | present-value |
234414
| `on` | object-name |
235415
| `ot` | object-type |
416+
| `desc` | description |
236417
| `sf` | status-flags |
418+
| `es` | event-state |
237419
| `oos` | out-of-service |
238-
| `desc` | description |
239-
| `units` | units |
420+
| `pa` | priority-array |
421+
| `rd` | relinquish-default |
422+
| `ol` | object-list |
423+
| `all` | ALL (reads all properties via RPM) |
424+
425+
All BACnet properties are also accepted by full name in kebab-case (e.g., `present-value`, `reliability`, `notification-class`) or by numeric value. Array indices use bracket syntax: `ol[3]`, `pa[8]`.
240426

241427
## Pre-built Binaries
242428

0 commit comments

Comments
 (0)