Dingtian relay driver — resolves the ticket-first entry blocker

The Dingtian board's inputs are independent of its relays (configurable), so a button on an input can report to the host WITHOUT auto-firing a relay — solving the access-controller-button-flow blocker the UHPPOTE/ZKTeco couldn't. packages/devices: - access-dingtian.ts: `dingtian` access driver implementing AccessControlDevice (relay pulse/latch via UDP string protocol :60001), InputDevice (read inputs + poll-based press/release events, active-LOW), and the new PreconditionDevice. - PreconditionDevice capability on the interface: a device can report config it requires for parking and optionally fix it. Dingtian checks input_link_relay via the HTTP config API and can disable it. - httpPort config field — the web/config API port is separate from UDP control (this unit uses 8080, not the default 80). - Register dingtian; export driver objects from the package. Verified on real hardware (DT-R004 @ 10.0.10.172): status read, relay pulse, input events; disabled input_link_relay via the driver, then confirmed pressing inputs fires NO relay (0000) — host-in-the-loop entry works. Config-write gotcha recorded: config_set.cgi requires "command":"setconfig" injected after "status" (GET omits it) or the POST silently no-ops. apps/server/scripts/dingtian-test.mjs: status / watch / pulse hardware test. wiki: dingtian-relay verified; button-flow marked RESOLVED; index + log.
2026-06-14 14:15:00 +02:00
parent 4319fb86dc
commit 1b55e2034d
9 changed files with 573 additions and 13 deletions
@@ -1,17 +1,22 @@
 ---
 type: decision
-tags: [parking, hardware, access-control, blocker, open]
+tags: [parking, hardware, access-control, resolved]
 sources: [parking-system-architecture]
 updated: 2026-06-15
-status: open
+status: settled
 ---

-# Blocker: Push-Button → Auto-Open Defeats the Ticket-First Entry Flow
+# Push-Button → Auto-Open: the Ticket-First Entry Blocker (RESOLVED)

-> **Procurement-blocking finding (2026-06-15), from on-hardware testing.** The UHPPOTE and
-> ZKTeco access controllers **on hand** cannot, as wired/configured, deliver the required entry
-> flow. This blocks the entry lane and needs a hardware/wiring resolution before that lane ships.
-> Work paused here to focus on the business side. See [[entry-exit-readers]], [[trust-boundary]].
+> **✅ RESOLVED (2026-06-15) by the [[dingtian-relay]] controller.** Its inputs are decoupled from
+> its relays (`input_link_relay` configurable off — done & verified on hardware), so a button on an
+> input reports to the host **without** firing a relay. Host-in-the-loop entry
+> (`button → host → ticket → host opens relay`) now works. The original blocker (below) stands as
+> the record of why the UHPPOTE/ZKTeco units couldn't do it.
+>
+> **Original procurement-blocking finding (2026-06-15), from on-hardware testing:** the UHPPOTE and
+> ZKTeco controllers on hand could not, as wired/configured, deliver the required entry flow.
+> See [[entry-exit-readers]], [[trust-boundary]].

 ## The required flow

@@ -39,8 +39,33 @@ see [[dingtian-vs-mqtt]].
  IP `192.168.1.100`, UDP `60000` (binary) / `60001` (string).
 - Binary protocol (port 60000) adds optional **password** + multicast; bitmask relay/input maps.

-## Status
+## Driver & config API

-Protocol understood from the SDK; **driver + on-hardware test not built yet**. Next: a `dingtian`
-relay driver in [[device-registry]] (UDP control + status parse) and the input-push endpoint,
-with `input_link_relay` disabled on the device. Needs the device IP + LAN to test.
+The `dingtian` driver ([[device-registry]]) implements three capabilities:
+`AccessControlDevice` (relay pulse/latch over UDP), `InputDevice` (read inputs + poll-based
+press/release events ~50 ms), and `PreconditionDevice` (below). Config fields include a separate
+**`httpPort`** — the device's web/config API is on a configurable HTTP port (this unit: **8080**,
+not the default 80), distinct from the UDP control port 60001.
+
+### Precondition: input_link_relay must be OFF
+
+The driver reads the device's JSON config (`GET /api/v2/config.cgi`) and **checks
+`input_link_relay`**; if enabled it reports a fixable issue, and `fixPreconditions()` writes the
+correction (`POST /api/v2/config_set.cgi`) — setting the flag to 0 and clearing `on_action_on`,
+preserving everything else (network, etc.). This is the generic [[device-registry|precondition]]
+capability: the app doesn't own full device config (that's the vendor web UI), only the few
+settings our flow depends on.
+
+> **Write gotcha (cost real debugging):** the GET config payload **omits** a `"command"` field, but
+> the set endpoint **requires `"command":"setconfig"`** injected right after `"status"`. Without it
+> the POST returns/looks like success but silently does nothing (and the device may reset). With it,
+> POST returns `{"status":0}` and the change sticks. JSON node order must be preserved.
+
+## Status — VERIFIED on hardware (DT-R004, sw V3.1.5461A, 10.0.10.172)
+
+- ✅ status read (`0000:1111:4`), relay pulse, input press/release events (active-LOW, idle HIGH).
+- ✅ **`input_link_relay` disabled via the driver** → confirmed: pressing an input now reports the
+  event and **fires NO relay** (`0000` after presses). The [[access-controller-button-flow]] blocker
+  is **solved** — host-in-the-loop entry (`button → host → ticket → host opens relay`) works.
+- ⬜ Next: input HTTP-push endpoint (device `input_link_url` → backend), and wiring the entry flow
+  (input event → print ticket → `pulseOpen`). Polling works today; push is the lower-latency path.
@@ -74,6 +74,6 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
 ## Decisions
 - [[standing-decisions]] — settled decisions (stack, platform, integrity, access control, readers).
 - [[open-questions]] — 7 open items (6 procurement + JWT key choice); ESP32 device auth deferred.
- [[access-controller-button-flow]] — ⚠️ BLOCKER: UHPPOTE/ZKTeco on hand can't do ticket-first entry as wired.
+- [[access-controller-button-flow]] — ✅ RESOLVED: Dingtian decoupled inputs enable ticket-first entry (was a UHPPOTE/ZKTeco blocker).
 - [[autonomous-direction]] — roadmap: toward fully unmanned (no booth); reshapes threat model + fail-state.
 - [[dingtian-vs-mqtt]] — transport choice: direct HTTP/UDP now, MQTT parked until multi-lane scale.
@@ -105,3 +105,16 @@ this scale) but kept for later multi-lane scale. Recorded the stated roadmap to
 **fully unmanned, no-booth** operation in [[autonomous-direction]] and its threat-model
 shift (operator-fraud → unattended-machine threats). New stub [[dingtian-relay]]
 with the full protocol from the SDK. Driver + on-hardware test still to build.
+
+## [2026-06-15] driver+test | Dingtian driver built; button blocker RESOLVED
+Built the `dingtian` access driver (AccessControlDevice relay control + InputDevice
+poll-based button events + new PreconditionDevice capability). Verified end to end on
+real hardware (DT-R004 @ 10.0.10.172, HTTP config on :8080, UDP control :60001):
+status read, relay pulse, input press/release. Disabled `input_link_relay` via the
+driver's fixPreconditions (GET config → flag 0 + clear maps → POST config_set), then
+confirmed: pressing inputs now fires NO relay (0000 status) — host-in-the-loop entry
+works. The [[access-controller-button-flow]] blocker is RESOLVED. Gotcha recorded in
+[[dingtian-relay]]: config_set requires injecting "command":"setconfig" after "status"
+(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.