@ecopoesis/homebridge-dmx 0.5.4 → 0.6.0

package/src/show/engine.ts

@@ -0,0 +1,280 @@
+// ShowEngine — runs at most one show at a time.
+//
+// Every frame (the involved controllers' fastest frame interval, 25 Hz on
+// sACN) the engine works out where each fixture is between the previous
+// step's look and the current one, renders it through the controller
+// (quietly — no per-frame logging) and moves on. The registry only hears
+// about it at step boundaries (throttled) and when the show stops, so
+// HomeKit tiles track the show without a 25 Hz event storm.
+//
+// Rules:
+//   - starting a show stops whichever one was running (its switch flips off)
+//   - the first fade starts from the fixtures' live registry state, so a
+//     show fades IN from whatever the lights were doing
+//   - stopping freezes the lights on the current frame and writes that
+//     frame to the registry (so tiles are accurate)
+//   - a HomeKit change to any fixture in the running show stops the show;
+//     the fixture that was touched keeps the user's new value
+
+import type { Logger } from 'homebridge';
+
+import { Fixture } from '../config.js';
+import { HomeKitLightState } from '../color/types.js';
+import { DmxController } from '../dmxController.js';
+import { StateRegistry } from '../stateRegistry.js';
+import { SHOW_FRAME_MS_DEFAULT, SHOW_KEYFRAME_MIN_MS } from '../settings.js';
+import { LookColor, mixLook } from './colors.js';
+import { Show } from './dsl.js';
+
+export type ShowListener = (runningId: string | null) => void;
+
+interface Run {
+  show: Show;
+  startedAt: number;
+  timer: NodeJS.Timeout;
+  /** Registry state of each fixture when the show started. */
+  snapshot: Map<string, LookColor>;
+  fixtures: Map<string, Fixture>;
+  frameMs: number;
+  /** The frame most recently put on the wire — what stop() freezes on. */
+  lastFrame: Map<string, LookColor> | null;
+  lastKeyframeStep: number;
+  lastKeyframeAt: number;
+}
+
+export class ShowEngine {
+  private run: Run | null = null;
+  private listeners = new Set<ShowListener>();
+  private lastEmitted: string | null = null;
+  private shows = new Map<string, Show>();
+
+  constructor(
+    shows: Show[],
+    private readonly controllers: Map<string, DmxController>,
+    private readonly registry: StateRegistry,
+    private readonly log: Logger,
+  ) {
+    for (const s of shows) this.shows.set(s.id, s);
+    // Any HomeKit change to a fixture in the running show ends the show.
+    registry.onChange((id, source) => {
+      if (source !== 'homekit' || !this.run) return;
+      if (this.run.fixtures.has(id)) {
+        this.stop(`"${id}" changed from HomeKit`, id);
+      }
+    });
+  }
+
+  running(): string | null {
+    return this.run?.show.id ?? null;
+  }
+
+  onChange(cb: ShowListener): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+
+  start(id: string): void {
+    const show = this.shows.get(id);
+    if (!show) { this.log.error(`show "${id}": unknown`); return; }
+    if (!show.runnable) {
+      this.log.error(`show "${id}": unbound params (${show.unboundParams.join(', ')})`);
+      return;
+    }
+    if (this.run?.show.id === id) return;
+    if (this.run) this.stopRun(`"${id}" starting`, undefined, false);
+
+    const snapshot = new Map<string, LookColor>();
+    for (const fx of show.fixtures) snapshot.set(fx.id, fromState(this.registry.get(fx.id)));
+
+    // One timer drives every involved controller, so tick at the SLOWEST
+    // frame interval among them: flooding the Stick with 25 Hz sets would
+    // keep resetting its debounce and it would never transact at all.
+    const frameMs = show.fixtures.reduce((max, fx) => {
+      const c = this.controllers.get(fx.controller.id);
+      return Math.max(max, c?.frameIntervalMs ?? SHOW_FRAME_MS_DEFAULT);
+    }, 0) || SHOW_FRAME_MS_DEFAULT;
+    const run: Run = {
+      show,
+      startedAt: Date.now(),
+      timer: setInterval(() => this.tick(), frameMs),
+      snapshot,
+      fixtures: new Map(show.fixtures.map((f) => [f.id, f])),
+      frameMs,
+      lastFrame: null,
+      lastKeyframeStep: -1,
+      lastKeyframeAt: 0,
+    };
+    run.timer.unref?.();
+    this.run = run;
+    this.log.info(
+      `show "${show.id}" started: ${show.steps.length} steps, ${show.fixtures.length} fixtures, ` +
+      `cycle ${(show.cycleMs / 1000).toFixed(1)} s, ${show.loop ? 'looping' : 'one-shot'}, ` +
+      `${frameMs} ms frames`,
+    );
+    this.tick();
+    this.emit();
+  }
+
+  /** Stop the running show, freezing the lights where they are: the
+   *  registry gets the last frame that actually went on the wire. `except`
+   *  names a fixture whose registry state must NOT be overwritten (it was
+   *  just set from HomeKit and is the reason we're stopping). */
+  stop(reason = 'switched off', except?: string): void {
+    this.stopRun(reason, except, true);
+  }
+
+  /** `notify: false` on a handoff inside start(): the switches hear one
+   *  transition (A → B) instead of A → nothing → B, which would bounce
+   *  the tapped tile off and back on. */
+  private stopRun(reason: string, except: string | undefined, notify: boolean): void {
+    const run = this.run;
+    if (!run) return;
+    clearInterval(run.timer);
+    this.run = null;
+    // Before the first tick nothing has been sent; after a one-shot's end
+    // the final look is on the wire (see applyFinal).
+    const frozen = run.lastFrame ?? run.show.steps[run.show.steps.length - 1].targets;
+    for (const [id, look] of frozen) {
+      if (id === except) continue;
+      this.registry.set(id, toState(look, this.fixture(run, id)), 'show');
+    }
+    this.log.info(`show "${run.show.id}" stopped (${reason})`);
+    if (notify) this.emit();
+  }
+
+  shutdown(): void {
+    if (this.run) { clearInterval(this.run.timer); this.run = null; }
+  }
+
+  /** Notify switches of the running show — only on an actual transition,
+   *  so the handoff inside start() (stop A, start B) doesn't bounce B's
+   *  tile off and back on. */
+  private emit(): void {
+    const id = this.running();
+    if (id === this.lastEmitted) return;
+    this.lastEmitted = id;
+    for (const l of this.listeners) l(id);
+  }
+
+  private fixture(run: Run, id: string): Fixture {
+    return run.fixtures.get(id)!;
+  }
+
+  private tick(): void {
+    const run = this.run;
+    if (!run) return;
+    const now = Date.now();
+    const frame = this.frameAt(run, now);
+    if (!frame) {
+      // One-shot show ran off the end: land on the final look and stop.
+      this.applyFinal(run);
+      return;
+    }
+    for (const [id, look] of frame.looks) {
+      const fx = this.fixture(run, id);
+      const c = this.controllers.get(fx.controller.id);
+      c?.setFixture(fx, toState(look, fx, true), { quiet: true });
+    }
+    run.lastFrame = frame.looks;
+    // Keyframe: on entering a new step, tell the registry where the lights
+    // are heading — the step's destination, not the in-between value, so
+    // a long fade shows its target for the whole fade. Throttled so fast
+    // chases don't flood HomeKit; on a sub-second chase the tiles lag by
+    // an unbounded amount, which is fine for a chase.
+    if (now - run.lastKeyframeAt >= SHOW_KEYFRAME_MIN_MS) {
+      run.lastKeyframeAt = now;
+      if (frame.step !== run.lastKeyframeStep) {
+        run.lastKeyframeStep = frame.step;
+        const targets = run.show.steps[frame.step].targets;
+        for (const [id, look] of targets) {
+          this.registry.set(id, toState(look, this.fixture(run, id)), 'show');
+        }
+      }
+    }
+  }
+
+  private applyFinal(run: Run): void {
+    clearInterval(run.timer);
+    this.run = null;   // before any registry write, same as stop()
+    const last = run.show.steps[run.show.steps.length - 1];
+    for (const [id, look] of last.targets) {
+      const fx = this.fixture(run, id);
+      this.controllers.get(fx.controller.id)?.setFixture(fx, toState(look, fx, true), { quiet: true });
+      this.registry.set(id, toState(look, fx), 'show');
+    }
+    this.log.info(`show "${run.show.id}" finished`);
+    this.emit();
+  }
+
+  /** Where every fixture is at wall-clock `now`. Null once a one-shot show
+   *  has run past its end. */
+  private frameAt(run: Run, now: number): { step: number; looks: Map<string, LookColor> } | null {
+    const { show, snapshot } = run;
+    let e = now - run.startedAt;
+    let firstCycle = true;
+    if (show.loop) {
+      if (e >= show.cycleMs) { firstCycle = false; e = e % show.cycleMs; }
+    } else if (e >= show.cycleMs) {
+      return null;
+    }
+    // Locate the step and the position within its fade/hold.
+    let i = 0;
+    let t = 1;
+    let acc = 0;
+    for (; i < show.steps.length; i++) {
+      const st = show.steps[i];
+      const len = st.fadeMs + st.holdMs;
+      if (e < acc + len || i === show.steps.length - 1) {
+        const local = e - acc;
+        t = st.fadeMs > 0 ? Math.min(1, local / st.fadeMs) : 1;
+        break;
+      }
+      acc += len;
+    }
+    const st = show.steps[i];
+    const from = i > 0 ? show.steps[i - 1].targets
+               : firstCycle ? null : show.steps[show.steps.length - 1].targets;
+    const eased = st.ease === 'sine' ? (1 - Math.cos(Math.PI * t)) / 2 : t;
+    const looks = new Map<string, LookColor>();
+    for (const fx of show.fixtures) {
+      const start = snapshot.get(fx.id)!;
+      const a = from?.get(fx.id) ?? start;
+      const b = st.targets.get(fx.id) ?? start;
+      looks.set(fx.id, mixLook(a, b, eased));
+    }
+    return { step: i, looks };
+  }
+}
+
+// ── LookColor ↔ HomeKitLightState ──────────────────────────────────────────
+
+export function fromState(s: HomeKitLightState): LookColor {
+  const out: LookColor = { brightness: s.on ? s.brightness : 0 };
+  if (s.hue != null) out.hue = s.hue;
+  if (s.saturation != null) out.saturation = s.saturation;
+  if (s.colorTemperatureMireds != null) out.mireds = s.colorTemperatureMireds;
+  return out;
+}
+
+/** Shape a look for a specific fixture: only the characteristics its color
+ *  model exposes, HomeKit-style on/brightness. A dark look parks the
+ *  brightness at 100 so the next HomeKit "on" restores full (mirrors
+ *  hsvcct.parse). `precise` keeps fractional values — the wire path
+ *  renders 16-bit intensity, so fades stay smooth below 1 % steps; the
+ *  registry (HomeKit) gets integers. */
+export function toState(look: LookColor, fx: Fixture, precise = false): HomeKitLightState {
+  const chars = fx.profile.model.characteristics;
+  const r = precise ? (n: number): number => n : Math.round;
+  const on = look.brightness > 0.5;
+  const s: HomeKitLightState = {
+    on,
+    brightness: on ? Math.max(1, r(look.brightness)) : 100,
+  };
+  const colorMode = look.hue != null && (look.saturation ?? 0) > 0;
+  if (chars.includes('Hue') && look.hue != null) s.hue = r(look.hue);
+  if (chars.includes('Saturation')) s.saturation = r(look.saturation ?? 0);
+  if (chars.includes('ColorTemperature') && look.mireds != null && !colorMode) {
+    s.colorTemperatureMireds = r(look.mireds);
+  }
+  return s;
+}

