mca/parking_solution
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

feat(vision): configurability — SetupWizard ANPR toggle, footer health chip, env docs

Browse Source 
Make the vision service genuinely configurable (was env-only).

- SetupWizard: an "ANPR" checkbox on the camera form (writes config.anpr; persisted
  only when on; sq+en) — opt-in is no longer raw JSON.
- DeviceMonitor optionally takes the VisionClient and probes /health each tick, emitting
  a "vision" pseudo-device → a Vision chip (ready/degraded/offline + recognizer) in the
  booth footer when VISION_ENABLED, no chip when off. Widened the DeviceStatus category
  union (server + web) + footer maps + devices.catVision. Verified: ready/fast_alpr when
  up, 0 chips when disabled.
- apps/vision/.env.example (Python service) + a VISION_* block in apps/server/.env.example
  (Node side) + a Configuration section in opencv-anpr-service.md covering all four
  layers and the caveats: the two processes share the VISION_ prefix but need SEPARATE
  .env files; bind /analyze to 127.0.0.1; cache model weights at deploy; an unbound anpr
  camera recognizes but every read is refused.

Build + lint green.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
This commit is contained in:
Julian Çuni
2026-06-19 16:41:29 +02:00
parent 540b333b06
commit 4af8b56dda
13 changed files with 168 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/server/.env.example
+12
View File
@@ -29,3 +29,15 @@ EVENT_SIGNING_KEY=
# Comma-separated extra origins allowed to open the booth WebSocket (/api/ws).
# In dev, set the Vite SPA origin. Same-origin is always allowed without this.
WS_ALLOWED_ORIGINS=http://localhost:5173
# Vision / ANPR (optional) -------------------------------------------------
# OFF by default. The Node SERVER's view of the vision microservice (apps/vision),
# which runs as a separate process with its OWN apps/vision/.env. Both sides share the
# VISION_ prefix but are different processes — keep the two .env files separate.
# See wiki/entities/opencv-anpr-service.md "Configuration".
# VISION_ENABLED=1 # master switch — nothing runs without it
# VISION_URL=http://127.0.0.1:8089 # must match apps/vision VISION_HOST:VISION_PORT
# VISION_TIMEOUT_MS=1500 # per-request cap so a slow call can't hang the lane
# VISION_POLL_MS=2000 # how often each anpr camera is polled
# VISION_DEDUPE_MS=15000 # suppress re-firing the same plate while a car sits in frame
# VISION_MIN_CONFIDENCE=0.5 # confidence floor; keep in sync with the service
apps/server/src/device-events.ts
+1 -1
View File
@@ -60,7 +60,7 @@ export interface PrinterStatusEvent {
export interface DeviceStatusEvent {
readonly deviceId: string; // devices id
readonly driverId: string;
readonly category: "access" | "reader" | "camera" | "printer";
readonly category: "access" | "reader" | "camera" | "printer" | "vision";
/**
* The device's ROLE descriptor for the footer label — NOT the vendor. A
* direction-style token the client localises and pairs with the category, so the
apps/server/src/device-monitor.ts
+41 -5
View File
@@ -3,6 +3,11 @@ import { devices, type Db, type DeviceRow } from "@parking/db";
import { isMonitorable, registry } from "@parking/devices";
import { deviceEvents, type DeviceStatusEvent } from "./device-events.js";
import { directionOf, relaysOf } from "./device-resolve.js";
import type { VisionClient } from "./vision-client.js";
/** Synthetic device id for the vision service in the status footer (it's a service,
* not a device row, but shares the footer's traffic-light + WS plumbing). */
const VISION_STATUS_ID = "vision-service";
// Unified live DEVICE monitor — the source for the booth's device-status footer.
// Every enabled, configured device is probed on an interval, regardless of
@@ -60,10 +65,15 @@ export class DeviceMonitor {
#timer: ReturnType<typeof setInterval> | null = null;
#ticking = false;
constructor(db: Db, log: FastifyBaseLogger, pollMs = POLL_MS) {
/** Optional: the vision service client. When present + enabled, the monitor probes
* its /health each tick and shows it as a "vision" chip in the footer. */
readonly #vision: VisionClient | null;
constructor(db: Db, log: FastifyBaseLogger, pollMs = POLL_MS, vision: VisionClient | null = null) {
this.#db = db;
this.#log = log;
this.#pollMs = pollMs;
this.#vision = vision;
}
/** Begin polling. Idempotent. */
@@ -97,12 +107,16 @@ export class DeviceMonitor {
const enabled = rows.filter((r) => r.enabled);
const present = new Set(enabled.map((r) => r.id));
// The vision service is a pseudo-device — keep it in the present set when enabled
// so the cleanup below doesn't evict it.
if (this.#vision?.enabled) present.add(VISION_STATUS_ID);
// Drop devices that are gone/disabled (so the footer doesn't show stale ones).
for (const id of [...this.#latest.keys()]) {
if (!present.has(id)) this.#latest.delete(id);
}
await Promise.all(enabled.map((r) => this.#poll(r)));
await Promise.all([...enabled.map((r) => this.#poll(r)), this.#pollVision()]);
} catch (err) {
this.#log.warn(`device-monitor tick failed: ${(err as Error).message}`);
} finally {
@@ -144,11 +158,33 @@ export class DeviceMonitor {
}
}
const prev = this.#latest.get(row.id);
this.#latest.set(row.id, next);
this.#publish(row.id, next);
}
/** Probe the vision service /health and publish it as a "vision" footer chip. Skipped
* entirely when no client is wired or it's disabled (no chip then). */
async #pollVision(): Promise<void> {
if (!this.#vision?.enabled) return;
const h = await this.#vision.health();
const state: DeviceStatusEvent["state"] = h.ok && h.ready ? "ready" : h.ready ? "degraded" : "offline";
this.#publish(VISION_STATUS_ID, {
deviceId: VISION_STATUS_ID,
driverId: "vision",
category: "vision",
roleKind: null,
state,
detail: h.ready ? h.recognizer : (h.detail ?? "not ready"),
checkedAt: new Date().toISOString(),
});
}
/** Cache + emit a status, but only when it CHANGED (state or detail). */
#publish(id: string, next: DeviceStatusEvent): void {
const prev = this.#latest.get(id);
this.#latest.set(id, next);
if (!prev || prev.state !== next.state || prev.detail !== next.detail) {
this.#log.info(
`device-monitor: ${next.category}/${next.roleKind ?? "—"} ${row.id} -> ${next.state}${next.detail ? ` (${next.detail})` : ""}`,
`device-monitor: ${next.category}/${next.roleKind ?? "—"} ${id} -> ${next.state}${next.detail ? ` (${next.detail})` : ""}`,
);
deviceEvents.emitDeviceStatus(next);
}
apps/server/src/server.ts
+9 -12
View File
@@ -112,11 +112,17 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
app.addHook("onReady", async () => printerMonitor.start());
app.addHook("onClose", async () => printerMonitor.stop());
// Vision (ANPR) client — built early so the device monitor can include the vision
// service's health in the footer. Opt-in (VISION_ENABLED) + fail-soft; advisory only.
// See wiki/entities/opencv-anpr-service.md.
const visionClient = new VisionClient(app.log);
if (visionClient.enabled) app.log.info("vision client enabled");
// Unified device-status monitor: polls EVERY configured device (relays/readers/
// cameras via healthCheck, printers via rich readStatus) and feeds the booth's
// device-status footer over the WS. Read-only — never drives a relay.
// cameras via healthCheck, printers via rich readStatus) PLUS the vision service's
// /health, and feeds the booth's device-status footer over the WS. Read-only.
// See wiki/concepts/device-status-monitoring.md.
const deviceMonitor = new DeviceMonitor(db, app.log);
const deviceMonitor = new DeviceMonitor(db, app.log, undefined, visionClient);
await deviceStatusRoutes(app, deviceMonitor);
app.addHook("onReady", async () => deviceMonitor.start());
app.addHook("onClose", async () => deviceMonitor.stop());
@@ -163,15 +169,6 @@ export async function buildServer(opts: BuildOptions = {}): Promise<FastifyInsta
});
app.addHook("onClose", async () => unsubscribeRead());
// Vision (ANPR) client: the adapter to the host vision microservice (apps/vision),
// talking localhost HTTP. ADVISORY ONLY + opt-in (VISION_ENABLED) + fail-soft — a
// plate read is an identity hint/evidence, never the sole authority to open a paid
// barrier. Constructed here and available for the (separate, not-yet-wired) read
// trigger that snapshots an opt-in camera and emits a plate read. See
// wiki/entities/opencv-anpr-service.md "Fitness for the entry/exit flows".
const visionClient = new VisionClient(app.log);
if (visionClient.enabled) app.log.info("vision client enabled");
// Vision READER: polls opt-in (config.anpr) cameras, recognizes a plate via the
// vision client, and emits a kind:"plate" read onto the SAME read bus a physical
// reader uses → the dispatcher routes it to the subscription/exit flow unchanged. A