@ecopoesis/homebridge-dmx 0.1.0

package/src/platform.ts

@@ -0,0 +1,118 @@
+// DmxPlatform — Homebridge DynamicPlatformPlugin entry.
+//
+// Loads the config, instantiates one StickController per controller spec,
+// creates one Lightbulb accessory per patch entry, wires each accessory to
+// its controller.
+
+import type {
+  API,
+  Characteristic,
+  DynamicPlatformPlugin,
+  Logger,
+  PlatformAccessory,
+  PlatformConfig,
+  Service,
+} from 'homebridge';
+
+import { Controller, LoadedConfig, loadConfig, RawConfig } from './config.js';
+import { StickController } from './controller.js';
+import { StickFixture } from './platformAccessory.js';
+import { PLATFORM_NAME, PLUGIN_NAME } from './settings.js';
+
+export class DmxPlatform implements DynamicPlatformPlugin {
+  public readonly Service: typeof Service;
+  public readonly Characteristic: typeof Characteristic;
+  public readonly accessories: PlatformAccessory[] = [];
+
+  private cfg: LoadedConfig | null = null;
+  private controllers = new Map<string, StickController>();
+
+  constructor(
+    public readonly log: Logger,
+    public readonly config: PlatformConfig,
+    public readonly api: API,
+  ) {
+    this.Service = api.hap.Service;
+    this.Characteristic = api.hap.Characteristic;
+
+    try {
+      this.cfg = loadConfig(
+        config as unknown as RawConfig,
+        api.user?.storagePath?.() ?? process.cwd(),
+      );
+    } catch (e) {
+      this.log.error('config error:', (e as Error).message);
+      return;
+    }
+
+    for (const c of this.cfg.controllers) {
+      this.controllers.set(c.id, this.makeController(c));
+    }
+
+    this.log.info(
+      `DMX platform configured: ${this.cfg.controllers.length} controller` +
+      `${this.cfg.controllers.length === 1 ? '' : 's'}, ` +
+      `${this.cfg.fixtures.length} fixture${this.cfg.fixtures.length === 1 ? '' : 's'}`,
+    );
+
+    this.api.on('didFinishLaunching', () => this.discoverDevices());
+    this.api.on('shutdown', () => {
+      for (const c of this.controllers.values()) c.shutdown();
+    });
+  }
+
+  private makeController(c: Controller): StickController {
+    switch (c.type) {
+      case 'StickDE3':
+        return new StickController(c.ip, this.log);
+      default:
+        throw new Error(`unsupported controller type "${(c as Controller).type}"`);
+    }
+  }
+
+  /** Called by Homebridge for each cached accessory at startup. */
+  configureAccessory(accessory: PlatformAccessory): void {
+    this.log.debug(`restoring cached accessory: ${accessory.displayName}`);
+    this.accessories.push(accessory);
+  }
+
+  private discoverDevices(): void {
+    if (!this.cfg) return;
+
+    const wantUuids = new Set<string>();
+    for (const fx of this.cfg.fixtures) {
+      const uuid = this.api.hap.uuid.generate(`dmx:${fx.controller.id}:${fx.id}`);
+      wantUuids.add(uuid);
+
+      const controller = this.controllers.get(fx.controller.id);
+      if (!controller) {
+        this.log.error(`fixture "${fx.id}": no controller "${fx.controller.id}"`);
+        continue;
+      }
+
+      const existing = this.accessories.find((a) => a.UUID === uuid);
+      if (existing) {
+        this.log.debug(`wiring cached accessory ${fx.id}`);
+        existing.context.fixture = { id: fx.id, controllerId: fx.controller.id };
+        new StickFixture(this, existing, fx, controller);
+      } else {
+        this.log.info(`registering new accessory: ${fx.name} (${fx.id})`);
+        const accessory = new this.api.platformAccessory(fx.name, uuid);
+        accessory.context.fixture = { id: fx.id, controllerId: fx.controller.id };
+        new StickFixture(this, accessory, fx, controller);
+        this.api.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, [accessory]);
+        this.accessories.push(accessory);
+      }
+    }
+
+    const stale = this.accessories.filter((a) => !wantUuids.has(a.UUID));
+    if (stale.length) {
+      this.log.info(`unregistering ${stale.length} stale accessor${stale.length === 1 ? 'y' : 'ies'}`);
+      this.api.unregisterPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, stale);
+      for (const a of stale) {
+        const i = this.accessories.indexOf(a);
+        if (i >= 0) this.accessories.splice(i, 1);
+      }
+    }
+  }
+}

