@ecopoesis/homebridge-dmx 0.2.0 → 0.4.0

package/src/stateRegistry.ts

@@ -0,0 +1,71 @@
+// StateRegistry — central store of every fixture's HomeKit-visible state.
+//
+// Every StickFixture and ZoneFixture reads/writes through here. Whenever a
+// fixture's state changes, listeners fire so zones can refresh their own
+// HomeKit characteristics (and vice versa: setting a zone updates each
+// member's state in the registry, which fires events, which prompt the
+// per-fixture accessories to update their HomeKit-displayed state).
+//
+// Majority rule for zone state: see pickMajority() — count occurrences of
+// each value across (alphabetically-sorted) members; largest count wins;
+// ties are broken in favour of the value held by the alphabetically-first
+// member.
+
+import { HomeKitLightState } from './color/types.js';
+
+export type StateChangeListener = (fixtureId: string) => void;
+
+const DEFAULT_STATE: HomeKitLightState = { on: false, brightness: 100 };
+
+export class StateRegistry {
+  private states = new Map<string, HomeKitLightState>();
+  private listeners = new Set<StateChangeListener>();
+
+  get(id: string): HomeKitLightState {
+    return this.states.get(id) ?? { ...DEFAULT_STATE };
+  }
+
+  /** Replace a fixture's state and fire change listeners. */
+  set(id: string, state: HomeKitLightState): void {
+    this.states.set(id, { ...state });
+    for (const l of this.listeners) l(id);
+  }
+
+  /** Merge a partial update into a fixture's state, returning the new full
+   *  state. Fires listeners. */
+  update(id: string, patch: Partial<HomeKitLightState>): HomeKitLightState {
+    const next: HomeKitLightState = { ...this.get(id), ...patch };
+    this.set(id, next);
+    return next;
+  }
+
+  onChange(cb: StateChangeListener): () => void {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  }
+}
+
+/** Bucket members' values; return the value with the largest bucket. Ties
+ *  break in favour of the value held by the first member in
+ *  alphabetical-id order. */
+export function pickMajority<T>(items: Array<{ id: string; v: T }>): T | undefined {
+  if (items.length === 0) return undefined;
+  const sorted = items.slice().sort((a, b) => a.id.localeCompare(b.id));
+  const counts = new Map<T, { count: number; firstIdx: number }>();
+  for (let i = 0; i < sorted.length; i++) {
+    const v = sorted[i].v;
+    const rec = counts.get(v);
+    if (rec) rec.count++;
+    else counts.set(v, { count: 1, firstIdx: i });
+  }
+  let bestV: T = sorted[0].v;
+  let bestRec = counts.get(bestV)!;
+  for (const [v, rec] of counts) {
+    if (rec.count > bestRec.count ||
+        (rec.count === bestRec.count && rec.firstIdx < bestRec.firstIdx)) {
+      bestV = v;
+      bestRec = rec;
+    }
+  }
+  return bestV;
+}

package/src/zoneAccessory.ts

@@ -1,12 +1,19 @@
-// ZoneFixture — virtual HomeKit Lightbulb that dispatches to a set of
-// member fixtures. Setting any characteristic of the zone updates the
-// zone's local state, then calls controller.setFixture for each member
-// using the zone's current state. The single controller debounce
-// coalesces all member updates into one subprocess transaction.
+// ZoneFixture — virtual HomeKit Lightbulb that aggregates a set of member
+// fixtures.
 //
