Remove UHPPOTE/ZKTeco; Dingtian is the only access driver

Neither UHPPOTE nor ZKTeco is used — the Dingtian relay controller was chosen and verified. Remove their code and re-scope the wiki. Code: - delete access-uhppote.ts, uhppoted.d.ts, access.ts (zkteco/esp32-relay stubs), and the three uhppote-*.mjs hardware test scripts. - remove the `uhppoted` npm dependency from @parking/devices and @parking/server. - unregister uhppote/zkteco/esp32-relay from the driver registry; drop their exports. Catalog access drivers = dingtian only. Build green (5/5). - refresh now-stale example comments (registry/interfaces/setup/api) to use current examples; keep the two "UHPPOTE blocker" references that explain why the precondition capability exists. Wiki (kept pages, re-scoped): - uhppote-controller, zkteco-controller -> rejected/historical with callouts; uhppote-vs-esp32 -> historical (detection-vs-prevention lens still useful). - re-point all "current device" framing (standing-decisions, bom, overview, open-questions, device-registry, device-discovery, index) to dingtian-relay. - transferable concepts (network-isolation, event-log-ingestion, barrier-not-a- door, threat-model) untouched. Raw source immutable. Links lint clean.
2026-06-14 14:28:52 +02:00
parent 1b55e2034d
commit 355026dcf7
26 changed files with 106 additions and 711 deletions
@@ -20,17 +20,23 @@ device carries an `id`, a `label`, a `config` blob to **auto-fill** the setup fo
 (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
+> **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.

-The [[uhppote-controller]] supports discovery natively: a **UDP broadcast** (`get-devices` on
+## 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 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).
+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 `uhppote` driver now handles all three:
+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
@@ -38,7 +38,8 @@ driver; **no business-logic change** — this is the [[device-adapter-pattern]]
 - Config is **validated against the driver's declared fields** before persisting.
 - Selections persist in the `lane_devices` table and drive runtime adapter construction.
 - Drivers may optionally implement **[[device-discovery]]** (`discover()`), so the admin can scan
-  the LAN instead of typing connection details — UHPPOTE does this today.
+  the LAN instead of typing connection details — no current driver uses it (the UHPPOTE did,
+  before removal; the [[dingtian-relay]] uses a fixed IP).

 Cameras are modelled as **snapshot-on-event**: the host requests an image at entry/exit; it's
 stored and referenced from the signed event as an **independent record** — a fraud-control input
@@ -7,6 +7,11 @@ updated: 2026-06-14

 # UHPPOTE vs. Custom ESP32 — Detection vs. Prevention

+> **Historical comparison.** Neither is the current device — the [[uhppote-controller]] was
+> **rejected** (entry-flow blocker → [[dingtian-relay]] chosen) and the [[esp32-custom-controller]]
+> is **deferred**. Kept because the **detection-vs-prevention** framing on the [[trust-boundary]]
+> fork is a durable lens that applies to any access device.
+
 A head-to-head on the [[trust-boundary]] fork: the off-the-shelf [[uhppote-controller]] versus
 the [[esp32-custom-controller]]. (Synthesized from [[parking-system-architecture]] §6–7.)

@@ -23,9 +28,10 @@ the [[esp32-custom-controller]]. (Synthesized from [[parking-system-architecture

 ## Bottom line

- The UHPPOTE is the **current choice**: good enough as a detection/audit layer **when only the
-  host can reach it** (isolation) and every event lands in the [[append-only-event-chain]].
- The ESP32 is the **documented upgrade** when you need a control path that holds even against an
-  attacker on the wire. They're **mixable per lane**.
+- The UHPPOTE was the **detection-grade** option: good enough as a detection/audit layer **when
+  only the host can reach it** (isolation) and every event lands in the [[append-only-event-chain]]
+  — but it was rejected for the entry lane (the button blocker).
+- The ESP32 is the **prevention-grade** option when you need a control path that holds even against
+  an attacker on the wire. Deferred.
 - Both still rely on host-side integrity ([[append-only-event-chain]]) and external
  [[reconciliation]] as the ultimate anti-fraud control.
@@ -27,7 +27,7 @@ status: open
   later" currently leaves a disk failure as **total revenue-history loss**.
 6. **Secure-element integration.** Confirm [[atecc608]] wiring/usage on the host (event
   signing). The [[esp32-custom-controller]] command-authentication use is **deferred — not
-   being implemented for now** (access control stays on the [[uhppote-controller]] behind
+   being implemented for now** (access control is the [[dingtian-relay]] behind
   [[network-isolation]]); revisit only if prevention-grade device auth becomes a requirement.
 7. **JWT signing: symmetric vs. asymmetric key.** _(Raised by the commit security review, not the
   source doc.)_ Auth currently uses a symmetric HMAC secret (`@fastify/jwt`, see
@@ -19,10 +19,12 @@ The decisions treated as settled in the design notes. (See [[parking-system-arch
 - **Integrity:** append-only, hash-chained, [[atecc608]]-signed event log
  ([[append-only-event-chain]]); **[[reconciliation]] is the anti-fraud control**; encryption
  protects only at-rest (see [[threat-model]]).
- **Access control:** [[uhppote-controller]] for now, on an **isolated VLAN**
-  ([[network-isolation]]); event log used as a tamper-evident audit source with host-side index
-  tracking ([[event-log-ingestion]]). The [[esp32-custom-controller]] is the documented
-  prevention-grade upgrade path (the [[trust-boundary]] fork).
+- **Access control:** the **[[dingtian-relay]]** relay+input controller, on an **isolated VLAN**
+  ([[network-isolation]]). Chosen because its **inputs are decoupled from its relays**, enabling
+  host-in-the-loop ticket-first entry — the resolution to [[access-controller-button-flow]].
+  (The [[uhppote-controller]] and [[zkteco-controller]] were evaluated and **rejected** — kept as
+  historical record. The [[esp32-custom-controller]] remains the documented prevention-grade
+  alternative — the [[trust-boundary]] fork.)
 - **Readers:** prefer [[wiegand]]-into-controller for permit holders (autonomous); host-in-the-loop
  for [[lpr-camera|LPR]]/QR/pure-network readers; both can share a relay (see
  [[entry-exit-readers]]).
@@ -14,7 +14,7 @@ payment terminal is dictated by the acquiring bank. (See [[parking-system-archit
 | --- | --- | --- |
 | Barrier operator | Magnetic Autocontrol / FAAC / CAME / Nice | Owns physical safety in firmware ([[barrier-not-a-door]]) |
 | Induction loops | Feig / BEA / EMX | Safety + free-exit detection |
-| Access controller | [[uhppote-controller]] now → ZKTeco later | Reader + relay; **isolate the VLAN** ([[network-isolation]]) |
+| Access controller | [[dingtian-relay]] relay+input board | Decoupled inputs (host-in-the-loop); **isolate the VLAN** ([[network-isolation]]). ([[uhppote-controller]]/[[zkteco-controller]] rejected) |
 | Permit readers | Nedap/Kathrein UHF, or Mifare → [[wiegand]] | Hands-free, or autonomous offline decisions |
 | Casual identity | [[lpr-camera]] (Milesight, edge AI) | Plate = ticket + independent record |
 | Ticket dispenser | Custom VKP80 | Parking-grade thermal/ESC-POS |
@@ -1,33 +1,37 @@
 ---
 type: entity
-tags: [parking, hardware, access-control, current-choice]
+tags: [parking, hardware, access-control, rejected, historical]
 sources: [parking-system-architecture]
 updated: 2026-06-15
 ---

-# UHPPOTE Controller (current choice)
+# UHPPOTE Controller (rejected — historical)

-The starting access-control hardware: a **UHPPOTE Wiegand 26/34 network controller (4-door)** —
-a cheap reader-plus-relay frontend, acceptable **provided you understand its limits**. The plan
-is UHPPOTE now → ZKTeco later (see [[bom]]). (See [[parking-system-architecture]] §6.)
+> **❌ NOT USED. Replaced by the [[dingtian-relay]] controller** (and its driver/test code
+> removed). Kept as the record of *why* — its firmware-fixed push-button blocker
+> ([[access-controller-button-flow]]) is what drove the switch to a board with decoupled inputs.
+> The transferable lessons below (network isolation, append-only log ingestion, "a barrier is not
+> a door") still apply to any access device.

-> **⚠️ Entry-flow blocker (verified on hardware):** the push-button input **auto-opens the relay
-> in firmware** — there's no command to make it report-without-opening — so it **cannot** do
-> ticket-first entry (`button → print → open`). Fine as a host-**commanded relay** and for
-> [[wiegand]]/permit lanes, but **not** the button-driven entry lane as wired. Full detail and
-> options: [[access-controller-button-flow]].
+The original starting hardware: a **UHPPOTE Wiegand 26/34 network controller (4-door)** — a cheap
+reader-plus-relay frontend. (See [[parking-system-architecture]] §6.)
+
+> **⚠️ The fatal limit (verified on hardware):** the push-button input **auto-opens the relay in
+> firmware** — no command makes it report-without-opening — so it **cannot** do ticket-first entry
+> (`button → print → open`). This is *the* reason it was dropped: full detail and the resolution in
+> [[access-controller-button-flow]].
 >
-> **Verified working on the real unit** (serial 225088491, fw 09120): host-commanded `openDoor`
-> on doors 1 & 2 (physically actuated, `reason="remote open door"`); button presses captured live
-> (`reason="push button ok"`); [[device-discovery]] scan. Test scripts: `apps/server/scripts/`.
+> **What was verified on the real unit** (serial 225088491, fw 09120) before retiring it:
+> host-commanded `openDoor` on doors 1 & 2 (physically actuated, `reason="remote open door"`);
+> button presses captured live (`reason="push button ok"`); UDP-broadcast [[device-discovery]].
+> The driver, `uhppoted` dependency, and test scripts have since been removed from the codebase.

-> **Implementation:** integrated via the official **`uhppoted`** npm package (MIT, by the
-> `uhppoted` org — `github.com/uhppoted/uhppoted-lib-nodejs`), added to `@parking/devices` as the
-> `uhppote` access driver ([[device-registry]]). It exposes exactly the protocol commands this
-> design needs: `openDoor`, `getStatus`, and the event-log set (`getEvent`, `getEventIndex`,
-> `setEventIndex`, `recordSpecialEvents`) plus `setListener`/`listen` for auto-push — see
-> [[event-log-ingestion]]. Transport defaults to **UDP** (broadcast `…:60000`), with optional
-> per-call TCP on newer firmware. The driver also implements **[[device-discovery]]**
+> **Past implementation (removed):** was integrated via the official **`uhppoted`** npm package
+> (MIT — `github.com/uhppoted/uhppoted-lib-nodejs`) as the `uhppote` access driver. It exposed
+> exactly the protocol commands the design needs: `openDoor`, `getStatus`, and the event-log set
+> (`getEvent`, `getEventIndex`, `setEventIndex`, `recordSpecialEvents`) plus `setListener`/`listen`
+> for auto-push — see [[event-log-ingestion]]. Transport defaulted to **UDP** (broadcast `…:60000`),
+> with optional per-call TCP on newer firmware. The driver also implemented **[[device-discovery]]**
 > (`getDevices` broadcast) so the setup wizard can scan for controllers. Note: the lib pulls one
 > trivial extra dep (the npm `os` shim) and uses UDP broadcast, which needs socket broadcast
 > permission on the host.
@@ -1,20 +1,24 @@
 ---
 type: entity
-tags: [parking, hardware, access-control]
+tags: [parking, hardware, access-control, rejected, historical]
 sources: [parking-system-architecture]
 updated: 2026-06-15
 ---

-# ZKTeco Controller
+# ZKTeco Controller (rejected — historical)

-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).
+> **❌ NOT USED.** Was considered as the access controller; the **[[dingtian-relay]]** board was
+> chosen instead (decoupled inputs, already verified). The `zkteco` driver **stub** has been
+> **removed** from the codebase. Kept for the record of the comparison below.

-## Relevance to the entry-flow blocker
+A network access controller (C3 / inBio families), originally the documented "UHPPOTE now →
+ZKTeco later" upgrade in the [[bom]].
+
+## Why it was a contender (vs. UHPPOTE)

 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**:
+[[access-controller-button-flow]] blocker) — but it was **never verified on our hardware**, and the
+Dingtian solved the problem first with less effort:

 - 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
@@ -32,13 +32,13 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
 - [[logto-zitadel-oidc]] — OIDC providers ruled out by offline-first.

 ## Entities — hardware & devices
- [[uhppote-controller]] — current access controller; cheap, tamper-evident, open-UDP, fixed firmware.
+- [[uhppote-controller]] — ❌ rejected/historical; firmware auto-open blocker drove the switch to Dingtian.
 - [[esp32-custom-controller]] — prevention-grade upgrade; device-level auth.
 - [[atecc608]] — secure element; non-extractable signing key (host events + controller auth).
 - [[wiegand]] — reader standard feeding the controller directly (autonomous permit-holder path).
 - [[lpr-camera]] — edge-AI plate recognition; host-side casual-identity source.
- [[zkteco-controller]] — C3/inBio controller; aux-input path may enable host-in-the-loop (driver TBD).
- [[dingtian-relay]] — relay+input board; inputs decoupled from relays → solves the button blocker (driver TBD).
+- [[zkteco-controller]] — ❌ rejected/historical; aux-input path was a contender, not pursued.
+- [[dingtian-relay]] — ✅ CHOSEN access controller; decoupled inputs solve the button blocker (driver verified on hardware).
 - [[bom]] — reference bill of materials (barrier, loops, controller, readers, payment, host, network).

 ## Concepts — foundational forces
@@ -54,7 +54,7 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
 - [[device-adapter-pattern]] — business logic talks to interfaces; swap hardware → new adapter.
 - [[device-registry]] — catalog of selectable drivers per category (admin-configurable).
 - [[first-run-setup]] — admin assigns devices per lane from the catalog at install.
- [[device-discovery]] — optional driver capability to scan the LAN (UHPPOTE UDP broadcast).
+- [[device-discovery]] — optional driver capability to scan the LAN (no current driver uses it; UHPPOTE was the example).
 - [[barrier-not-a-door]] — never timed-close a barrier; safety lives in barrier firmware.
 - [[trust-boundary]] — the core fork: network vs. device; auditable vs. unforgeable.
 - [[fail-state-safety]] — entry fails closed, exit fails open; manual override; watchdog.
@@ -118,3 +118,16 @@ works. The [[access-controller-button-flow]] blocker is RESOLVED. Gotcha recorde
 (GET omits it) or the write silently no-ops. Added httpPort config field (port 8080 ≠
 default 80). Test script apps/server/scripts/dingtian-test.mjs. Next: input HTTP-push
 endpoint + wiring input→ticket→pulseOpen.
+
+## [2026-06-15] cleanup | Remove UHPPOTE/ZKTeco code; wiki → rejected/historical
+Neither UHPPOTE nor ZKTeco is used (Dingtian chosen). Removed their code:
+deleted access-uhppote.ts, uhppoted.d.ts, access.ts (zkteco/esp32 stubs), the
+three uhppote-*.mjs scripts; dropped the `uhppoted` npm dep from both packages;
+unregistered uhppote/zkteco/esp32-relay from the driver registry; updated example
+comments. Catalog access drivers now = dingtian only. Build green.
+Wiki: kept the pages but marked [[uhppote-controller]] + [[zkteco-controller]]
+rejected/historical, [[uhppote-vs-esp32]] historical; re-pointed all "current
+device" framing (standing-decisions, bom, overview, open-questions) to
+[[dingtian-relay]]; noted no current driver uses [[device-discovery]]. Transferable
+concepts (network-isolation, event-log-ingestion, barrier-not-a-door, threat-model)
+kept as-is. Links lint clean; raw source untouched (immutable).
@@ -29,11 +29,12 @@ deployed on-site at a parking facility. Two forces shape nearly every decision:
  rest ([[disk-os-hardening]]) defends a secondary threat.
 - **Devices** sit behind a [[device-adapter-pattern]] (swap hardware → new adapter only), with
  the [[barrier-not-a-door]] safety principle keeping physical safety in barrier-operator firmware.
- **Access control** hinges on the [[trust-boundary]] fork:
-  [[uhppote-vs-esp32|detection vs. prevention]]. Today: [[uhppote-controller]] behind
-  [[network-isolation]], its open [[uhppote-udp-protocol]] contained, its log made trustworthy by
-  [[event-log-ingestion]]. Upgrade path: the [[esp32-custom-controller]] with
-  [[challenge-response-auth]] and [[fail-state-safety]].
+- **Access control** today is the **[[dingtian-relay]]** relay+input controller behind
+  [[network-isolation]] — chosen because its inputs are **decoupled from its relays**, enabling
+  host-in-the-loop ticket-first entry (resolving [[access-controller-button-flow]]). The
+  [[uhppote-controller]] and [[zkteco-controller]] were evaluated and **rejected** (historical).
+  The deeper fork is still the [[trust-boundary]] ([[uhppote-vs-esp32|detection vs. prevention]]);
+  the [[esp32-custom-controller]] remains the prevention-grade alternative.
 - **Readers** split two ways ([[entry-exit-readers]]): permit holders via [[wiegand]]
  (autonomous), casual/transient via host-side [[lpr-camera]] / QR; both can share a relay.
 - A reference [[bom]] lists recommended devices.
@@ -47,6 +48,6 @@ modes (fail-open on exit)**, the **reconciliation channel**, and **backup/durabi

 - *Security-first:* [[threat-model]] → [[append-only-event-chain]] → [[reconciliation]] →
  [[uhppote-vs-esp32]].
- *Hardware-first:* [[bom]] → [[uhppote-controller]] → [[entry-exit-readers]] →
-  [[esp32-custom-controller]].
+- *Hardware-first:* [[bom]] → [[dingtian-relay]] → [[access-controller-button-flow]] →
+  [[entry-exit-readers]].
 - *Stack-first:* [[technology-stack]] → [[offline-first]] → [[device-adapter-pattern]].