package/src/platformAccessory.ts

@@ -0,0 +1,102 @@
+// StickFixture — one HomeKit Lightbulb accessory per patched fixture.
+
+import type {
+  CharacteristicValue,
+  PlatformAccessory,
+  Service,
+} from 'homebridge';
+
+import { Fixture } from './config.js';
+import { HomeKitLightState } from './color/types.js';
+import { StickController } from './controller.js';
+import type { DmxPlatform } from './platform.js';
+import { CHARACTERISTIC_UPDATE_DELAY_MS } from './settings.js';
+
+export class StickFixture {
+  /** Current HomeKit state we'll send to the Stick on the next push. */
+  private state: HomeKitLightState = { on: false, brightness: 100 };
+
+  /** Debounce timer for HomeKit's multi-characteristic dispatch
+   *  (Hue/Saturation/Brightness arrive as 3 separate set calls). */
+  private pending: NodeJS.Timeout | null = null;
+
+  constructor(
+    private readonly platform: DmxPlatform,
+    private readonly accessory: PlatformAccessory,
+    private readonly fixture: Fixture,
+    private readonly controller: StickController,
+  ) {
+    const C = platform.Characteristic;
+    const info = accessory.getService(platform.Service.AccessoryInformation);
+    info?.setCharacteristic(C.Manufacturer, 'Stick-DE3 DMX')
+        ?.setCharacteristic(C.Model, fixture.profile.name)
+        ?.setCharacteristic(C.SerialNumber, fixture.id);
+
+    const bulb: Service =
+      accessory.getService(platform.Service.Lightbulb)
+      ?? accessory.addService(platform.Service.Lightbulb, fixture.name);
+
+    bulb.setCharacteristic(C.Name, fixture.name);
+
+    const chars = fixture.profile.model.characteristics;
+
+    bulb.getCharacteristic(C.On)
+      .onGet(() => this.state.on)
+      .onSet((v) => { this.state.on = Boolean(v); this.schedule(); });
+
+    if (chars.includes('Brightness')) {
+      bulb.getCharacteristic(C.Brightness)
+        .onGet(() => this.state.brightness)
+        .onSet((v: CharacteristicValue) => {
+          this.state.brightness = Number(v);
+          this.schedule();
+        });
+    }
+
+    if (chars.includes('Hue')) {
+      bulb.getCharacteristic(C.Hue)
+        .onGet(() => this.state.hue ?? 0)
+        .onSet((v) => {
+          this.state.hue = Number(v);
+          // setting hue implies color mode (sat>0); leave saturation as-is
+          this.schedule();
+        });
+    }
+
+    if (chars.includes('Saturation')) {
+      bulb.getCharacteristic(C.Saturation)
+        .onGet(() => this.state.saturation ?? 0)
+        .onSet((v) => {
+          this.state.saturation = Number(v);
+          this.schedule();
+        });
+    }
+
+    if (chars.includes('ColorTemperature')) {
+      bulb.getCharacteristic(C.ColorTemperature)
+        .onGet(() => this.state.colorTemperatureMireds ?? 200)
+        .onSet((v) => {
+          this.state.colorTemperatureMireds = Number(v);
+          // CCT mode: HomeKit toggles between color and white modes; we mirror
+          // by zeroing saturation when CCT is changed.
+          this.state.saturation = 0;
+          this.schedule();
+        });
+    }
+  }
+
+  private schedule(): void {
+    if (this.pending) clearTimeout(this.pending);
+    this.pending = setTimeout(() => {
+      this.pending = null;
+      const s = this.state;
+      this.platform.log.info(
+        `[${this.fixture.id}] HK set: on=${s.on} br=${s.brightness}` +
+        (s.hue != null ? ` h=${s.hue}` : '') +
+        (s.saturation != null ? ` s=${s.saturation}` : '') +
+        (s.colorTemperatureMireds != null ? ` ct=${s.colorTemperatureMireds}` : ''),
+      );
+      this.controller.setFixture(this.fixture, this.state);
+    }, CHARACTERISTIC_UPDATE_DELAY_MS);
+  }
+}

package/src/settings.ts

