@ecopoesis/homebridge-dmx 0.4.0 → 0.5.1

package/src/platform.ts

@@ -14,8 +14,11 @@ import type {
   Service,
 } from 'homebridge';
 
-import { Controller, LoadedConfig, loadConfig, RawConfig } from './config.js';
+import { Controller, Fixture, LoadedConfig, loadConfig, RawConfig } from './config.js';
 import { StickController } from './controller.js';
+import { DmxController } from './dmxController.js';
+import { readEthergateUniverse } from './ethergate.js';
+import { SacnController } from './sacn.js';
 import { StickFixture } from './platformAccessory.js';
 import { StateRegistry } from './stateRegistry.js';
 import { ZoneFixture } from './zoneAccessory.js';
@@ -27,8 +30,9 @@ export class DmxPlatform implements DynamicPlatformPlugin {
   public readonly accessories: PlatformAccessory[] = [];
 
   private cfg: LoadedConfig | null = null;
-  private controllers = new Map<string, StickController>();
+  private controllers = new Map<string, DmxController>();
   private registry = new StateRegistry();
+  private statePollTimers: NodeJS.Timeout[] = [];
 
   constructor(
     public readonly log: Logger,
@@ -59,16 +63,74 @@ export class DmxPlatform implements DynamicPlatformPlugin {
       `${this.cfg.zones.length} zone${this.cfg.zones.length === 1 ? '' : 's'}`,
     );
 
-    this.api.on('didFinishLaunching', () => this.discoverDevices());
+    this.api.on('didFinishLaunching', () => {
+      this.discoverDevices();
+      this.startStateSync();
+    });
     this.api.on('shutdown', () => {
+      for (const t of this.statePollTimers) clearInterval(t);
       for (const c of this.controllers.values()) c.shutdown();
     });
   }
 
-  private makeController(c: Controller): StickController {
+  /** State read-back (sACN/Ethergate only): the gateway's live output
+   *  buffers are ground truth for what's on the wire, so seed the registry
+   *  from them at startup — a Homebridge restart inherits reality instead
+   *  of assuming darkness — and optionally re-poll every statePollSeconds
+   *  to track changes made by other senders. */
+  private startStateSync(): void {
+    if (!this.cfg) return;
+    for (const spec of this.cfg.controllers) {
+      if (spec.type !== 'sACN') continue;
+      const ctrl = this.controllers.get(spec.id);
+      if (!(ctrl instanceof SacnController)) continue;
+      const fixtures = this.cfg.fixtures.filter(
+        (f) => f.controller.id === spec.id && f.profile.model.parse);
+      if (fixtures.length === 0) continue;
+
+      const sync = async (): Promise<void> => {
+        // Never clobber an in-flight HomeKit change with a read that may
+        // pre-date it.
+        if (Date.now() - ctrl.lastChangeAt < 5_000) return;
+        const universes = [...new Set(fixtures.map((f) => f.universe))];
+        for (const u of universes) {
+          const slots = await readEthergateUniverse(spec.ip, u);
+          if (!slots) {
+            this.log.debug(`state sync: universe ${u + 1} read failed (non-Ethergate gateway?)`);
+            continue;
+          }
+          for (const fx of fixtures) {
+            if (fx.universe !== u) continue;
+            this.applyReadBack(fx, slots);
+          }
+        }
+      };
+
+      sync().then(() => this.log.info(
+        `state sync: seeded ${fixtures.length} fixtures from ${spec.ip}`));
+      if (spec.statePollSeconds > 0) {
+        const t = setInterval(() => void sync(), spec.statePollSeconds * 1000);
+        t.unref?.();
+        this.statePollTimers.push(t);
+      }
+    }
+  }
+
+  private applyReadBack(fx: Fixture, slots: Uint8Array): void {
+    const bytes = slots.slice(fx.startCh - 1, fx.startCh - 1 + fx.nChannels);
+    const state = fx.profile.model.parse!(bytes, fx.profile.channels);
+    const cur = this.registry.get(fx.id);
+    if (JSON.stringify(cur) !== JSON.stringify(state)) {
+      this.registry.set(fx.id, state);
+    }
+  }
+
+  private makeController(c: Controller): DmxController {
     switch (c.type) {
       case 'StickDE3':
         return new StickController(c.ip, this.log, DEBOUNCE_MS, c.refreshMinutes * 60_000);
+      case 'sACN':
+        return new SacnController(c.ip, this.log, c.priority);
       default:
         throw new Error(`unsupported controller type "${(c as Controller).type}"`);
     }

package/src/platformAccessory.ts

@@ -12,7 +12,7 @@ import type {
 
 import { Fixture } from './config.js';
 import { HomeKitLightState } from './color/types.js';
-import { StickController } from './controller.js';
+import { DmxController } from './dmxController.js';
 import type { DmxPlatform } from './platform.js';
 import { CHARACTERISTIC_UPDATE_DELAY_MS } from './settings.js';
 import { StateRegistry } from './stateRegistry.js';
@@ -25,7 +25,7 @@ export class StickFixture {
     private readonly platform: DmxPlatform,
     private readonly accessory: PlatformAccessory,
     private readonly fixture: Fixture,
-    private readonly controller: StickController,
+    private readonly controller: DmxController,
     private readonly registry: StateRegistry,
   ) {
     const C = platform.Characteristic;

package/src/sacn.ts

@@ -0,0 +1,154 @@
+// SacnController — streams DMX to a network gateway over sACN (E1.31).
+//
+// Built for the ENTTEC DIN Ethergate Mk2 (PoE) but speaks plain
+// ANSI E1.31, so any sACN node works. Unlike the Stick there is no
+// session, no crypto, and sends are ~free, so the model is simple:
+//
+//   - setFixture() renders into a per-universe 512-byte buffer and marks
+//     the universe dirty; a short coalescing timer batches the burst of
+//     per-member calls a zone set produces into one packet per universe
+//   - a 1 Hz keepalive re-sends every universe we have state for: E1.31
+//     receivers drop a source after 2.5 s of silence, and the steady
+//     trickle keeps the gateway holding our look
+//   - shutdown() sends the spec's stream-terminated packets so the
+//     gateway drops the source cleanly (its DMX output holds last values)
+//
+// Universe numbering: patch universes A/B (internal 0/1) map to sACN
+// universes 1/2 — sACN has no universe 0. Set the Ethergate ports to
+// sACN universes 1 and 2. Packets are unicast to the configured ip.
+
+import type { Logger } from 'homebridge';
+import dgram from 'node:dgram';
+import { randomBytes } from 'node:crypto';
+
+import { Fixture } from './config.js';
+import { HomeKitLightState } from './color/types.js';
+import { DmxController } from './dmxController.js';
+import {
+  SACN_COALESCE_MS,
+  SACN_KEEPALIVE_MS,
+  SACN_PORT,
+  SACN_PRIORITY_DEFAULT,
+  SACN_SOURCE_NAME,
+} from './settings.js';
+
+const PACKET_LEN = 638;                  // full 512-slot E1.31 data packet
+const OPT_STREAM_TERMINATED = 0x40;
+
+export class SacnController implements DmxController {
+  private universes = new Map<number, Uint8Array>();  // internal idx (0=A,1=B) → slots
+  private seq = new Map<number, number>();
+  private dirty = new Set<number>();
+  private coalesceTimer: NodeJS.Timeout | null = null;
+  private keepaliveTimer: NodeJS.Timeout | null = null;
+  /** When setFixture last staged a change (keepalive re-sends excluded).
+   *  Read by the platform's state-poll guard so a read-back never clobbers
+   *  an in-flight HomeKit change. */
+  public lastChangeAt = 0;
+  private readonly socket: dgram.Socket;
+  private readonly cid = randomBytes(16);
+  private closed = false;
+
+  constructor(
+    private readonly ip: string,
+    private readonly log: Logger,
+    private readonly priority: number = SACN_PRIORITY_DEFAULT,
+  ) {
+    this.socket = dgram.createSocket('udp4');
+    this.socket.on('error', (e) => this.log.error('sACN socket error:', e.message));
+  }
+
+  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.dirty.add(fixture.universe);
+    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}/U${fixture.universe + 1}=${hex}`);
+    this.scheduleSend();
+    if (!this.keepaliveTimer) {
+      this.keepaliveTimer = setInterval(() => this.sendAll(), SACN_KEEPALIVE_MS);
+      this.keepaliveTimer.unref?.();
+    }
+  }
+
+  private universeBuf(u: number): Uint8Array {
+    let arr = this.universes.get(u);
+    if (!arr) { arr = new Uint8Array(512); this.universes.set(u, arr); }
+    return arr;
+  }
+
+  /** Coalesce the burst of setFixture calls a zone set produces into one
+   *  packet per universe. */
+  private scheduleSend(): void {
+    if (this.coalesceTimer) return;
+    this.coalesceTimer = setTimeout(() => {
+      this.coalesceTimer = null;
+      for (const u of this.dirty) this.sendUniverse(u);
+      this.dirty.clear();
+    }, SACN_COALESCE_MS);
+  }
+
+  private sendAll(): void {
+    for (const u of this.universes.keys()) this.sendUniverse(u);
+  }
+
+  private sendUniverse(u: number, options = 0): void {
+    if (this.closed) return;
+    const slots = this.universes.get(u);
+    if (!slots) return;
+    const seq = (this.seq.get(u) ?? 0) & 0xff;
+    this.seq.set(u, seq + 1);
+    const pkt = this.buildPacket(u + 1, seq, slots, options);
+    this.socket.send(pkt, SACN_PORT, this.ip, (e) => {
+      if (e) this.log.error(`sACN send U${u + 1} failed:`, e.message);
+    });
+  }
+
+  /** ANSI E1.31 data packet: root layer + framing layer + DMP layer. */
+  private buildPacket(sacnUniverse: number, seq: number, slots: Uint8Array, options: number): Buffer {
+    const buf = Buffer.alloc(PACKET_LEN);
+    // Root layer
+    buf.writeUInt16BE(0x0010, 0);                       // RLP preamble size
+    buf.writeUInt16BE(0x0000, 2);                       // RLP postamble size
+    buf.write('ASC-E1.17', 4, 'ascii');                 // ACN packet identifier (12 bytes, zero-padded)
+    buf.writeUInt16BE(0x7000 | (PACKET_LEN - 16), 16);  // flags + length
+    buf.writeUInt32BE(0x00000004, 18);                  // VECTOR_ROOT_E131_DATA
+    this.cid.copy(buf, 22);
+    // Framing layer
+    buf.writeUInt16BE(0x7000 | (PACKET_LEN - 38), 38);
+    buf.writeUInt32BE(0x00000002, 40);                  // VECTOR_E131_DATA_PACKET
+    buf.write(SACN_SOURCE_NAME.slice(0, 63), 44, 'utf8');
+    buf.writeUInt8(this.priority, 108);
+    buf.writeUInt16BE(0x0000, 109);                     // sync address (none)
+    buf.writeUInt8(seq, 111);
+    buf.writeUInt8(options, 112);
+    buf.writeUInt16BE(sacnUniverse, 113);
+    // DMP layer
+    buf.writeUInt16BE(0x7000 | (PACKET_LEN - 115), 115);
+    buf.writeUInt8(0x02, 117);                          // VECTOR_DMP_SET_PROPERTY
+    buf.writeUInt8(0xa1, 118);                          // address & data type
+    buf.writeUInt16BE(0x0000, 119);                     // first property address
+    buf.writeUInt16BE(0x0001, 121);                     // address increment
+    buf.writeUInt16BE(1 + 512, 123);                    // property value count
+    buf.writeUInt8(0x00, 125);                          // DMX start code
+    buf.set(slots, 126);
+    return buf;
+  }
+
+  shutdown(): void {
+    if (this.coalesceTimer) clearTimeout(this.coalesceTimer);
+    if (this.keepaliveTimer) clearInterval(this.keepaliveTimer);
+    // Spec-polite goodbye: three stream-terminated packets per universe.
+    // The gateway drops the source immediately instead of waiting out the
+    // 2.5 s network-loss timeout; its DMX output holds the last values.
+    for (const u of this.universes.keys()) {
+      for (let i = 0; i < 3; i++) this.sendUniverse(u, OPT_STREAM_TERMINATED);
+    }
+    this.closed = true;
+    setTimeout(() => this.socket.close(), 100).unref?.();
+  }
+}

package/src/settings.ts

@@ -27,3 +27,24 @@ export const REFRESH_CHECK_MS = 60_000;
  *  subprocess controller — send_dmx.mjs's own FRAME_HZ env knob is what
  *  matters now. */
 export const FRAME_INTERVAL_MS = 40;
+
+// ── sACN (E1.31) controller ────────────────────────────────────────────────
+
+/** UDP port sACN receivers listen on (ANSI E1.31). */
+export const SACN_PORT = 5568;
+
+/** Coalescing window for the burst of setFixture calls a zone set
+ *  produces: one packet per universe per burst. */
+export const SACN_COALESCE_MS = 25;
+
+/** Keepalive stream rate. E1.31 receivers drop a source after 2.5 s of
+ *  silence; a 1 Hz re-send keeps the gateway holding our look and
+ *  re-asserts state cheaply. */
+export const SACN_KEEPALIVE_MS = 1000;
+
+/** Default E1.31 priority (spec range 0-200, 100 = default). Only matters
+ *  if a second source ever targets the same universe. */
+export const SACN_PRIORITY_DEFAULT = 100;
+
+/** Source name advertised in every E1.31 framing layer (max 63 chars). */
+export const SACN_SOURCE_NAME = 'homebridge-dmx';

package/src/zoneAccessory.ts

@@ -23,7 +23,7 @@ import type {
 
 import { Fixture, Zone } from './config.js';
 import { HKCharacteristic, HomeKitLightState } from './color/types.js';
-import { StickController } from './controller.js';
+import { DmxController } from './dmxController.js';
 import type { DmxPlatform } from './platform.js';
 import { CHARACTERISTIC_UPDATE_DELAY_MS } from './settings.js';
 import { StateRegistry, pickMajority } from './stateRegistry.js';
@@ -37,7 +37,7 @@ export class ZoneFixture {
     private readonly platform: DmxPlatform,
     accessory: PlatformAccessory,
     private readonly zone: Zone,
-    private readonly controllers: Map<string, StickController>,
+    private readonly controllers: Map<string, DmxController>,
     private readonly registry: StateRegistry,
   ) {
     const C = platform.Characteristic;