package/src/showAccessory.ts

@@ -0,0 +1,46 @@
+// ShowSwitch — one HomeKit Switch per runnable show.
+//
+// On  → engine.start(id): whatever show was running stops (its own switch
+//       flips off through the engine's change listener).
+// Off → engine.stop(): lights freeze on the current frame.
+// The switch also flips off by itself when a one-shot show finishes or a
+// user touches one of the show's lights.
+
+import type { PlatformAccessory, Service } from 'homebridge';
+
+import type { DmxPlatform } from './platform.js';
+import { Show } from './show/dsl.js';
+import { ShowEngine } from './show/engine.js';
+
+export class ShowSwitch {
+  private sw: Service;
+
+  constructor(
+    platform: DmxPlatform,
+    accessory: PlatformAccessory,
+    show: Show,
+    engine: ShowEngine,
+  ) {
+    const C = platform.Characteristic;
+    const info = accessory.getService(platform.Service.AccessoryInformation);
+    info?.setCharacteristic(C.Manufacturer, 'DMX')
+        ?.setCharacteristic(C.Model, `Show (${show.steps.length} steps, ${show.fixtures.length} fixtures)`)
+        ?.setCharacteristic(C.SerialNumber, `show-${show.id}`);
+
+    this.sw =
+      accessory.getService(platform.Service.Switch)
+      ?? accessory.addService(platform.Service.Switch, show.name);
+    this.sw.setCharacteristic(C.Name, show.name);
+
+    this.sw.getCharacteristic(C.On)
+      .onGet(() => engine.running() === show.id)
+      .onSet((v) => {
+        if (v) engine.start(show.id);
+        else if (engine.running() === show.id) engine.stop();
+      });
+
+    engine.onChange((runningId) => {
+      this.sw.updateCharacteristic(C.On, runningId === show.id);
+    });
+  }
+}

