julian
1efa77bf56
A parking lot is one pool of spaces with a flexible set of entry/exit
points — no "lane". Direction is a property of each RELAY inside an access
controller; readers/cameras bind to a controller relay and inherit it.
Schema:
- drop `lane` from ledger_events, device_events, sessions
- rename lane_devices -> devices (no lane/direction columns)
- access config.relays=[{relay,direction,button?}]; reader/camera
config.controllerId+relay binding
- fresh 0000_baseline migration (history reset; dev data was throwaway)
Signed ledger:
- remove `lane` from canonicalize(); bump signer keyId sw-hmac-v1 -> v2
(v1 events won't verify under v2 — intentional, gated per-event by keyId)
Server:
- new device-resolve.ts (replaces lane-map.ts): relayForButton,
relayForDevice, firstRelayByDirection, devicesByDirection
- entry-flow: button terminal -> its relay; exit/permit: reader's bound
relay; dispatcher resolves the bound relay + inherited direction
- camera snapshots fire by direction site-wide, async, never block open
- DeviceConfig widened to nested JSON for relays[]
Web:
- wizard: no lane selector; add controllers (relay map + entry-button
terminal) first, then bind readers/cameras/printers to a controller relay
Wiki: new entry-exit-points.md (replaces lane-direction); reworked
entry-exit-readers, parking-session, first-run-setup, device-registry,
append-only-event-chain, device-events; removed stale lane/LaneMap mentions.
73 lines
3.9 KiB
Markdown
73 lines
3.9 KiB
Markdown
---
|
|
type: concept
|
|
tags: [parking, architecture, devices, setup]
|
|
sources: [parking-system-architecture]
|
|
updated: 2026-06-15
|
|
---
|
|
|
|
# Device Discovery
|
|
|
|
An optional driver capability: **find devices on the LAN** so the admin doesn't have to type
|
|
connection details by hand during [[first-run-setup]]. Modeled generically so any driver can
|
|
opt in.
|
|
|
|
> Implementation-derived (from `@parking/devices` + setup API/UI), not the source doc.
|
|
|
|
## The capability
|
|
|
|
A driver may implement `DiscoverableDriver` — `discover() => DiscoveredDevice[]`. Each found
|
|
device carries an `id`, a `label`, a `config` blob to **auto-fill** the setup form, and `info`
|
|
(firmware, MAC, …). The [[device-registry]]'s `isDiscoverable()` guard lets the system treat it
|
|
as optional; the setup catalog returns a `discoverable` list of driver ids.
|
|
|
|
> **No current driver implements discovery.** The [[dingtian-relay]] board uses a fixed IP
|
|
> (entered/known at setup). The capability remains for future UDP-discoverable devices (cameras
|
|
> via ONVIF, etc.). The worked example below is the (removed) UHPPOTE driver — kept because the
|
|
> **broadcast gotchas are transferable** to any UDP discovery we add later.
|
|
|
|
## UHPPOTE discovery (historical example)
|
|
|
|
The [[uhppote-controller]] supported discovery natively: a **UDP broadcast** (`get-devices` on
|
|
port `60000`) that **every controller on the LAN answers** with its serial, IP, netmask, gateway,
|
|
MAC, firmware version, and date. The `uhppoted` lib exposed this as `getDevices(ctx)`; the
|
|
(now-removed) `uhppote` driver mapped each result into a `DiscoveredDevice` (serial → id, IP →
|
|
host). **Was verified on real hardware** (serial 225088491).
|
|
|
|
### Broadcast gotchas (learned the hard way — see [[wsl-dev-networking]])
|
|
|
|
These cost real debugging time; the (removed) `uhppote` driver handled all three, and any future
|
|
UDP-discovery driver will need to as well:
|
|
|
|
1. **Broadcast to the *subnet-directed* address, not the global `255.255.255.255`.** The
|
|
`uhppoted` lib only calls `setBroadcast(true)` when the target matches a **local interface's
|
|
subnet broadcast** (e.g. `10.0.10.255`). For the global address it skips it, so the `send`
|
|
fails with **`EACCES`**. The driver computes the subnet broadcast from `os.networkInterfaces()`.
|
|
2. **A host with multiple interfaces must broadcast on *all* subnets.** With several NICs (LAN,
|
|
VPN/Tailscale, docker bridges) the controller is on only one. Picking the first interface
|
|
misses it; the driver broadcasts on every subnet and dedupes by serial.
|
|
3. **For *unicast* ops (status / open), the lib's `Config` broadcast must match the target's
|
|
subnet** — it governs reply routing, so a mismatched broadcast makes `getStatus` time out even
|
|
though `openDoor` "succeeds". The driver sets the broadcast per the target host's subnet. (This
|
|
was the health-check "offline/timeout" bug: a 5 s timeout dropped to 24 ms once fixed.)
|
|
|
|
Also: concurrent `uhppoted` calls collide on the `:60001` reply-listener port (EACCES / dropped
|
|
replies), so the driver **serializes** all controller I/O. Override the broadcast with
|
|
`UHPPOTE_BROADCAST` for unusual setups.
|
|
|
|
## Flow
|
|
|
|
1. The setup catalog flags `uhppote` as discoverable.
|
|
2. Admin clicks **Scan** → `GET /api/setup/discover/:driverId` (admin-only).
|
|
3. The server runs `discover()` and **health-checks each found device** so the admin sees
|
|
reachability before assigning.
|
|
4. Selecting a result **auto-fills serial + host**; the admin then assigns + binds it.
|
|
|
|
## Deployment notes
|
|
|
|
- Discovery is an **L2 broadcast**: the host and controller must share a layer-2 segment. Works
|
|
on the isolated device VLAN ([[network-isolation]]). A routed/NAT'd network (e.g. WSL2 NAT mode
|
|
— see [[wsl-dev-networking]]) blocks it entirely.
|
|
- Discovery shares the same unauthenticated UDP exposure as everything else UHPPOTE — another
|
|
reason the controllers live on an isolated VLAN ([[uhppote-udp-protocol]]).
|
|
- Cameras (Hikvision/Dahua via ONVIF/WS-Discovery) could implement the same interface later.
|