julian
77606da2c9
Brought up the real UHPPOTE controller (serial 225088491, fw 09120) end to end and recorded a procurement-level blocker. Verified on hardware: - discovery (LAN scan), host-commanded openDoor on doors 1 & 2 (physically actuated; reason="remote open door"), and live button capture (reason="push button ok"). Driver/networking fixes (packages/devices/src/drivers/access-uhppote.ts): - broadcast to subnet-directed address (lib doesn't enable SO_BROADCAST for the global 255.255.255.255 -> EACCES); - Config broadcast must match the target's subnet for unicast reply routing (fixes the health-check timeout: 5s -> 24ms ready); - discover across all local subnets, dedupe by serial; - serialize all controller I/O (concurrent calls collided on UDP :60001). Server/UX: - load .env via node --env-file-if-exists (vars weren't being read before); - SETUP_AUTH_BYPASS hardened: env-gated, dev + loopback only, fails closed otherwise; surfaced as catalog.authBypass so the wizard drops the token field; - .env.example documents all vars; inline favicon stops a 404. - apps/server/scripts/: uhppote-listen (live events, restores prior listener) and uhppote-relay (guarded door-open test). BLOCKER (wiki/decisions/access-controller-button-flow.md): the controller's push-button input auto-opens the relay in firmware with no report-without-open mode, so ticket-first entry (button -> print -> open, fail-closed) is impossible as wired. UHPPOTE can't do it on that input; ZKTeco *might* via a programmable aux input + PULL SDK but that's unverified and needs a new driver. Entry-lane hardware decision paused to focus on the business side. wiki: access-controller-button-flow (blocker), zkteco-controller (stub + assessment), uhppote-controller callout, index + log.
1.8 KiB
1.8 KiB
type, tags, sources, updated
| type | tags | sources | updated | ||||
|---|---|---|---|---|---|---|---|
| entity |
|
|
2026-06-15 |
ZKTeco Controller
A network access controller (C3 / inBio families) — the documented "UHPPOTE now → ZKTeco later"
upgrade in the bom. A zkteco driver stub exists in the device-registry but the
real protocol is not implemented (see below).
Relevance to the entry-flow blocker
ZKTeco is better positioned than the uhppote-controller for host-in-the-loop entry (the access-controller-button-flow blocker), but this is unverified on our hardware:
- Its auxiliary inputs have programmable linkage (ZKBioSecurity software / PULL SDK) and
are not hardwired to "open door" — so a button on an aux input can raise a host event
without auto-opening, enabling
button → host → print ticket → host opens. - The PULL SDK streams real-time events (
GetRTLog) and has an explicit open command (ControlDeviceOutput). - Caveat: a button on the door's exit-switch input still auto-opens (same as UHPPOTE) — only the aux-input path avoids it.
Driver status
- ZKTeco speaks its own PULL SDK / TCP protocol — not the UHPPOTE UDP protocol, so the
uhppotedlib does not work with it. - No verified MIT/Apache/BSD Node library found. Mature open implementations are Python
(
zkaccess-c3-py,pyzkaccess). Adopting ZKTeco means writing a new driver for the registry (device-adapter-pattern) — real protocol work.
Reference
- ZKTeco SDK / PULL SDK: https://www.zkteco.com/en/SDK
zkaccess-c3-py: https://github.com/vwout/zkaccess-c3-pypyzkaccess: https://github.com/bdragon300/pyzkaccess
See access-controller-button-flow for the full blocker context.