@@ -0,0 +1,18 @@
+// Homebridge plugin constants.
+
+export const PLATFORM_NAME = 'DMX';
+export const PLUGIN_NAME = '@ecopoesis/homebridge-dmx';
+
+/** Coalesce HomeKit's multi-characteristic dispatch (Hue+Sat+Brightness
+ *  arrive as 3 separate sets when picking a color). Mirrors unifi-ap-rgb. */
+export const CHARACTERISTIC_UPDATE_DELAY_MS = 50;
+
+/** "Send until quiet" debounce. After the LAST HomeKit change, we wait
+ *  this long before spawning the send_dmx subprocess. Coalesces a fast
+ *  slider drag into one transaction. */
+export const DEBOUNCE_MS = 750;
+
+/** Frame interval (40ms = 25Hz, matches HWM exactly). Unused by the
+ *  subprocess controller — send_dmx.mjs's own FRAME_HZ env knob is what
+ *  matters now. */
+export const FRAME_INTERVAL_MS = 40;

package/src/stick/frame.ts

@@ -0,0 +1,70 @@
+// Encrypted 576-byte DMX frame builder.
+//
+// Layout (verified empirically 2026-05-23):
+//
+//   32-byte clear header
+//   +0x00 (8B)  magic = "Stick_3A"
+//   +0x08 (2B)  opcode 0x0019
+//   +0x0a (8B)  fieldA — the shared session message counter (Token)
+//   +0x12 (2B)  port — 0 for universe A; B unknown
+//   +0x14 (2B)  channel count, always 512
+//   +0x16 (1B)  constant 100
+//   +0x17 (1B)  frame seq counter (per-frame, modulo 256)
+//   +0x18 (8B)  random nonce
+//
+//   544-byte AES-256-CBC ciphertext
+//     IV = fieldA(8) ‖ nonce(8)
+//     plaintext = [P0(16)][zeros(16)][channels(512)]   ← off-by-16 fix
+//                                                       (was [P0][channels][trailer])
+
+import crypto from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { MAGIC, P0 } from './protocol.js';
+
+export interface FrameOpts {
+  /** AES-256 session key (32B) from KDF */
+  key: Buffer;
+  /** 512 DMX channel values (0-255 each) */
+  channels: Uint8Array;
+  /** universe port id (0 = A; B not yet known) */
+  port: number;
+  /** 8-byte fieldA from the session Token counter */
+  fieldA: Buffer;
+  /** per-frame sequence counter (low byte) */
+  seq: number;
+}
+
+/** Build one 576-byte encrypted DMX frame. */
+export function buildFrame(opts: FrameOpts): Buffer {
+  if (opts.channels.length !== 512) {
+    throw new Error(`channels must be 512 bytes, got ${opts.channels.length}`);
+  }
+  if (opts.key.length !== 32) {
+    throw new Error(`key must be 32 bytes (AES-256), got ${opts.key.length}`);
+  }
+  if (opts.fieldA.length !== 8) {
+    throw new Error(`fieldA must be 8 bytes, got ${opts.fieldA.length}`);
+  }
+
+  const nonce = crypto.randomBytes(8);
+  const iv = Buffer.concat([opts.fieldA, nonce]); // 16-byte CBC IV
+
+  // [P0(16)][zeros(16)][channels(512)] = 544
+  const plain = Buffer.concat([P0, Buffer.alloc(16), Buffer.from(opts.channels)]);
+
+  const c = crypto.createCipheriv('aes-256-cbc', opts.key, iv);
+  c.setAutoPadding(false);
+  const body = Buffer.concat([c.update(plain), c.final()]); // 544
+
+  const hdr = Buffer.alloc(32);
+  MAGIC.copy(hdr, 0);
+  hdr.writeUInt16LE(0x0019, 8);
+  opts.fieldA.copy(hdr, 0x0a);
+  hdr.writeUInt16LE(opts.port, 0x12);
+  hdr.writeUInt16LE(512, 0x14);
+  hdr[0x16] = 100;
+  hdr[0x17] = opts.seq & 0xff;
+  nonce.copy(hdr, 0x18);
+
+  return Buffer.concat([hdr, body]); // 576
+}

package/src/stick/kdf.ts

