feat(devices): radar presence input + button-light output on the controller

Model the entry button (I1) and a Hikvision radar (I2) as named children of the access controller, and drive the button's 12V lamp on a spare relay. - Radar = the existing relays[].presenceInput one-car-one-ticket gate, now labelled presenceKind: loop|radar. A radar may idle opposite the button, so add a per-input active-level override: relays[].presenceActiveLow -> driver inputActiveLow set, inverting just that terminal (pure helper inputActive()). The Dingtian has one board-wide resting level otherwise. - AuxOutputDevice.setAux(channel,on) capability on the device interface (Dingtian latch) so business logic drives a NON-barrier lamp through the interface. Barriers still only pulseOpen — barrier-not-a-door preserved. - ButtonLightController: subscribes to the radar input edge + the camera lane status and drives a 3-state lamp — radar+car=solid, radar-only=blink (~1Hz), else off. Fails OFF on host loss/error; de-duped. A radar detection never opens a barrier on its own (advisory; threat model). - SetupWizard: presence kind + active-low + a button-light relay picker; sq+en i18n. Tests: button-light.test.ts (truth table + blink + fail-OFF + de-dupe), access-dingtian.test.ts (active-level inversion). Workspace build+lint+test green (158 server tests). Wiki: hikvision-radar, button-light-indicator + updates. Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
2026-06-24 11:45:22 +02:00
parent 215a3ac405
commit 2915d141aa
17 changed files with 916 additions and 23 deletions
@@ -0,0 +1,194 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { randomUUID } from "node:crypto";
+import { devices, type Db } from "@parking/db";
+import { createTestDb } from "@parking/db/testing";
+import type { AuxOutputDevice } from "@parking/devices";
+import { ButtonLightController } from "./button-light.js";
+import { deviceEvents } from "./device-events.js";
+import { silentLogger } from "./test-helpers.js";
+
+// ButtonLightController: the entry-button lamp on a spare relay, driven by the RADAR
+// input vs. the camera lane status. Truth table:
+//   radar present + lane busy  -> SOLID on
+//   radar present + lane free   -> BLINK (~1 Hz)
+//   otherwise                   -> OFF
+// Lamp is a non-barrier aux output; fails OFF; de-dupes redundant writes.
+
+let db: Db;
+const CONTROLLER = "ctl-1";
+const RADAR_INPUT = 2; // I2
+const LAMP_RELAY = 3; // spare relay R3
+
+/** A fake aux device recording setAux calls (channel,on). Optionally throws. */
+function fakeAux(record: Array<{ ch: number; on: boolean }>, throwOnce = { v: false }): AuxOutputDevice {
+  return {
+    async setAux(channel: number, on: boolean): Promise<void> {
+      if (throwOnce.v) {
+        throwOnce.v = false;
+        throw new Error("UDP down");
+      }
+      record.push({ ch: channel, on });
+    },
+  };
+}
+
+beforeEach(() => {
+  ({ db } = createTestDb());
+  vi.useFakeTimers();
+  // One controller: entry relay 1 with radar on I2; lamp on spare relay 3.
+  db.insert(devices).values({
+    id: CONTROLLER,
+    category: "access",
+    driverId: "dingtian",
+    config: {
+      host: "10.0.0.5",
+      relays: [
+        { relay: 1, direction: "entry", button: 1, presenceInput: RADAR_INPUT, presenceKind: "radar" },
+        { relay: 2, direction: "exit" },
+      ],
+      buttonLight: { relay: LAMP_RELAY, blinkOnMs: 500, blinkOffMs: 500 },
+    },
+    enabled: true,
+  }).run();
+});
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+/** Emit a radar (presence input) edge for the controller. */
+function radar(present: boolean): void {
+  deviceEvents.emitInput({
+    driverId: "dingtian",
+    deviceId: CONTROLLER,
+    input: RADAR_INPUT,
+    edge: present ? "on" : "off",
+    at: new Date().toISOString(),
+    source: "poll",
+  });
+}
+
+/** Emit a lane status (entry busy/free). */
+function lane(entryBusy: boolean): void {
+  deviceEvents.emitLaneStatus({ entry: entryBusy, exit: false });
+}
+
+describe("ButtonLightController truth table", () => {
+  it("OFF at start (no radar, no car)", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const ctl = new ButtonLightController(db, silentLogger(), () => fakeAux(calls));
+    ctl.start();
+    expect(ctl.stateOf(CONTROLLER)).toBe("off");
+    // Initial apply drives the lamp off (false). It may de-dupe to no call since
+    // lastOn starts null -> false IS a change, so exactly one off write.
+    expect(calls).toEqual([{ ch: LAMP_RELAY, on: false }]);
+    ctl.stop();
+  });
+
+  it("radar present + lane busy -> SOLID on", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const aux = fakeAux(calls);
+    const ctl = new ButtonLightController(db, silentLogger(), () => aux);
+    ctl.start();
+    calls.length = 0;
+    lane(true);
+    radar(true);
+    expect(ctl.stateOf(CONTROLLER)).toBe("solid");
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: true });
+    // Solid = no blinking: advancing time produces no further toggles.
+    const n = calls.length;
+    vi.advanceTimersByTime(2000);
+    expect(calls.length).toBe(n);
+    ctl.stop();
+  });
+
+  it("radar present + lane free -> BLINK (toggles over time)", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const aux = fakeAux(calls);
+    const ctl = new ButtonLightController(db, silentLogger(), () => aux);
+    ctl.start();
+    calls.length = 0;
+    radar(true); // lane still free
+    expect(ctl.stateOf(CONTROLLER)).toBe("blink");
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: true }); // on now
+    vi.advanceTimersByTime(500);
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: false }); // toggled off
+    vi.advanceTimersByTime(500);
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: true }); // toggled on
+    ctl.stop();
+  });
+
+  it("blink -> solid when the camera confirms a car (lane busy)", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const aux = fakeAux(calls);
+    const ctl = new ButtonLightController(db, silentLogger(), () => aux);
+    ctl.start();
+    radar(true); // blink
+    expect(ctl.stateOf(CONTROLLER)).toBe("blink");
+    lane(true); // camera confirms
+    expect(ctl.stateOf(CONTROLLER)).toBe("solid");
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: true });
+    // No more toggles (blink torn down).
+    const n = calls.length;
+    vi.advanceTimersByTime(2000);
+    expect(calls.length).toBe(n);
+    ctl.stop();
+  });
+
+  it("radar clears -> OFF", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const aux = fakeAux(calls);
+    const ctl = new ButtonLightController(db, silentLogger(), () => aux);
+    ctl.start();
+    lane(true);
+    radar(true); // solid
+    calls.length = 0;
+    radar(false); // car gone
+    expect(ctl.stateOf(CONTROLLER)).toBe("off");
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: false });
+    ctl.stop();
+  });
+
+  it("de-dupes redundant writes (no spam on repeat events)", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const aux = fakeAux(calls);
+    const ctl = new ButtonLightController(db, silentLogger(), () => aux);
+    ctl.start();
+    lane(true);
+    radar(true); // solid, on
+    const n = calls.length;
+    radar(true); // same state — no new edge (present unchanged)
+    lane(true); // same lane — no change
+    expect(calls.length).toBe(n);
+    ctl.stop();
+  });
+
+  it("fails OFF: a setAux error does not throw or escalate", () => {
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const throwOnce = { v: true };
+    const aux = fakeAux(calls, throwOnce);
+    const ctl = new ButtonLightController(db, silentLogger(), () => aux);
+    // First write (initial off) throws — must be swallowed.
+    expect(() => ctl.start()).not.toThrow();
+    // Subsequent writes work; driving to solid still succeeds.
+    lane(true);
+    radar(true);
+    expect(calls.at(-1)).toEqual({ ch: LAMP_RELAY, on: true });
+    ctl.stop();
+  });
+
+  it("ignores controllers without a buttonLight config", () => {
+    // A second controller, no lamp.
+    db.insert(devices).values({
+      id: "ctl-2",
+      category: "access",
+      driverId: "dingtian",
+      config: { host: "10.0.0.6", relays: [{ relay: 1, direction: "entry", presenceInput: 2 }] },
+      enabled: true,
+    }).run();
+    const calls: Array<{ ch: number; on: boolean }> = [];
+    const ctl = new ButtonLightController(db, silentLogger(), () => fakeAux(calls));
+    ctl.start();
+    expect(ctl.stateOf("ctl-2")).toBeNull();
+    ctl.stop();
+  });
+});