Rongta 80mm printer: driver, role-based failover, live status monitoring

Add the rongta PrinterDevice driver (ESC/POS over raw TCP 9100) and the device-agnostic pieces around it: - Roles + failover: each printer declares a role (entry-dispenser/booth- receipt) and failoverRank; printer-routing.ts picks the best healthy printer and falls back outside->booth for entry tickets (never the reverse). - Live status: MonitorableDevice.readStatus()/PrinterStatus capability. The Rongta driver scrapes the device's own /prn_stat.htm (Cover/Cutter/Paper End/Near End/Off-Line) rather than hand-decoding DLE EOT, whose reply bytes on this clone don't match the canonical ESC/POS bit layout (verified on hardware) -- avoids a false-healthy. Maps to ready/degraded/offline, fail safe on an unreachable or unexpected page. - Server PrinterMonitor polls enabled printers (PRINTER_POLL_MS, default 5s), caches latest, emits "printer-status" on change. Exposed via GET /api/printers/status and an SSE stream for the booth UI. Verified against 10.0.10.6: ready when healthy, offline when unreachable (no throw), bus emits on change and suppresses unchanged reads. Wiki: new rongta-printer entity, printer-roles-failover and printer-status-monitoring concepts; BOM/index/log updated.
2026-06-14 20:26:45 +02:00
parent 2a86e578a8
commit b2a0471b08
15 changed files with 878 additions and 3 deletions
@@ -0,0 +1,53 @@
+---
+type: concept
+tags: [parking, printer, device, reliability]
+sources: []
+updated: 2026-06-14
+---
+
+# Printer roles & failover
+
+A lane runs **more than one printer**, and the system knows each one's job so it can fail over
+automatically. This is a reliability decision, not a threat-model one: an entry ticket must
+still print when the outside dispenser jams or drops off the network.
+
+## Roles
+
+Each printer instance (a `lane_devices` row, category `printer`) declares a **role** in its
+config:
+
+- **`entry-dispenser`** — outside, at the lane. Prints the entry ticket the driver takes.
+- **`booth-receipt`** — inside the booth. Prints receipts at exit/payment, AND serves as the
+  **backup** for entry tickets.
+
+It also declares a **`failoverRank`** (higher = preferred within a role) to order multiple
+printers of the same role deterministically (ties broken by id).
+
+## Failover rule (asymmetric, on purpose)
+
+For an **entry ticket** (`wantRole = entry-dispenser`): try the entry dispensers (best rank
+first), then fall back to the **booth printer**. So a driver still gets a ticket when the
+outside unit is offline — the operator hands it over from the booth.
+
+The reverse is **deliberately not** done: a **receipt** never prints on the outside dispenser.
+Receipts are a booth-only job; an entry dispenser falling back to print receipts makes no
+physical sense.
+
+## Where the logic lives
+
+- The driver (`rongta`) is **role-agnostic** — role/rank are just config; the transport doesn't
+  care. Keeps [[device-adapter-pattern|adapters]] swappable.
+- Selection is pure logic in `packages/devices/printer-routing.ts`: `orderForRole()` ranks
+  candidates; `printWithFailover()` attempts the print down the list and throws
+  `NoPrinterAvailableError` only when every candidate fails.
+- It **attempts the print directly** rather than racing a `healthCheck` first — the print is
+  the real reachability test, and a health probe that passes can still be followed by a failed
+  print.
+
+## Open: the all-printers-down policy
+
+When `printWithFailover` exhausts every candidate, what should entry do — raise the barrier
+with no paper ticket (the plate/[[lpr-camera]] is the independent record), or hold? That policy
+belongs to the **entry flow** ([[device-input-flow]], [[fail-state-safety]]), not the printer
+layer, and is **not yet decided**. The signed event ([[append-only-event-chain]]) is created
+regardless of whether paper prints.
@@ -0,0 +1,74 @@
+---
+type: concept
+tags: [parking, printer, device, monitoring, reliability]
+sources: []
+updated: 2026-06-14
+---
+
+# Printer status monitoring
+
+The booth must know a printer is in trouble **before** a driver presses the entry button and no
+ticket comes out. So the system polls each printer's live status (paper out, cover open, cutter
+jam, off-line) and pushes changes to the operator UI. A reliability control, like
+[[printer-roles-failover]] — not a threat-model one.
+
+## Where the status comes from (the safe-decode decision)
+
+The raw print socket (TCP 9100) is write-only for us — it returns no paper/cover feedback. ESC/POS
+printers expose status via real-time queries (`DLE EOT n`). On the [[rongta-printer]] clone we
+probed, **`DLE EOT` replies do NOT follow the canonical ESC/POS bit layout** (the spec's fixed
+validation bits were wrong, verified on hardware 2026-06-14). Decoding those bits ourselves risked
+a **false-healthy** — reporting "paper OK" when it's empty — which is the dangerous direction for
+an entry lane.
+
+Instead we scrape the device's **own status web page** (`http://<host>/prn_stat.htm`). The board
+decodes the bits itself into labelled Yes/No rows (Cover Is Open, Cutter Error, Paper End, Paper
+Near End, Printer Off-Line). We trust the device's decode over hand-decoding an undocumented clone.
+
+This is captured as a device capability: `MonitorableDevice.readStatus(): PrinterStatus` in
+`packages/devices`. The Rongta driver implements it; the monitor is device-agnostic via
+`isMonitorable()`. A future printer with a different status mechanism just implements the same
+interface.
+
+## Status mapping (fail safe)
+
+`readStatus()` maps to `ready | degraded | offline`:
+
+- status page unreachable / times out → **offline** (same signal as a dead printer; never throws),
+- page reachable but a recognised field is missing → **degraded** ("unexpected status page") —
+  we do NOT claim "ready" off a page we didn't fully parse,
+- any fault flag true (paper end, cover open, cutter error, off-line) → **degraded** + a detail
+  string ("paper out", …),
+- all five clear → **ready**.
+
+## The monitor (server)
+
+`PrinterMonitor` (`apps/server/src/printer-monitor.ts`):
+
+- reloads the monitored set from `lane_devices` each tick (so a newly-assigned printer is picked
+  up without a restart), keeping only enabled, monitorable printers;
+- polls every `PRINTER_POLL_MS` (default 5000ms), never overlapping ticks;
+- caches the latest status per device id;
+- emits a `printer-status` event on the device bus **only when status changes** (deduped).
+
+## API / live UI
+
+- `GET /api/printers/status` — cached snapshot of all printers (no device round-trip).
+- `GET /api/printers/status/stream` — **Server-Sent Events**: full snapshot on connect, then one
+  event per change. The booth SPA subscribes for real-time paper-out / offline indicators.
+- Any authenticated role may read (operational, not a setup action).
+
+## Verified on hardware (2026-06-14)
+
+`readStatus()` against 10.0.10.6 → `ready` (all flags false); against an unreachable host →
+`offline` with "status page timeout" (no throw); bus emits on change and suppresses unchanged
+reads. Full repo typechecks.
+
+## Open / not yet done
+
+- **Fault-state capture**: we've only observed the all-clear page. The exact label text for an
+  active fault (e.g. does "Paper End" flip to "Yes"?) should be confirmed by physically removing
+  paper / opening the cover, to be 100% sure the scrape catches it. The parser is built to match
+  Yes/No and degrade on anything unexpected, so this is a confidence check, not a blocker.
+- Tying a `degraded`/`offline` entry-dispenser into [[printer-roles-failover]] failover and the
+  (not-yet-built) entry flow's all-printers-down policy ([[device-input-flow]]).
@@ -17,8 +17,8 @@ payment terminal is dictated by the acquiring bank. (See [[parking-system-archit
 | 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 |
-| Booth printer | Epson TM / Citizen (USB or network) | ESC/POS; one adapter covers both transports |
+| Ticket dispenser | [[rongta-printer]] 80mm (entry-dispenser role) | ESC/POS over raw TCP 9100; driver written |
+| Booth printer | [[rongta-printer]] 80mm (booth-receipt role) | Receipts + backup for entry tickets ([[printer-roles-failover]]) |
 | Payment | Bank-certified P2PE standalone terminal + cash drawer | Keeps the app out of **PCI-DSS scope** |
 | Host machine | Fanless industrial PC + UPS + [[atecc608]] | Reliability, power-loss safety, offline signing |
 | Network | Managed VLAN switch, PoE+ | Isolate the open control protocol |
@@ -0,0 +1,48 @@
+---
+type: entity
+tags: [parking, hardware, printer, device]
+sources: []
+updated: 2026-06-14
+---
+
+# Rongta 80mm thermal printer
+
+The chosen ticket/receipt printer: a **Rongta RP-series 80mm network thermal printer** (and the
+many ESC/POS-compatible OEM clones that share its firmware). Driver `rongta` in
+`packages/devices` implements [[device-adapter-pattern|PrinterDevice]].
+
+## Transport & protocol
+
+- **ESC/POS over a raw TCP socket on port 9100** (the JetDirect/RAW convention). The driver
+  opens the socket, writes the ESC/POS byte stream, waits for flush, closes.
+- **No authentication** on the print socket — anyone who can reach port 9100 can print. Like
+  every other field device it must sit on the **isolated device VLAN** ([[network-isolation]]).
+  There is no real HTTP/control boundary on the device (same posture as [[dingtian-relay]]).
+- **Health check** is a TCP connect probe to 9100. The print socket exposes no status protocol
+  we rely on; the print itself is the real reachability test (failover attempts the print).
+- **Live status** comes from the device's own web page `http://<host>/prn_stat.htm` (port 80),
+  which decodes Cover Open / Cutter Error / Paper End / Paper Near End / Off-Line into Yes/No.
+  We scrape that rather than hand-decode `DLE EOT` — this clone's DLE EOT reply bytes do **not**
+  match the canonical ESC/POS bit layout (verified on hardware), so trusting the device's own
+  decode avoids a false-healthy. Implemented as `readStatus()`; see [[printer-status-monitoring]].
+
+## Deployment (this site)
+
+- First printer verified reachable at **10.0.10.6:9100** from the host (TCP connect OK,
+  2026-06-14).
+- **At least two printers**, by role — see [[printer-roles-failover]]:
+  - **entry-dispenser** — outside, at the lane; the driver takes the entry ticket.
+  - **booth-receipt** — inside the booth; receipts, AND the backup that prints the entry
+    ticket if the outside dispenser is offline.
+
+## Ticket rendering
+
+`printTicket(TicketData)` builds ESC/POS: `ESC @` init, centered/bold/double-size header,
+lane, ticket id, issued-at, feed + partial cut (`GS V B`). CP437/ASCII subset.
+
+## Status
+
+Driver written and compiles; entry-ticket layout is a first pass; live status monitoring is
+implemented and verified ([[printer-status-monitoring]]). The receipt/exit layout and the
+cash-drawer kick (ESC/POS `ESC p`) are **not yet implemented** — they arrive with the
+exit/payment flow. Replaces the generic "Epson TM / Citizen" booth-printer line in [[bom]].
@@ -7,7 +7,7 @@ updated: 2026-06-14
 # Index

 Content catalog for the wiki. Start at [[overview]]. Maintained on every ingest.
-Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
+Counts: 1 source · 15 entities · 12 concepts · 2 decision records.

 ## Overview & navigation
 - [[overview]] — the top-level synthesis and entry point.
@@ -39,6 +39,7 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
 - [[lpr-camera]] — edge-AI plate recognition; host-side casual-identity source.
 - [[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).
+- [[rongta-printer]] — ✅ CHOSEN 80mm thermal printer; ESC/POS over raw TCP 9100; driver written, one unit reachable at 10.0.10.6.
 - [[bom]] — reference bill of materials (barrier, loops, controller, readers, payment, host, network).

 ## Concepts — foundational forces
@@ -57,6 +58,8 @@ Counts: 1 source · 14 entities · 10 concepts · 2 decision records.
 - [[device-input-flow]] — button → device push → backend decides → relay; backend is source of truth.
 - [[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.
+- [[printer-roles-failover]] — ≥2 printers per lane by role; entry ticket falls back outside→booth.
+- [[printer-status-monitoring]] — live poll of paper/cover/cutter/offline via the device's status page; SSE to the booth UI.
 - [[trust-boundary]] — the core fork: network vs. device; auditable vs. unforgeable.
 - [[fail-state-safety]] — entry fails closed, exit fails open; manual override; watchdog.

@@ -205,3 +205,25 @@ config write, relay fire, and userset.cgi itself all return 200 unauthenticated
 inbound-auth setting (only session_en, which bricks the read API). So rotating the
 login is COSMETIC, not a boundary — the signed event log remains the real
 guarantee. Recorded in [[dingtian-relay]] (new Hardening section).
+
+## [2026-06-14] ingest | Rongta 80mm printer driver + printer roles/failover
+- Added `rongta` PrinterDevice driver (ESC/POS over raw TCP 9100); registered in registry.
+- Decision: ≥2 printers per lane by role (entry-dispenser outside, booth-receipt inside);
+  entry ticket fails over outside→booth (asymmetric — receipts never print outside).
+- Selection logic lives in packages/devices/printer-routing.ts (orderForRole, printWithFailover).
+- One unit verified reachable at 10.0.10.6:9100 from host (TCP connect OK).
+- New pages: [[rongta-printer]], [[printer-roles-failover]]. Updated [[bom]], [[index]].
+- Open: all-printers-down policy belongs to the (not-yet-built) entry flow, not the printer layer.
+
+## [2026-06-14] ingest | Live printer status monitoring
+- Added MonitorableDevice.readStatus()/PrinterStatus capability in packages/devices.
+- Rongta readStatus() scrapes the device's own /prn_stat.htm (Cover/Cutter/Paper End/Near End/
+  Off-Line) — chosen over hand-decoding DLE EOT because this clone's DLE EOT bytes don't match
+  the canonical ESC/POS bit layout (verified on hardware; risk of false-healthy).
+- Server PrinterMonitor: polls enabled monitorable printers (PRINTER_POLL_MS, default 5s),
+  caches latest, emits "printer-status" on change. API: GET /api/printers/status + SSE stream.
+- Verified live: 10.0.10.6 -> ready (all flags clear); unreachable host -> offline (no throw);
+  bus emits on change, suppresses unchanged. Full repo typechecks (8/8).
+- New page: [[printer-status-monitoring]]. Updated [[rongta-printer]], [[index]].
+- Open: capture the page's actual text for an ACTIVE fault (pull paper / open cover) to confirm
+  the Yes flip; wire degraded/offline into failover + entry-flow all-down policy.