@@ -0,0 +1,99 @@
+// Stick-DE3 DMX cipher — per-session AES-256 key derivation (KDF).
+//
+// TypeScript port of tools/derive-dmx-key.mjs (which remains the canonical
+// reference). The .mjs version is kept untouched so diagnostic tools that
+// import it (verify-kdf.mjs, decrypt-dmx.mjs, etc.) keep working.
+//
+// Math summary (verified end-to-end against a real session):
+//
+//   curve = NIST P-256 / prime256v1
+//   d     = random scalar mod n              (ephemeral private, 32B)
+//   our   = d · G                            (our public key, sent in 0x0F)
+//   Q     = stick's response pubkey          (received in 0x0F reply)
+//   S     = decompress(STATIC_POINT_33B)     (hardcoded in HM binary)
+//
+//   AES-256 key = LE( X(d · S)  XOR  X(d · Q) )
+//
+// Endianness: every 256-bit coord on the wire is LITTLE-endian limbs;
+// node's `crypto` works in big-endian (SEC1), so we byte-reverse at every
+// boundary. The installed AES key is the LE form of the XOR.
+
+import crypto from 'node:crypto';
+import { Buffer } from 'node:buffer';
+
+export const P256 = {
+  p: 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffffn,
+  n: 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n,
+  a: 0xffffffff00000001000000000000000000000000fffffffffffffffffffffffcn,
+  b: 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604bn,
+  Gx: 0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296n,
+  Gy: 0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5n,
+} as const;
+
+// 33-byte SEC1-compressed static point. Stored verbatim at HardwareManager
+// file offset 0x7b0490 (vmaddr 0x1007b0490), prefix 0x03 (odd Y).
+export const STATIC_POINT_COMPRESSED = Buffer.from(
+  '0328081290396d063e5114526ed978b926558f6ba1c96ad2facf76fffb3ffea0fe',
+  'hex',
+);
+
+const rev = (b: Buffer): Buffer => Buffer.from(b).reverse();
+const pad32 = (b: Buffer): Buffer =>
+  b.length >= 32 ? b.subarray(b.length - 32)
+                 : Buffer.concat([Buffer.alloc(32 - b.length), b]);
+
+function modpow(base: bigint, exp: bigint, mod: bigint): bigint {
+  let r = 1n;
+  base %= mod;
+  while (exp > 0n) {
+    if (exp & 1n) r = (r * base) % mod;
+    base = (base * base) % mod;
+    exp >>= 1n;
+  }
+  return r;
+}
+
+/** SEC1-decompress a 33-byte compressed point to 65-byte uncompressed. */
+export function decompressPoint(compressed33: Buffer): Buffer {
+  const { p, a, b } = P256;
+  const prefix = compressed33[0];
+  const x = BigInt('0x' + compressed33.subarray(1, 33).toString('hex'));
+  const rhs = ((((x * x) % p) * x) % p + ((a * x) % p) + b) % p;
+  let y = modpow(rhs, (p + 1n) / 4n, p); // p ≡ 3 (mod 4)
+  if ((y * y) % p !== rhs) throw new Error('static point X is not on P-256');
+  if ((y & 1n) !== BigInt(prefix & 1)) y = p - y;
+  const hex = (v: bigint) => v.toString(16).padStart(64, '0');
+  return Buffer.from('04' + hex(x) + hex(y), 'hex');
+}
+
+/** Uncompressed SEC1 point (65B, 0x04‖X_be‖Y_be) → 64B little-endian wire. */
+export function pointToWire(uncompressed65: Buffer): Buffer {
+  const xbe = uncompressed65.subarray(1, 33);
+  const ybe = uncompressed65.subarray(33, 65);
+  return Buffer.concat([rev(xbe), rev(ybe)]);
+}
+
+/** 64B little-endian wire point → uncompressed SEC1 (65B) for node crypto. */
+export function wireToPoint(wire64: Buffer): Buffer {
+  const xbe = rev(wire64.subarray(0, 32));
+  const ybe = rev(wire64.subarray(32, 64));
+  return Buffer.concat([Buffer.from([0x04]), xbe, ybe]);
+}
+
+/** Create the ephemeral P-256 keypair (steps 1-2 of the KDF). */
+export function makeEphemeral(): crypto.ECDH {
+  const ecdh = crypto.createECDH('prime256v1');
+  ecdh.generateKeys();
+  return ecdh;
+}
+
+/** Derive the per-session AES-256 key.
+ *   key = LE( X(d·S) XOR X(d·Q) ) */
+export function deriveDmxKey(ecdh: crypto.ECDH, stickPub65: Buffer): Buffer {
+  const S = decompressPoint(STATIC_POINT_COMPRESSED);
+  const x1 = pad32(ecdh.computeSecret(S));
+  const x2 = pad32(ecdh.computeSecret(stickPub65));
+  const xorBE = Buffer.alloc(32);
+  for (let i = 0; i < 32; i++) xorBE[i] = x1[i] ^ x2[i];
+  return rev(xorBE);
+}