package/src/stateRegistry.ts

@@ -13,7 +13,13 @@
 
 import { HomeKitLightState } from './color/types.js';
 
-export type StateChangeListener = (fixtureId: string) => void;
+/** Who made a change. Accessories write as 'homekit' (the default);
+ *  the gateway read-back writes 'sync'; the show engine writes 'show'.
+ *  The engine uses this to end a show when a user touches one of its
+ *  lights without reacting to its own keyframes or to read-back. */
+export type StateSource = 'homekit' | 'sync' | 'show';
+
+export type StateChangeListener = (fixtureId: string, source: StateSource) => void;
 
 const DEFAULT_STATE: HomeKitLightState = { on: false, brightness: 100 };
 
@@ -26,16 +32,16 @@ export class StateRegistry {
   }
 
   /** Replace a fixture's state and fire change listeners. */
-  set(id: string, state: HomeKitLightState): void {
+  set(id: string, state: HomeKitLightState, source: StateSource = 'homekit'): void {
     this.states.set(id, { ...state });
-    for (const l of this.listeners) l(id);
+    for (const l of this.listeners) l(id, source);
   }
 
   /** Merge a partial update into a fixture's state, returning the new full
    *  state. Fires listeners. */
-  update(id: string, patch: Partial<HomeKitLightState>): HomeKitLightState {
+  update(id: string, patch: Partial<HomeKitLightState>, source: StateSource = 'homekit'): HomeKitLightState {
     const next: HomeKitLightState = { ...this.get(id), ...patch };
-    this.set(id, next);
+    this.set(id, next, source);
     return next;
   }
 

package/src/zoneAccessory.ts

@@ -22,7 +22,7 @@ import type {
 } from 'homebridge';
 
 import { Fixture, Zone } from './config.js';
-import { HKCharacteristic, HomeKitLightState } from './color/types.js';
+import { HKCharacteristic, HomeKitLightState, miredsToHueSat } from './color/types.js';
 import { DmxController } from './dmxController.js';
 import type { DmxPlatform } from './platform.js';
 import { CHARACTERISTIC_UPDATE_DELAY_MS } from './settings.js';
@@ -65,17 +65,17 @@ export class ZoneFixture {
     }
     if (has('Hue')) {
       this.bulb.getCharacteristic(C.Hue)
-        .onGet(() => this.majorityState().hue ?? 0)
+        .onGet(() => this.display().hue)
         .onSet((v) => this.applyToMembers({ hue: Number(v) }));
     }
     if (has('Saturation')) {
       this.bulb.getCharacteristic(C.Saturation)
-        .onGet(() => this.majorityState().saturation ?? 0)
+        .onGet(() => this.display().saturation)
         .onSet((v) => this.applyToMembers({ saturation: Number(v) }));
     }
     if (has('ColorTemperature')) {
       this.bulb.getCharacteristic(C.ColorTemperature)
-        .onGet(() => this.majorityState().colorTemperatureMireds ?? 200)
+        .onGet(() => this.display().ct)
         .onSet((v) => this.applyToMembers({
           colorTemperatureMireds: Number(v),
           saturation: 0,
@@ -101,6 +101,25 @@ export class ZoneFixture {
     };
   }
 
+  /** HomeKit-facing view of the majority state — same dual-mode display
+   *  convention as StickFixture.display() (HAP-NodeJS#618). */
+  private display(): { hue: number; saturation: number; ct: number; whiteMode: boolean } {
+    const s = this.majorityState();
+    if (!this.zone.characteristics.includes('ColorTemperature')
+        || !this.zone.characteristics.includes('Hue')) {
+      return { hue: s.hue ?? 0, saturation: s.saturation ?? 0,
+               ct: s.colorTemperatureMireds ?? 200, whiteMode: (s.saturation ?? 0) === 0 };
+    }
+    if ((s.saturation ?? 0) === 0) {
+      const ct = s.colorTemperatureMireds ?? 200;
+      const rep = miredsToHueSat(ct);
+      return { hue: rep.hue, saturation: rep.saturation, ct, whiteMode: true };
+    }
+    const ctChar = this.bulb.getCharacteristic(this.platform.Characteristic.ColorTemperature);
+    const minCt = (ctChar.props.minValue as number | undefined) ?? 140;
+    return { hue: s.hue ?? 0, saturation: s.saturation!, ct: minCt, whiteMode: false };
+  }
+
   /** A HomeKit set on the zone: build the new state from the current
    *  majority + the patch the user is applying, write it into every
    *  member, and trigger the controller after a small debounce so
@@ -154,23 +173,26 @@ export class ZoneFixture {
     this.refreshPending = setTimeout(() => {
       this.refreshPending = null;
       const s = this.majorityState();
+      const d = this.display();
       const C = this.platform.Characteristic;
       this.bulb.updateCharacteristic(C.On, s.on);
       if (this.zone.characteristics.includes('Brightness')) {
         this.bulb.updateCharacteristic(C.Brightness, s.brightness);
       }
-      if (this.zone.characteristics.includes('Hue') && s.hue != null) {
-        this.bulb.updateCharacteristic(C.Hue, s.hue);
+      if (this.zone.characteristics.includes('Hue')) {
+        this.bulb.updateCharacteristic(C.Hue, d.hue);
       }
-      if (this.zone.characteristics.includes('Saturation') && s.saturation != null) {
-        this.bulb.updateCharacteristic(C.Saturation, s.saturation);
+      if (this.zone.characteristics.includes('Saturation')) {
+        this.bulb.updateCharacteristic(C.Saturation, d.saturation);
       }
-      // Same rule as StickFixture.pushFromRegistry: the Home app displays
-      // whichever mode updated last, so only push ColorTemperature when the
-      // zone majority is actually in white mode (sat 0).
-      if (this.zone.characteristics.includes('ColorTemperature') && s.colorTemperatureMireds != null
-          && (s.saturation ?? 0) === 0) {
-        this.bulb.updateCharacteristic(C.ColorTemperature, s.colorTemperatureMireds);
+      if (this.zone.characteristics.includes('ColorTemperature')) {
+        if (d.whiteMode) {
+          // Real CCT, pushed last so temperature wins the display-mode race.
+          this.bulb.updateCharacteristic(C.ColorTemperature, d.ct);
+        } else {
+          // Park CT at min silently (see StickFixture.pushFromRegistry).
+          this.bulb.getCharacteristic(C.ColorTemperature).value = d.ct;
+        }
       }
     }, CHARACTERISTIC_UPDATE_DELAY_MS);
   }