@ecopoesis/homebridge-dmx 0.1.0

package/src/color/rgbw.ts

@@ -0,0 +1,36 @@
+// rgbw — RGB + single White channel.
+// White component extracted as min(R,G,B); the colored channels get
+// (channel - white) so the total spectrum stays correct.
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  hsvToRgb01,
+  rgbBytes,
+  requireRoles,
+} from './types.js';
+
+export const rgbw: ColorModel = {
+  id: 'rgbw',
+  characteristics: ['On', 'Brightness', 'Hue', 'Saturation'],
+  validate(channels) {
+    requireRoles(channels, ['red', 'green', 'blue', 'white']);
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const rgb01 = hsvToRgb01(state.hue ?? 0, state.saturation ?? 0);
+    const px = rgbBytes(rgb01, state);
+    const w = Math.min(px.r, px.g, px.b);
+    const out = new Uint8Array(channels.length);
+    for (let i = 0; i < channels.length; i++) {
+      if (channels[i].fine) continue;
+      switch (channels[i].role) {
+        case 'red':   out[i] = px.r - w; break;
+        case 'green': out[i] = px.g - w; break;
+        case 'blue':  out[i] = px.b - w; break;
+        case 'white': out[i] = w; break;
+      }
+    }
+    return out;
+  },
+};

package/src/color/rgbww.ts

@@ -0,0 +1,56 @@
+// rgbww — RGB + WarmWhite + CoolWhite. The extracted white component
+// is split between WW and CW based on the HomeKit CCT (mireds), falling
+// back to 50/50 when CCT isn't set. WW channel optionally declares K=K
+// (e.g. "WarmWhite 2700") and CW does the same; if absent, defaults
+// 2700K (WW) / 6500K (CW) are used.
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  clamp,
+  hsvToRgb01,
+  rgbBytes,
+  requireRoles,
+} from './types.js';
+
+const DEFAULT_WW_K = 2700;
+const DEFAULT_CW_K = 6500;
+
+export const rgbww: ColorModel = {
+  id: 'rgbww',
+  characteristics: ['On', 'Brightness', 'Hue', 'Saturation', 'ColorTemperature'],
+  validate(channels) {
+    requireRoles(channels, ['red', 'green', 'blue', 'warm-white', 'cool-white']);
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const wwK = channels.find((c) => c.role === 'warm-white')?.kMin ?? DEFAULT_WW_K;
+    const cwK = channels.find((c) => c.role === 'cool-white')?.kMin ?? DEFAULT_CW_K;
+
+    const rgb01 = hsvToRgb01(state.hue ?? 0, state.saturation ?? 0);
+    const px = rgbBytes(rgb01, state);
+    const w = Math.min(px.r, px.g, px.b);
+
+    // Mix ratio: when CCT is at WW endpoint -> all WW; at CW endpoint -> all CW.
+    let warmFrac = 0.5;
+    if (state.colorTemperatureMireds != null && state.colorTemperatureMireds > 0) {
+      const k = 1_000_000 / state.colorTemperatureMireds;
+      warmFrac = clamp((cwK - k) / (cwK - wwK), 0, 1);
+    }
+    const ww = Math.round(w * warmFrac);
+    const cw = w - ww;
+
+    const out = new Uint8Array(channels.length);
+    for (let i = 0; i < channels.length; i++) {
+      if (channels[i].fine) continue;
+      switch (channels[i].role) {
+        case 'red':         out[i] = px.r - w; break;
+        case 'green':       out[i] = px.g - w; break;
+        case 'blue':        out[i] = px.b - w; break;
+        case 'warm-white':  out[i] = ww; break;
+        case 'cool-white':  out[i] = cw; break;
+      }
+    }
+    return out;
+  },
+};

package/src/color/types.ts