package/src/stick/protocol.ts

@@ -0,0 +1,90 @@
+// Wire-protocol constants + low-level helpers for the Stick-DE3 control
+// channel (TCP/2431) and the encrypted DMX stream (UDP/2431).
+//
+// Ported verbatim from tools/send_dmx.mjs (which is now frozen as the
+// reference implementation). All offsets / magic / opcodes here have been
+// reverse-engineered from the 2024-03-21 ESA2 HardwareManager binary; see
+// the [[stick-cipher-is-stream-not-aes]] memory note for the full RE trail.
+
+import { Buffer } from 'node:buffer';
+
+export const TCP_PORT = 2431;
+export const UDP_DST_PORT = 2431;
+export const UDP_SRC_PORT = 2430;
+
+export const MAGIC = Buffer.from('Stick_3A');
+export const LSAG = Buffer.from('LSAG_ALL');
+
+// 16-byte fixed plaintext header that every DMX frame starts with. Confirmed
+// constant across ≥2 independent sessions. Recovered from decrypted frames.
+export const P0 = Buffer.from('5b4e99da9685ad976c432b0a7ff9ffcc', 'hex');
+
+// HMAC-SHA256 key for the 0x48 TCP-auth handshake.
+//   = "#h.6xcKsGD{y}-z" (15 bytes), runtime-extracted from HardwareManager
+//     and verified against a captured 0x48 message.
+export const AUTH_KEY = Buffer.from('23682e3678634b7347447b797d2d7a', 'hex');
+
+// The Stick's static 0x0F pubkey. Constant across every observed session
+// (it's the "Q" the device claims as ephemeral but never actually rotates
+// in practice). Used as a fallback if the live 0x0F reply can't be parsed.
+// 64-byte little-endian wire form.
+export const Q_FALLBACK = Buffer.from(
+  '87ef58c2660c272b54a74bbc94cb8518108e370b7eed78456bd8d120c6b9ac0a' +
+  'd791e4ce698aea761679f4b92a3ecf2acd12bf9bc308ce0ba8cb96630871105e',
+  'hex',
+);
+
+/** A monotonic 4-byte LE counter shared between TCP messages and UDP frame
+ *  fieldA. The Stick rejects out-of-order tokens. */
+export class Token {
+  private n: number;
+  constructor(start = 0x80) { this.n = start; }
+  next(): Buffer {
+    const b = Buffer.alloc(8);
+    b.writeUInt32LE(this.n++, 0);
+    return b;
+  }
+  /** Current value without advancing. */
+  peek(): number { return this.n; }
+}
+
+/** Build a TCP/2431 message: magic(8) ‖ opcode(2 LE) ‖ ...body parts. */
+export function msg(magic: Buffer, opcode: number, ...parts: Buffer[]): Buffer {
+  const op = Buffer.alloc(2);
+  op.writeUInt16LE(opcode, 0);
+  return Buffer.concat([magic, op, ...parts]);
+}
+
+/** Find a Stick_3A / LSAG_ALL message of `opcode` and at least `minLen`
+ *  bytes inside the accumulating receive buffer. Returns the slice or null. */
+export function findMsg(rxBuf: Buffer, opcode: number, minLen: number): Buffer | null {
+  for (let o = 0; o + 10 <= rxBuf.length; o++) {
+    const head = rxBuf.subarray(o, o + 8);
+    if (!head.equals(MAGIC) && !head.equals(LSAG)) continue;
+    if (rxBuf.readUInt16LE(o + 8) !== opcode) continue;
+    if (rxBuf.length < o + minLen) continue;
+    return rxBuf.subarray(o, o + minLen);
+  }
+  return null;
+}
+
+/** Poll a predicate every 20ms until it returns non-null or `timeoutMs`
+ *  elapses. Returns the value or null on timeout. */
+export function waitFor<T>(
+  predicate: () => T | null,
+  timeoutMs: number,
+): Promise<T | null> {
+  return new Promise((resolve) => {
+    const deadline = Date.now() + timeoutMs;
+    const tick = () => {
+      const r = predicate();
+      if (r != null) return resolve(r);
+      if (Date.now() > deadline) return resolve(null);
+      setTimeout(tick, 20);
+    };
+    tick();
+  });
+}
+
+export const sleep = (ms: number): Promise<void> =>
+  new Promise((r) => setTimeout(r, ms));