Files

T

julian dbf1fa17d7 wiki: document dev environment (WSL networking, workflow)

Capture hard-won dev knowledge that was only in commit messages:

- wsl-dev-networking: WSL2 NAT blocks UDP broadcast (device discovery can't
  reach the LAN); fix is mirrored networking (.wslconfig, Win11 22H2+), plus the
  gotchas that remained after — multiple interfaces, subnet-directed broadcast,
  localhost->IPv6 stall. Alternatives for non-mirrored setups.
- local-dev-workflow: first-time setup, pnpm dev, and the gotchas (the
  strip-types dev-server hang -> tsx, the 127.0.0.1 proxy fix, .env loading,
  seeding into the right DB).
- device-discovery: corrected the old "broadcast permission (EACCES)" note — the
  real cause was the lib not enabling SO_BROADCAST for global 255.255.255.255;
  documented the three verified broadcast gotchas + I/O serialization.
- schema: add a `reference` page type; new "Dev environment" index section; log.

Links lint clean; both new pages well-connected.

2026-06-14 13:09:35 +02:00

3.5 KiB

Raw Blame History

type, tags, sources, updated

type

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.

UHPPOTE discovery

The uhppote-controller supports 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 official uhppoted lib exposes this as getDevices(ctx); the uhppote driver maps each result into a DiscoveredDevice (serial → id, IP → host). Verified on real hardware (serial 225088491).

Broadcast gotchas (learned the hard way — see wsl-dev-networking)

These cost real debugging time; the uhppote driver now handles all three:

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().
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.
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

The setup catalog flags uhppote as discoverable.
Admin clicks Scan → GET /api/setup/discover/:driverId (admin-only).
The server runs discover() and health-checks each found device so the admin sees reachability before assigning.
Selecting a result auto-fills serial + host; the admin then assigns it to a lane.

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.

3.5 KiB Raw Blame History