@@ -0,0 +1,150 @@
+// Color-model interfaces.
+//
+// A `ColorModel` translates the canonical HomeKit lightbulb state into the
+// byte values a fixture expects, given that fixture's `channel_order` from
+// the patch config. The optional `parse` is a placeholder for future
+// state-read support; not implemented in v1.
+
+export type HKCharacteristic =
+  | 'On'
+  | 'Brightness'
+  | 'Hue'
+  | 'Saturation'
+  | 'ColorTemperature';
+
+/** Canonical HomeKit state. Optional fields are populated only for models
+ *  that expose the corresponding characteristic. */
+export interface HomeKitLightState {
+  on: boolean;
+  brightness: number;              // 0..100 (percent)
+  hue?: number;                    // 0..360 (degrees)
+  saturation?: number;             // 0..100 (percent)
+  colorTemperatureMireds?: number; // 50..400 (HomeKit mired range)
+}
+
+export type ChannelRole =
+  | 'intensity'
+  | 'cct'
+  | 'saturation'
+  | 'hue'
+  | 'red'
+  | 'green'
+  | 'blue'
+  | 'white'
+  | 'warm-white'
+  | 'cool-white'
+  | 'amber';
+
+/** One entry from a profile's `channel_order`. Produced by `parseChannelName`.
+ *  `fine: true` means the byte at this slot is the low 8 bits of the 16-bit
+ *  value paired with the immediately preceding non-fine entry of the same role. */
+export interface ChannelDef {
+  role: ChannelRole;
+  fine?: boolean;
+  /** For CCT channels: Kelvin range. Required for CCT to mireds<->byte mapping. */
+  kMin?: number;
+  kMax?: number;
+}
+
+export interface ColorModel {
+  /** Lowercase identifier used in YAML/JSON config (`colormodel: hsvcct`). */
+  readonly id: string;
+  /** HomeKit characteristics this model wants on its fixture. */
+  readonly characteristics: HKCharacteristic[];
+  /** Throw if `channels` is inconsistent with this model's requirements. */
+  validate(channels: ChannelDef[]): void;
+  /** Produce a byte per `channels` entry, in order, given the HomeKit state. */
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array;
+  /** Optional reverse direction; not implemented in v1. */
+  parse?(bytes: Uint8Array, channels: ChannelDef[]): HomeKitLightState;
+}
+
+// ── shared helpers ─────────────────────────────────────────────────────────
+
+/** Map HomeKit brightness (0..100) to a 16-bit value (0..65535) honoring On. */
+export function brightness16(state: HomeKitLightState): number {
+  if (!state.on) return 0;
+  const pct = clamp(state.brightness, 0, 100);
+  return Math.round((pct / 100) * 65535);
+}
+
+/** Map HomeKit brightness (0..100) to an 8-bit value (0..255) honoring On. */
+export function brightness8(state: HomeKitLightState): number {
+  if (!state.on) return 0;
+  return Math.round((clamp(state.brightness, 0, 100) / 100) * 255);
+}
+
+/** Mireds → Kelvin → 0..255 byte across [kMin, kMax]. */
+export function ctByte(mireds: number | undefined, kMin: number, kMax: number): number {
+  if (mireds == null || mireds <= 0) return 128;
+  const k = 1_000_000 / mireds;
+  const t = (k - kMin) / (kMax - kMin);
+  return Math.round(clamp(t, 0, 1) * 255);
+}
+
+/** HSV → RGB at V=1 (the brightness is applied separately on top — same idiom
+ *  as unifi-ap-rgb so we don't double-darken). */
+export function hsvToRgb01(hueDeg: number, satPct: number): { r: number; g: number; b: number } {
+  const h = ((hueDeg % 360) + 360) % 360;
+  const s = clamp(satPct, 0, 100) / 100;
+  const c = s;                        // chroma when V = 1
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  let r1 = 0, g1 = 0, b1 = 0;
+  if (h < 60)        [r1, g1, b1] = [c, x, 0];
+  else if (h < 120)  [r1, g1, b1] = [x, c, 0];
+  else if (h < 180)  [r1, g1, b1] = [0, c, x];
+  else if (h < 240)  [r1, g1, b1] = [0, x, c];
+  else if (h < 300)  [r1, g1, b1] = [x, 0, c];
+  else               [r1, g1, b1] = [c, 0, x];
+  const m = 1 - c;                    // V - c with V = 1
+  return { r: r1 + m, g: g1 + m, b: b1 + m };
+}
+
+/** Scale 0..1 RGB by brightness (0..100) and on/off, return 0..255 bytes. */
+export function rgbBytes(rgb01: { r: number; g: number; b: number }, state: HomeKitLightState):
+  { r: number; g: number; b: number } {
+  const m = state.on ? clamp(state.brightness, 0, 100) / 100 : 0;
+  return {
+    r: Math.round(rgb01.r * m * 255),
+    g: Math.round(rgb01.g * m * 255),
+    b: Math.round(rgb01.b * m * 255),
+  };
+}
+
+export function clamp(v: number, lo: number, hi: number): number {
+  return v < lo ? lo : v > hi ? hi : v;
+}
+
+/** Tag a single-byte channel index plus its fine companion (if any), and
+ *  emit the right 16-bit split into `out`. Returns the index advanced past
+ *  any fine companion. */
+export function writeMaybe16(
+  out: Uint8Array,
+  channels: ChannelDef[],
+  i: number,
+  value16: number,
+): number {
+  const coarse = (value16 >> 8) & 0xff;
+  const fine = value16 & 0xff;
+  out[i] = coarse;
+  if (channels[i + 1]?.fine && channels[i + 1].role === channels[i].role) {
+    out[i + 1] = fine;
+    return i + 2;
+  }
+  return i + 1;
+}
+
+/** Validate that `roles` is exactly the set of (coarse) roles in `channels`. */
+export function requireRoles(channels: ChannelDef[], roles: ChannelRole[]): void {
+  const present = channels.filter((c) => !c.fine).map((c) => c.role);
+  for (const r of roles) {
+    if (!present.includes(r)) {
+      throw new Error(`channel_order missing required role '${r}'`);
+    }
+  }
+  for (const r of present) {
+    if (!roles.includes(r)) {
+      throw new Error(`channel_order has unexpected role '${r}' for this model`);
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,248 @@
+// Config loader + validator.
+//
+// Inputs:
+//   - Homebridge config: `platforms[].DMX` block from Homebridge's
+//     config.json. Optional `yamlPath` points to an external YAML file
+//     whose contents take precedence over the JSON.
+//   - YAML override: same shape as the JSON block.
+//
+// Shape:
+//   {
+//     "platform": "DMX",
+//     "name": "DMX",
+//     "yamlPath": "/optional/path/to/dmx.yaml",
+//     "controllers": [
+//       { "id": "main", "type": "StickDE3", "ip": "192.168.96.2" }
+//     ],
+//     "profiles": [
+//       { "name": "WAC", "colormodel": "hsvcct",
+//         "channel_order": ["Intensity", "Intensity (Fine)",
+//                           "ColorTemp 1650-8000", "Saturation", "Hue"] }
+//     ],
+//     "patch": [
+//       { "id": "a_down", "name": "A Down", "type": "WAC",
+//         "controller": "main", "universe": "A", "start": 6 }
+//     ]
+//   }
+//
+// Output: a normalized `LoadedConfig` the platform consumes. Validates:
+//   - controllers: unique ids, supported type, ip present
+//   - profiles: colormodel recognised, channel_order parses cleanly, model
+//     requirements satisfied
+//   - patch: unique ids, references a known profile + controller, valid
+//     universe ∈ {A,B}, start in [1, 512-nch+1], no slot overlap within a
+//     single (controller, universe).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+
+import { ChannelDef, ColorModel } from './color/types.js';
+import { getColorModel } from './color/index.js';
+import { parseChannelName } from './color/parsers.js';
+
+export interface ControllerSpec {
+  id: string;            // unique handle, referenced from patch entries
+  type: string;          // 'StickDE3' (only one supported today)
+  ip: string;            // controller's static IP
+}
+
+export interface ProfileSpec {
+  name: string;
+  colormodel: string;
+  channel_order: string[];
+}
+
+export interface PatchSpec {
+  id: string;            // unique handle (kebab-case)
+  name: string;          // human-friendly HomeKit name
+  type: string;          // profile name (refers to a ProfileSpec.name)
+  controller?: string;   // controller id; required if >1 controller configured
+  universe?: string;     // 'A' or 'B'; default 'A'
+  start: number;         // 1-based DMX start address
+}
+
+export interface RawConfig {
+  name?: string;
+  yamlPath?: string;
+  controllers?: ControllerSpec[];
+  profiles?: ProfileSpec[];
+  patch?: PatchSpec[];
+}
+
+export interface Profile {
+  name: string;
+  model: ColorModel;
+  channels: ChannelDef[];
+}
+
+export const CONTROLLER_TYPES = ['StickDE3'] as const;
+export type ControllerType = typeof CONTROLLER_TYPES[number];
+
+export interface Controller {
+  id: string;
+  type: ControllerType;
+  ip: string;
+}
+
+export interface Fixture {
+  id: string;
+  name: string;
+  profile: Profile;
+  controller: Controller;
+  universe: number;      // 0 (A) or 1 (B)
+  startCh: number;       // 1..512
+  nChannels: number;     // = channels.length
+}
+
+export interface LoadedConfig {
+  name: string;
+  controllers: Controller[];
+  fixtures: Fixture[];
+}
+
+export const DEFAULT_PLATFORM_NAME = 'DMX';
+
+/** Load + validate the platform config. `rawJson` is the Homebridge
+ *  `platforms[]` entry; if it specifies `yamlPath`, that YAML file is loaded
+ *  and treated as a full override of the JSON.
+ *
+ *  If `cwd` is passed, relative yamlPath is resolved against it. */
+export function loadConfig(rawJson: RawConfig, cwd?: string): LoadedConfig {
+  let raw: RawConfig = rawJson;
+  if (raw.yamlPath) {
+    const p = path.isAbsolute(raw.yamlPath) ? raw.yamlPath
+            : path.resolve(cwd ?? process.cwd(), raw.yamlPath);
+    const text = fs.readFileSync(p, 'utf8');
+    const parsed = yaml.load(text) as RawConfig;
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error(`yamlPath ${p}: not an object`);
+    }
+    raw = { ...rawJson, ...parsed };
+  }
+
+  // Controllers
+  const controllerSpecs = raw.controllers ?? [];
+  if (controllerSpecs.length === 0) {
+    throw new Error('config: at least one controller required under "controllers"');
+  }
+  const controllersById = new Map<string, Controller>();
+  for (const cs of controllerSpecs) {
+    if (!cs.id) throw new Error('controller: missing id');
+    if (controllersById.has(cs.id)) {
+      throw new Error(`controller: duplicate id "${cs.id}"`);
+    }
+    if (!CONTROLLER_TYPES.includes(cs.type as ControllerType)) {
+      throw new Error(
+        `controller "${cs.id}": unknown type "${cs.type}". ` +
+        `Supported: ${CONTROLLER_TYPES.join(', ')}`,
+      );
+    }
+    if (!cs.ip || typeof cs.ip !== 'string') {
+      throw new Error(`controller "${cs.id}": required field "ip" missing`);
+    }
+    controllersById.set(cs.id, { id: cs.id, type: cs.type as ControllerType, ip: cs.ip });
+  }
+
+  // Profiles
+  const profileSpecs = raw.profiles ?? [];
+  const profilesByName = new Map<string, Profile>();
+  for (const ps of profileSpecs) {
+    if (!ps.name) throw new Error('profile: missing name');
+    if (profilesByName.has(ps.name)) {
+      throw new Error(`profile: duplicate name "${ps.name}"`);
+    }
+    if (!Array.isArray(ps.channel_order) || ps.channel_order.length === 0) {
+      throw new Error(`profile "${ps.name}": channel_order must be a non-empty array`);
+    }
+    let model: ColorModel;
+    try { model = getColorModel(ps.colormodel); }
+    catch (e) { throw new Error(`profile "${ps.name}": ${(e as Error).message}`); }
+    let channels: ChannelDef[];
+    try { channels = ps.channel_order.map(parseChannelName); }
+    catch (e) { throw new Error(`profile "${ps.name}" channel_order: ${(e as Error).message}`); }
+    try { model.validate(channels); }
+    catch (e) { throw new Error(`profile "${ps.name}": ${(e as Error).message}`); }
+    profilesByName.set(ps.name, { name: ps.name, model, channels });
+  }
+
+  // Patch
+  const patchSpecs = raw.patch ?? [];
+  const fixtures: Fixture[] = [];
+  const seenIds = new Set<string>();
+  // Per controller + per universe: 512 channels, tracking which fixture
+  // owns each slot. Key is `${controllerId}:${universe}`.
+  const occupancy: Map<string, Map<number, string>> = new Map();
+  const slots = (cid: string, u: number): Map<number, string> => {
+    const key = `${cid}:${u}`;
+    let m = occupancy.get(key);
+    if (!m) { m = new Map(); occupancy.set(key, m); }
+    return m;
+  };
+
+  for (const ps of patchSpecs) {
+    if (!ps.id) throw new Error('patch: missing id');
+    if (seenIds.has(ps.id)) {
+      throw new Error(`patch: duplicate id "${ps.id}"`);
+    }
+    seenIds.add(ps.id);
+    const profile = profilesByName.get(ps.type);
+    if (!profile) {
+      throw new Error(`patch "${ps.id}": unknown profile "${ps.type}"`);
+    }
+    // controller reference. If only one controller is configured, default to it.
+    let controllerId = ps.controller;
+    if (!controllerId) {
+      if (controllersById.size === 1) {
+        controllerId = controllersById.keys().next().value as string;
+      } else {
+        throw new Error(
+          `patch "${ps.id}": "controller" required when more than one controller is configured`,
+        );
+      }
+    }
+    const controller = controllersById.get(controllerId);
+    if (!controller) {
+      throw new Error(`patch "${ps.id}": unknown controller "${controllerId}"`);
+    }
+    const universeChar = (ps.universe ?? 'A').toUpperCase();
+    if (universeChar !== 'A' && universeChar !== 'B') {
+      throw new Error(`patch "${ps.id}": universe must be 'A' or 'B', got "${ps.universe}"`);
+    }
+    const universe = universeChar === 'A' ? 0 : 1;
+    const nch = profile.channels.length;
+    const start = Number(ps.start);
+    if (!Number.isInteger(start) || start < 1 || start + nch - 1 > 512) {
+      throw new Error(
+        `patch "${ps.id}": start ${ps.start} + ${nch} channels does not fit in 1..512`,
+      );
+    }
+    const slotMap = slots(controllerId, universe);
+    for (let i = 0; i < nch; i++) {
+      const slot = start + i;
+      const owner = slotMap.get(slot);
+      if (owner) {
+        throw new Error(
+          `patch "${ps.id}": DMX slot ${slot}@${universeChar} ` +
+          `(controller "${controllerId}") overlaps with "${owner}"`,
+        );
+      }
+      slotMap.set(slot, ps.id);
+    }
+    fixtures.push({
+      id: ps.id,
+      name: ps.name || ps.id,
+      profile,
+      controller,
+      universe,
+      startCh: start,
+      nChannels: nch,
+    });
+  }
+
+  return {
+    name: raw.name ?? DEFAULT_PLATFORM_NAME,
+    controllers: [...controllersById.values()],
+    fixtures,
+  };
+}

package/src/controller.ts

@@ -0,0 +1,136 @@
+// StickController — single shared session manager for the platform.
+//
+// Behavior:
+//   - HomeKit calls setFixture(fixture, state) any number of times
+//   - The first call opens a StickSession and starts streaming at 25 Hz
+//   - Subsequent calls within DEBOUNCE_MS just update the targets and
+//     extend the streaming window
+//   - When DEBOUNCE_MS passes with no new calls, RST the session → latch
+//   - If a call arrives during teardown, immediately re-open and continue
+
+import type { Logger } from 'homebridge';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+import { Fixture } from './config.js';
+import { HomeKitLightState } from './color/types.js';
+import { DEBOUNCE_MS } from './settings.js';
+import { sleep } from './stick/protocol.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// dist/controller.js → ../tools/send_dmx.mjs
+const SEND_DMX_PATH = path.resolve(__dirname, '..', 'tools', 'send_dmx.mjs');
+
+export class StickController {
+  private targets = new Map<number, Uint8Array>();
+  private lastChangeAt = 0;
+  private streaming = false;
+  /** Tracks whether the very first subprocess in this controller's
+   *  lifetime should set RUN_PROBE=1. After a Stick power-cycle (which
+   *  we can't detect in-band) the probe is required to (re-)register
+   *  the client. Subsequent subprocesses can skip it. */
+  private needsProbe = true;
+
+  constructor(
+    private readonly ip: string,
+    private readonly log: Logger,
+    private readonly debounceMs: number = DEBOUNCE_MS,
+  ) {}
+
+  /** Stage a fixture's bytes into the universe target buffer and ensure
+   *  the streaming loop is running. */
+  setFixture(fixture: Fixture, state: HomeKitLightState): void {
+    const arr = this.universeBuf(fixture.universe);
+    const bytes = fixture.profile.model.render(state, fixture.profile.channels);
+    for (let i = 0; i < bytes.length; i++) {
+      arr[fixture.startCh - 1 + i] = bytes[i];
+    }
+    this.lastChangeAt = Date.now();
+    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
+    this.log.info(`setFixture ${fixture.id}@DMX${fixture.startCh}=${hex} streaming=${this.streaming}`);
+    if (!this.streaming) {
+      this.streaming = true;
+      this.run().catch((e) => {
+        this.log.error('streaming loop crashed:', (e as Error).message);
+      }).finally(() => {
+        this.streaming = false;
+      });
+    }
+  }
+
+  private universeBuf(u: number): Uint8Array {
+    let arr = this.targets.get(u);
+    if (!arr) { arr = new Uint8Array(512); this.targets.set(u, arr); }
+    return arr;
+  }
+
+  /** Build the CLI args from current targets. Only non-zero channels are
+   *  passed — send_dmx initialises the universe to 0 so omission == 0. */
+  private buildArgs(): string[] {
+    const args: string[] = [SEND_DMX_PATH, this.ip];
+    for (const [u, arr] of this.targets) {
+      for (let i = 0; i < 512; i++) {
+        if (arr[i] !== 0) args.push(`${u},${i + 1}=${arr[i]}`);
+      }
+    }
+    return args;
+  }
+
+  /** Subprocess approach: spawn tools/send_dmx.mjs for each transaction.
+   *  Fresh node process = no in-process state poisoning that breaks
+   *  session 2+ in the long-lived plugin. Costs ~1.5-3s per spawn (process
+   *  startup + handshake + 750ms stream + RST) but is empirically reliable. */
+  private async run(): Promise<void> {
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      // Wait for the debounce window to clear (no changes for debounceMs).
+      while (Date.now() - this.lastChangeAt < this.debounceMs) {
+        await sleep(50);
+      }
+
+      const runProbe = this.needsProbe;
+      const args = this.buildArgs();
+      const env = {
+        ...process.env,
+        STREAM_MS: '750',
+        SECTORS: '0',
+        ...(runProbe ? { RUN_PROBE: '1' } : {}),
+      };
+      this.log.info(`send_dmx subprocess: ${args.length - 2} channels` +
+                    (runProbe ? ' (with probe)' : ''));
+
+      const startedAt = Date.now();
+      let stderr = '';
+      const child = spawn('node', args, { env });
+      child.stdout.on('data', (d) => this.log.debug(`[send_dmx] ${d.toString().trimEnd()}`));
+      child.stderr.on('data', (d) => { stderr += d.toString(); });
+
+      const exitCode = await new Promise<number>((res) => {
+        child.on('exit', (code) => res(code ?? -1));
+        child.on('error', (e) => {
+          this.log.error('send_dmx spawn error:', e.message);
+          res(-1);
+        });
+      });
+      const elapsedMs = Date.now() - startedAt;
+
+      if (exitCode === 0) {
+        this.needsProbe = false;
+        this.log.info(`send_dmx done in ${elapsedMs}ms`);
+      } else {
+        this.log.error(`send_dmx exited ${exitCode} after ${elapsedMs}ms; stderr: ${stderr.slice(0, 200)}`);
+      }
+
+      // If a change arrived during the subprocess, run another transaction.
+      if (Date.now() - this.lastChangeAt < this.debounceMs) continue;
+      return;
+    }
+  }
+
+  /** Shutdown hook. Subprocess approach has no long-lived state. */
+  shutdown(): void {
+    /* no-op */
+  }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+// Homebridge plugin entry point.
+
+import type { API } from 'homebridge';
+import { PLATFORM_NAME } from './settings.js';
+import { DmxPlatform } from './platform.js';
+
+export default (api: API): void => {
+  api.registerPlatform(PLATFORM_NAME, DmxPlatform);
+};