Copy page

Documentation

Windrow - Periodic Discovery and Credentials

Mirrors Windrow's own docs/periodic-discovery-and-credentials.md — Windrow is a sibling repo (github.com/jacobnash/Windrow); this page makes the worked example reachable from here. Built for new-construction commissioning: equipment shows up on the network over time, and a human shouldn't have to remember to click "scan." windrow.api runs discovery on its own on a timer, tracks every device either scan has ever seen — separate from provisioned connections — and gives you somewhere to record a login if a device needs one.

Code
python -m windrow.api --address 192.168.128.63/24:47820 --mqtt-host localhost \
  --bacnet-discovery-interval 300 \
  --modbus-scan-cidr 192.168.1.0/24 --modbus-scan-interval 600

• BACnet Who-Is scanning always runs (--bacnet-discovery-interval, default 300s) — no subnet argument needed, it broadcasts on whatever interface --address already bound.
• Modbus scanning is off by default. Modbus has no discovery protocol of its own — "scan" means TCP-connect-sweeping a subnet on port 502 — so there's no safe range to guess. Pass --modbus-scan-cidr (repeatable) to turn it on for one or more subnets.

1. See what's been found

Code
curl localhost:8001/devices

Code
[
  {
    "id": "7a1ac077179748588d981ef714161bda",
    "protocol": "bacnet",
    "device_instance": 3456,
    "address": "192.168.128.167",
    "vendor_id": 999,
    "status": "pending",
    "connection_id": null,
    "credential": null,
    "default_credential_flag": null,
    "default_credential_checked_at": null,
    "first_seen_at": 1786888550.46,
    "last_seen_at": 1786888550.46
  }
]

status is pending (seen, not provisioned), provisioned (a matching connection exists — flips automatically, no extra call needed once you POST /connections or POST /modbus/connections for it), or ignored (a human dismissed it via PATCH /devices/{id}, survives future rescans).

2. Set a credential, if the device needs one

Neither BACnet nor Modbus has protocol-level auth — this is pure bookkeeping for whatever manual login the device's own surface needs (a gateway's local web UI, most commonly), recordable before any connection exists for it:

Code
curl -X PATCH localhost:8001/devices/<id>/credential -d '{"username": "admin", "password": "sup3r-secret"}'

Code
{"username": "admin", "password": "sup3r-secret"}

The plaintext password is shown once, in this response only. Every later GET /devices (or GET /connections / GET /modbus/connections, which support the same PATCH .../credential) redacts it:

Code
{"username": "admin", "password": null}

Stored encrypted at rest (Fernet, via the cryptography package), keyed by the WINDROW_CREDENTIAL_KEY env var — generate one with:

Code
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Setting a credential is bookkeeping only — nothing here logs into the device with it. That's deliberately out of scope; there's no protocol handshake to wire it into yet.

3. Default-credential check

The first time a Modbus device is seen as pending, windrow.api automatically tries a short list of common defaults (admin/admin, admin/password, root/root, …) as HTTP Basic Auth against the device's own address, on ports 80 and 443 — GET only, non-destructive, meant to catch equipment still on factory defaults during commissioning:

Code
"default_credential_flag": {"username": "admin", "password": "admin", "scheme": "http", "checked_at": 1786888550.46}

BACnet devices always show default_credential_flag: null. BACnet has no HTTP-login concept of its own, so there's nothing to check — this is explicit, not a silently-skipped feature. Re-run the check later (e.g. after changing the device's password) with:

Code
curl -X POST localhost:8001/devices/<id>/recheck-credentials

Known gap: HTTP Basic Auth only. Real gateway firmware more often uses a form-based admin login, which this doesn't catch — would need per-vendor knowledge, out of scope for a basic check.

4. Modbus: discover and provision

Modbus has no self-describing object list like BACnet's — register addresses are opaque and vendor-documented, so you supply {label: address} directly instead of a /learn step:

Code
curl -X POST localhost:8001/modbus/discover -d '{"cidr": "192.168.1.0/24"}'

Code
[{"host": "192.168.1.50", "port": 502, "vendor": "Acme Controls", "product_code": "X1-2000", "revision": "2.0"}]

vendor/product_code/revision come from Modbus function 0x2B/0x0E (Read Device Identification) where the device implements it — null on a device that doesn't is a normal result, not an error.

Code
curl -X POST localhost:8001/modbus/connections -d '{
  "host": "192.168.1.50",
  "topic_prefix": "fbf/modbus-ahu-1",
  "poll_interval": 5.0,
  "points": {"zone-temp": 0, "fan-status": 1}
}'

Same GET/DELETE .../{id} and PATCH .../{id}/credential shape as BACnet connections.

Known v1 limitations

• Same-host broadcast quirk as /discover. A locally-originated BACnet Who-Is broadcast doesn't reliably loop back to another process on the same machine (macOS/BSD networking behavior) — the periodic BACnet scan can look like it's finding nothing if you're testing against a mock device on the same host. Works normally against real devices on a real network. Verified live: this is genuinely non-deterministic on a single host, not a bug in the scan loop itself (confirmed by driving device_registry.reconcile_bacnet() directly against a real, reliable directed discovery call — the reconciliation logic behaves correctly every time; only the same-host broadcast delivery is flaky).
• One shared poll interval per Modbus connection, not per-point like BACnet connections support (his_collect_cov etc.) — nothing asked for that yet, and Modbus's opaque register model doesn't get much from it.
• No default-credential check for BACnet — see above, not a gap so much as "the check has nowhere to point itself."
• No file locking on windrow-devices.json / windrow-modbus-connections.json — same accepted single-writer assumption as connections.json.

Real bugs this was verified against, not just assumed to work

• Device-registry reconciliation never matched a provisioned connection back to its discovered device. discover_devices()'s own address field never carries a port ("no port — the standard BACnet/IP port 47808 is implied"), but a connection's device_address field commonly does ("192.168.128.63:47808", matching every worked example in this repo) — the two never compared equal. Fixed by normalizing on the host portion before matching. Found by actually provisioning a connection against a live mock device and watching status never leave pending, not by reading the code.
• An unclosed AsyncModbusTcpClient stalls process shutdown indefinitely. pymodbus's async client spawns its own internal "transport reconnect" background task; if nothing calls client.close() before the owning asyncio.run() call tears down, that task doesn't respond to cancellation in time and the whole shutdown hangs forever. Reproduced reliably with two sequential asyncio.run() calls in one process (exactly windrow.api's create-a-connection-then-restart shape); fixed with an explicit ModbusConnectionManager.close() called from api.py's shutdown path (and from every test's teardown).
• pymodbus 3.14's real method is read_device_information(device_id=...), not read_device_identification — confirmed via inspect against the installed package rather than guessed from older docs/examples.