-// Per-member HomeKit accessories are NOT updated automatically. The user
-// has accepted this trade-off: last command wins, and partial overrides
-// of group commands are fine.
+// Reads: each .onGet returns the MAJORITY value of that characteristic
+// across the zone's members. Ties are broken in favour of the value held
+// by the alphabetically-first member. This gives a deterministic display
+// even when members are in split states.
+//
+// Writes: each .onSet updates every member's state in the registry (which
+// fires per-member change events so the individual fixture accessories
+// refresh their own HomeKit displays), then triggers the controller for
+// each member so the DMX wire reflects the change.
+//
+// When ANY member's state changes (by any path), the zone's HomeKit
+// characteristics push the new majority — so zones containing overlapping
+// members stay coherent with each other.
 
 import type {
   CharacteristicValue,
@@ -14,21 +21,24 @@ import type {
   Service,
 } from 'homebridge';
 
-import { Zone } from './config.js';
+import { Fixture, Zone } from './config.js';
 import { HKCharacteristic, HomeKitLightState } from './color/types.js';
 import { StickController } from './controller.js';
 import type { DmxPlatform } from './platform.js';
 import { CHARACTERISTIC_UPDATE_DELAY_MS } from './settings.js';
+import { StateRegistry, pickMajority } from './stateRegistry.js';
 
 export class ZoneFixture {
-  private state: HomeKitLightState = { on: false, brightness: 100 };
   private pending: NodeJS.Timeout | null = null;
+  private refreshPending: NodeJS.Timeout | null = null;
+  private bulb: Service;
 
   constructor(
     private readonly platform: DmxPlatform,
     accessory: PlatformAccessory,
     private readonly zone: Zone,
     private readonly controllers: Map<string, StickController>,
+    private readonly registry: StateRegistry,
   ) {
     const C = platform.Characteristic;
     const info = accessory.getService(platform.Service.AccessoryInformation);
@@ -36,53 +46,83 @@ export class ZoneFixture {
         ?.setCharacteristic(C.Model, `Zone (${zone.members.length} fixtures)`)
         ?.setCharacteristic(C.SerialNumber, `zone-${zone.id}`);
 
-    const bulb: Service =
+    this.bulb =
       accessory.getService(platform.Service.Lightbulb)
       ?? accessory.addService(platform.Service.Lightbulb, zone.name);
 
-    bulb.setCharacteristic(C.Name, zone.name);
-
-    // Always expose On.
-    bulb.getCharacteristic(C.On)
-      .onGet(() => this.state.on)
-      .onSet((v) => { this.state.on = Boolean(v); this.schedule(); });
+    this.bulb.setCharacteristic(C.Name, zone.name);
 
     const has = (k: HKCharacteristic): boolean => zone.characteristics.includes(k);
 
+    this.bulb.getCharacteristic(C.On)
+      .onGet(() => this.majorityState().on)
+      .onSet((v) => this.applyToMembers({ on: Boolean(v) }));
+
     if (has('Brightness')) {
-      bulb.getCharacteristic(C.Brightness)
-        .onGet(() => this.state.brightness)
-        .onSet((v: CharacteristicValue) => {
-          this.state.brightness = Number(v);
-          this.schedule();
-        });
+      this.bulb.getCharacteristic(C.Brightness)
+        .onGet(() => this.majorityState().brightness)
+        .onSet((v: CharacteristicValue) => this.applyToMembers({ brightness: Number(v) }));
     }
     if (has('Hue')) {
-      bulb.getCharacteristic(C.Hue)
-        .onGet(() => this.state.hue ?? 0)
-        .onSet((v) => { this.state.hue = Number(v); this.schedule(); });
+      this.bulb.getCharacteristic(C.Hue)
+        .onGet(() => this.majorityState().hue ?? 0)
+        .onSet((v) => this.applyToMembers({ hue: Number(v) }));
     }
     if (has('Saturation')) {
-      bulb.getCharacteristic(C.Saturation)
-        .onGet(() => this.state.saturation ?? 0)
-        .onSet((v) => { this.state.saturation = Number(v); this.schedule(); });
+      this.bulb.getCharacteristic(C.Saturation)
+        .onGet(() => this.majorityState().saturation ?? 0)
+        .onSet((v) => this.applyToMembers({ saturation: Number(v) }));
     }
     if (has('ColorTemperature')) {
-      bulb.getCharacteristic(C.ColorTemperature)
-        .onGet(() => this.state.colorTemperatureMireds ?? 200)
-        .onSet((v) => {
-          this.state.colorTemperatureMireds = Number(v);
-          this.state.saturation = 0;
-          this.schedule();
-        });
+      this.bulb.getCharacteristic(C.ColorTemperature)
+        .onGet(() => this.majorityState().colorTemperatureMireds ?? 200)
+        .onSet((v) => this.applyToMembers({
+          colorTemperatureMireds: Number(v),
+          saturation: 0,
+        }));
+    }
+
+    // Refresh on any member change.
+    const memberIds = new Set(zone.members.map((m) => m.id));
+    registry.onChange((id) => {
+      if (memberIds.has(id)) this.scheduleRefresh();
+    });
+  }
+
+  /** Compute majority state across members, per characteristic. */
+  private majorityState(): HomeKitLightState {
+    const ss = this.zone.members.map((m) => ({ id: m.id, state: this.registry.get(m.id) }));
+    return {
+      on:                       pickMajority(ss.map((s) => ({ id: s.id, v: s.state.on }))) ?? false,
+      brightness:               pickMajority(ss.map((s) => ({ id: s.id, v: s.state.brightness }))) ?? 100,
+      hue:                      pickMajority(ss.map((s) => ({ id: s.id, v: s.state.hue }))),
+      saturation:               pickMajority(ss.map((s) => ({ id: s.id, v: s.state.saturation }))),
+      colorTemperatureMireds:   pickMajority(ss.map((s) => ({ id: s.id, v: s.state.colorTemperatureMireds }))),
+    };
+  }
+
+  /** 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
+   *  multi-characteristic dispatch coalesces. */
+  private applyToMembers(patch: Partial<HomeKitLightState>): void {
+    const next = { ...this.majorityState(), ...patch };
+    // Push the next state into every member's registry entry. This fires
+    // per-fixture change events so the individual StickFixture accessories
+    // refresh their own HomeKit displays.
+    for (const m of this.zone.members) {
+      this.registry.update(m.id, next);
     }
+    this.scheduleDispatch();
   }
 
-  private schedule(): void {
+  /** Debounced controller dispatch. Sends current registry state for each
+   *  member to the appropriate StickController. */
+  private scheduleDispatch(): void {
     if (this.pending) clearTimeout(this.pending);
     this.pending = setTimeout(() => {
       this.pending = null;
-      const s = this.state;
+      const s = this.majorityState();
       this.platform.log.info(
         `[zone:${this.zone.id}] HK set: on=${s.on} br=${s.brightness}` +
         (s.hue != null ? ` h=${s.hue}` : '') +
@@ -90,15 +130,41 @@ export class ZoneFixture {
         (s.colorTemperatureMireds != null ? ` ct=${s.colorTemperatureMireds}` : '') +
         ` → ${this.zone.members.length} members`,
       );
-      // Dispatch the zone's state to each member via that member's controller.
       for (const m of this.zone.members) {
         const c = this.controllers.get(m.controller.id);
         if (!c) {
           this.platform.log.error(`zone "${this.zone.id}": no controller for "${m.id}"`);
           continue;
         }
-        c.setFixture(m, this.state);
+        c.setFixture(m, this.registry.get(m.id));
+      }
+    }, CHARACTERISTIC_UPDATE_DELAY_MS);
+  }
+
+  /** Debounced refresh: when members change, push the new majority to
+   *  the zone's HomeKit characteristics. */
+  private scheduleRefresh(): void {
+    if (this.refreshPending) clearTimeout(this.refreshPending);
+    this.refreshPending = setTimeout(() => {
+      this.refreshPending = null;
+      const s = this.majorityState();
+      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('Saturation') && s.saturation != null) {
+        this.bulb.updateCharacteristic(C.Saturation, s.saturation);
+      }
+      if (this.zone.characteristics.includes('ColorTemperature') && s.colorTemperatureMireds != null) {
+        this.bulb.updateCharacteristic(C.ColorTemperature, s.colorTemperatureMireds);
       }
     }, CHARACTERISTIC_UPDATE_DELAY_MS);
   }
 }
+
+// Silence "Fixture imported but unused" — kept for potential future use.
+export type _MemberRef = Fixture;

package/tools/stick-power-cycle.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+# stick-power-cycle — hard power-cycle the Nicolaudie Stick-DE3 by turning
+# PoE off/on on its switch port (sw01 port 15, via PoE splitter).
+#
+# Why: the Stick can wedge into a state where TCP sessions and the crypto
+# handshake succeed but live DMX output is blackout (seen 2026-08-22..24);
+# only a real power removal recovers it. The UniFi UI "Power Cycle" bounce
+# is too short — the splitter rides through it. This holds power off for
+# OFF_SECONDS, then restores, then waits for the Stick to answer ping.
+#
+# Credentials: read at runtime from the homebridge config.json (same local
+# UniFi user the AP-RGB plugin uses). Nothing secret is stored here.
+#
+# Scheduled via systemd user timer (host has no cron):
+#   ~/.config/systemd/user/stick-power-cycle.{service,timer}  — daily 08:30 UTC
+#   (= 4:30am EDT; lights are always off then). Lingering enabled for miker so
+#   the timer fires without a login session. Logs: ~/stick-power-cycle.log
+#   Manual run: systemctl --user start stick-power-cycle.service
+
+import json, socket, ssl, sys, time, urllib.request, http.cookiejar
+
+CONTROLLER   = 'https://192.168.1.1'
+CONFIG_JSON  = '/opt/containers/homebridge/config.json'
+SWITCH_MAC   = '94:2a:6f:94:f1:da'   # sw01
+PORT_IDX     = 15                    # Stick-DE3 PoE splitter, "dmx" VLAN 96
+STICK_IP     = '192.168.96.2'
+OFF_SECONDS  = 30
+BOOT_WAIT_S  = 180
+
+def log(*a):
+    print(time.strftime('%Y-%m-%d %H:%M:%S%z'), *a, flush=True)
+
+def load_creds():
+    cfg = json.load(open(CONFIG_JSON))
+    p = next(x for x in cfg['platforms'] if x.get('platform') == 'UnifiAPLight')
+    return p['username'], p['password']
+
+class Unifi:
+    def __init__(self):
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        self.op = urllib.request.build_opener(
+            urllib.request.HTTPSHandler(context=ctx),
+            urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
+        self.csrf = ''
+
+    def req(self, method, path, body=None):
+        rq = urllib.request.Request(CONTROLLER + path, method=method,
+            data=json.dumps(body).encode() if body is not None else None,
+            headers={'Content-Type': 'application/json'})
+        if self.csrf:
+            rq.add_header('x-csrf-token', self.csrf)
+        r = self.op.open(rq, timeout=15)
+        self.csrf = r.headers.get('x-csrf-token', self.csrf)
+        return json.load(r)
+
+    def login(self, user, pw):
+        self.req('POST', '/api/auth/login', {'username': user, 'password': pw})
+
+    def get_switch(self):
+        data = self.req('GET', '/proxy/network/api/s/default/stat/device')['data']
+        return next(d for d in data if d.get('mac') == SWITCH_MAC)
+
+    def set_poe(self, poe_mode):
+        # port_overrides is replaced wholesale on PUT — merge, never clobber.
+        sw = self.get_switch()
+        overrides = sw.get('port_overrides', [])
+        entry = next((o for o in overrides if o.get('port_idx') == PORT_IDX), None)
+        if entry is None:
+            entry = {'port_idx': PORT_IDX}
+            overrides.append(entry)
+        entry['poe_mode'] = poe_mode
+        self.req('PUT', f"/proxy/network/api/s/default/rest/device/{sw['_id']}",
+                 {'port_overrides': overrides})
+        log(f'port {PORT_IDX} poe_mode -> {poe_mode}')
+
+def stick_up():
+    # TCP probe of the Stick's own control port — proves the device booted,
+    # not just that the link is up. (The host has no ping binary anyway.)
+    try:
+        socket.create_connection((STICK_IP, 2431), timeout=2).close()
+        return True
+    except OSError:
+        return False
+
+def main():
+    log(f'power-cycling Stick-DE3 (sw {SWITCH_MAC} port {PORT_IDX}, {OFF_SECONDS}s off)')
+    api = Unifi()
+    api.login(*load_creds())
+    api.set_poe('off')
+    try:
+        time.sleep(OFF_SECONDS)
+    finally:
+        # restore is sacred: retry hard so the port can never stay dark
+        for attempt in range(5):
+            try:
+                api.set_poe('auto')
+                break
+            except Exception as e:
+                log(f'restore attempt {attempt + 1} failed: {e}')
+                time.sleep(5)
+                try:
+                    api.login(*load_creds())
+                except Exception:
+                    pass
+        else:
+            log('FATAL: could not restore PoE — port may be off!')
+            sys.exit(2)
+
+    deadline = time.time() + BOOT_WAIT_S
+    while time.time() < deadline:
+        if stick_up():
+            log(f'Stick back up ({STICK_IP}:2431 accepting connections)')
+            return
+        time.sleep(5)
+    log(f'WARNING: Stick not reachable within {BOOT_WAIT_S}s of power restore')
+    sys.exit(1)
+
+if __name__ == '__main__':
+    main()