AGENTS.md

1# Agent instructions — DIY BACnet Server (Open-FDD field-bus)
2 
3This file is **durable project context**. Do not remove or bypass these rules when refactoring.
4 
5## Hosted BACnet device (device 599999 / OpenFDD)
6 
7The gateway hosts a BACnet/IP server on UDP **47808** (configurable via `OPENFDD_FIELDBUS_BACNET_PORT`).
8 
9| Requirement | Detail |
10|-------------|--------|
11| Device name | `OpenFDD` (`config/gateway.toml` → `device_name`) |
12| Vendor ID | **999** on `BACnetServer::bip_builder().vendor_id(999)` **and** `DeviceConfig.vendor_id` |
13| Model | `openfdd-fieldbus` |
14| Point catalog | `config/objects.csv` — **do not drop rows** without explicit user request |
15 
16### Server vs client UDP sockets
17 
18- **Server** binds `0.0.0.0:47808` (or configured port) — only socket on that port.
19- **Client** uses **ephemeral** UDP ports (`whois_bind_port = 0` in `gateway.toml`).
20- Never bind the BACnet client to the same UDP port as the hosted server (causes Workbench `???` / dropped ReadProperty).
21 
22## REST vs BACnet write split (critical — no data races)
23 
24Points in `objects.csv` with **`Commandable=Y`** are **BACnet-writable only**:
25 
26- External BMS / Workbench / Niagara may WriteProperty (e.g. `openfdd-optimization-enabled` BV **9010**).
27- REST **`POST /bacnet/server/update` must reject** writes to commandable points.
28- Mechanism: `BacnetServerManager::api_writable()` / `reject_api_write()` in `rust-api/src/services/bacnet_server.rs`.
29- Rejection message constant: `API_WRITABLE_REJECT_MSG`.
30 
31Points with **`Commandable=N`** are **server-owned** (weather mirror, FDD diagnostics). Only these may be updated via REST.
32 
33### Tests that must stay green
34 
35- `every_commandable_point_rejects_api_write`
36- `optimization_enabled_is_only_commandable_hosted_point`
37- `update_rejects_commandable_point`
38- Smoke: `scripts/smoke_test.sh` hosted-server section (commandable reject + weather points)
39 
40## Weather mirror (Open-Meteo)
41 
42Weather AVs **9101–9104**, location CSV **9105**, fault BV **9106**, last-updated CSV **9107**.
43 
44On each mirror cycle, update:
45 
461. **Present-value** on weather points
472. **Description** with live Open-Meteo context (value + timestamp + source)
483. **`weather-last-updated`** (CSV:9107) with human-readable timestamp
49 
50Implementation: `rust-api/src/services/weather.rs` → `mirror_to_bacnet()`.
51 
52## Before merging BACnet changes
53 
541. `cargo test` in `rust-api/`
552. `scripts/smoke_test.sh` against running container
563. Optional: `point-discover --device 599999 --address <host>:47808` from rusty-bacnet samples — expect name **OpenFDD** and ≥10 objects
57 
58## Swagger / OpenAPI bench examples
59 
60- **`OPENFDD_FIELDBUS_SWAGGER_BENCH=1`** by default — bench JSON bodies always pre-filled (opt-out with `=0`).
61- **Open-FDD workflow:** `POST /bacnet/whois` `{}` → `POST /api/bacnet/point-discovery` → `POST /api/bacnet/supervisory`.
62- **`GET /bacnet/points` removed** — use Who-Is + point discovery instead.
63 
64## Key files
65 
66```
67config/objects.csv          # hosted point catalog (+ Description column)
68config/gateway.toml         # device 599999, server bind, client ephemeral ports
69rust-api/src/services/bacnet_server.rs
70rust-api/src/services/weather.rs
71scripts/smoke_test.sh
72```
73