@ecopoesis/homebridge-dmx 0.1.0

package/CLAUDE.md

@@ -0,0 +1,176 @@
+# homebridge-wac-dmx
+
+Homebridge plugin to control WAC Lighting CUBE Architectural DC-WD05 fixtures via a Nicolaudie Stick-DE3 DMX controller.
+
+## Architecture
+
+- 18x WAC DC-WD05 fixtures on a DMX chain
+- Nicolaudie Stick-DE3 wall-mount DMX controller at 192.168.96.2
+- Stick-DE3 exposes a TCP interface (port 2431) that sends raw DMX values
+- This plugin bridges HomeKit ↔ DMX via Homebridge
+
+## Fixture Configuration
+
+- RDM Personality: 4 (Enhanced Tuning, 5 channels per fixture)
+- DMX addresses: 1, 6, 11, 16, 21, 26, 31, 36, 41, 46, 51, 56, 61, 66, 71, 76, 81, 86
+
+### Physical fixture map
+
+9 positions (A–I) on the boat, each with an **up** and a **down** fixture
+(9 × 2 = 18). Nautical terms (bow = front, stern = back, port/stbd) for clarity.
+
+```
+            stern
+            G   H
+                    I
+ stbd  F            D  port
+       E            B
+            C   A
+            bow
+```
+
+| DMX | Pos | DMX | Pos | DMX | Pos |
+|-----|-----|-----|-----|-----|-----|
+|  1  | B up   | 31 | E down | 61 | I down |
+|  6  | A down | 36 | C down | 66 | B down |
+| 11  | E up   | 41 | C up   | 71 | I up   |
+| 16  | G up   | 46 | H down | 76 | G down |
+| 21  | H up   | 51 | F up   | 81 | D up   |
+| 26  | A up   | 56 | F down | 86 | D down |
+
+### Channel Map (per fixture, 5 channels)
+
+| Slot | Name             | DMX Range | Notes                        |
+|------|------------------|-----------|------------------------------|
+| 0    | Intensity        | 0-255     | Master dimmer (coarse)       |
+| 1    | Intensity (fine) | 0-255     | 16-bit fine dimmer           |
+| 2    | Color Temp       | 0-255     | Maps to 1650K-8000K          |
+| 3    | Saturation       | 0-255     | 0 = white/CCT mode           |
+| 4    | Hue              | 0-255     | 0-360° mapped to 0-255       |
+
+## HomeKit ↔ DMX Mapping
+
+HomeKit Lightbulb service characteristics:
+
+| HomeKit Characteristic | Range      | DMX Channel | Conversion                                              |
+|------------------------|------------|-------------|---------------------------------------------------------|
+| On                     | bool       | Ch 0        | on=last brightness, off=0                               |
+| Brightness             | 0-100%     | Ch 0 (+ Ch 1 for fine) | `Math.round(value * 2.55)`                |
+| Hue                    | 0-360°     | Ch 4        | `Math.round(value * 255 / 360)`                         |
+| Saturation             | 0-100%     | Ch 3        | `Math.round(value * 2.55)`                              |
+| ColorTemperature       | 50-400 mireds | Ch 2     | mireds→K: `1000000/mireds`, then scale 1650-8000K→0-255 |
+
+When saturation is 0, the fixture is in white/CCT mode using the color temp channel.
+When saturation > 0, it's in color mode using hue + saturation.
+
+## Stick-DE3 Network
+
+- Static IP: 192.168.96.2 (on dedicated /30 VLAN, ID 96)
+- The Stick changes its MAC address on every settings update (this is "a feature")
+
+### Protocol (observed via packet capture)
+
+- **TCP/2431** — control + per-session crypto handshake. Client sends
+  `LSAG_ALL\x00\x00\x15\x00\x00\x00`; Stick replies
+  `Stick_3A\x00\xc9\x00DEFAULT\x00…` (carries device name/identity). Short
+  probe connections close in ~30 ms (normal); one long-lived control session.
+- **UDP → 192.168.96.2:2431** (src port 2430) — the live DMX stream:
+  **576-byte frames = 32-byte clear header + 544-byte AES-128 body**
+  (CBC or CFB mode selectable by a flag in the cipher state; mode for the
+  live Stick3 path TBD). Custom-inlined AES (S-box @ `DAT_1007c0010`), not
+  Gladman library. See `tools/ghidra/README.md` and
+  `memory/stick-cipher-is-stream-not-aes.md` for the static-RE findings.
+- **UDP/2430 broadcast** — device discovery only.
+
+### Required device setup (CRITICAL — fixes the multi-minute lag)
+
+Symptom (now resolved): every DMX change — from any source (HWM faders, ESA
+Pro 2, raw stream) — applied a **consistent ~2–3 min late, then snapped**.
+
+Root cause: the Stick's **DMX output wire-timing** was set to absurd values
+(MBB 15000 / Break 1000 / MAB 1500 / **MBS 400**). MBS is applied between all
+512 slots every frame, so the output engine emitted frames so slowly that live
+input backed up in the device's FIFO for minutes. NOT a network/AES/show/fade
+problem — all of those were investigated and ruled out.
+
+Fix: **USB-connect Hardware Manager** → the DMX/fader screen → set
+**Standard/Recommended**:
+
+| Param | Good value |
+|-------|-----------|
+| MBB (Mark Before Break) | 100 |
+| Break | 180 |
+| MAB (Mark After Break) | 20 |
+| MBS (Mark Between Slots) | 4 |
+
+(≈ 40 Hz / ~348 fps figure shown). Lights then change instantly, over USB
+**and** the network.
+
+Gotchas:
+- This DMX-timing screen exists **only in USB-connected Hardware Manager** —
+  it is NOT in the network config, and a **factory Reset does NOT fix it**
+  (Reset wipes network + showfile but not these toward sane values).
+- After a Reset you must re-enter the static network *and* re-enable **WAN
+  access** for network HWM control.
+- fw **3.08** is the newest *version*, but builds differ: installed build is
+  dated **2024-08-08**; a newer Hardware Manager (≈May 2026) bundles **3.08
+  built 2026-03-31** — a silent same-version rebuild (no changelog line will
+  reflect it). It *may* fix the absurd DMX-timing defaults and/or MAC/remote
+  bugs — unknown without Nicolaudie support or testing.
+- **Landmine:** the device works only because the DMX timing was hand-fixed;
+  any factory Reset / settings corruption (it rewrites settings+MAC constantly)
+  reintroduces the absurd defaults and the ~2–3 min lag. A planned update to
+  the 2026-03-31 build *might* remove this permanently — do it deliberately,
+  not reactively, and **first archive the currently-installed Hardware Manager
+  app/installer**: it is the ONLY firmware-rollback path (Nicolaudie publishes
+  no old firmware). When updating: record config, flash, then read the DMX
+  screen *before* changing anything (defaults may already be sane).
+
+### Other notes
+
+- Hardware Manager / ESA Pro 2 send a tame, steady **25 Hz** stream — *not* a
+  flood. A pacing relay/bridge was built, deployed, and **disproven**; do not
+  revisit it.
+- First Connect after launching Hardware Manager often fails **XHL 17**; the
+  retry succeeds → stale single TCP/2431 session slot freed by the failed
+  attempt. The plugin should auto-retry and close its session cleanly.
+- `tools/quick-trigger.mjs` — spec-verified UDP/2430 Quick Trigger (scene-level
+  only; not actioned on fw3.08 unless "Security for Cloud Access" is off).
+  `tools/stick-status.mjs` — reads the TCP/2431 status packet (Live-Mode flag).
+- Per-fixture HomeKit control still requires sending the **encrypted 576-byte
+  DMX stream**; see `tools/ghidra/README.md` and
+  `memory/stick-cipher-is-stream-not-aes.md`. (The latency fix above is
+  independent and a prerequisite for that to be usable.)
+
+### Plugin architecture constraints (observed)
+
+- **Latch IS supported — on clean disconnect** (corrected 2026-05-20; the
+  earlier "no latch / must stream" note was wrong). The Stick holds DMX
+  values after a *clean* TCP disconnect; output only drops when the session
+  is dirty-dropped (TCP timeout, process kill, the current 2025-09-23
+  EsaPro2 HWM's bugged disconnect). Implication: the plugin can be
+  **transactional** — connect → ECDH handshake → send DMX → clean
+  disconnect → Stick holds the value. No persistent streaming needed.
+  Trade-off: a few hundred ms wall-controller blink per change. See
+  `memory/stick-actually-latches-on-clean-disconnect.md`.
+- **Single session, mutually exclusive with HWM.** Only one TCP/2431 session;
+  while Hardware Manager is connected the Stick is unusable by anything else
+  (and vice-versa). Fine for production — HWM is commissioning-only; the
+  plugin owns the session at runtime. They cannot run simultaneously.
+- **Graceful-fallback option:** load a real (non-empty) standalone show with a
+  sensible "lights on" look so a stream/plugin outage degrades to that look
+  instead of full blackout. Trade-off vs. the empty-show baseline.
+- **Hard dependency:** the continuous stream is the **encrypted 576-byte DMX**
+  (32-byte clear header + 544-byte AES-128 body, custom-inlined AES with
+  S-box at `DAT_1007c0010`). Mode is CBC or CFB, selected by a byte in the
+  cipher state (live Stick3 path mode TBD). Quick Trigger is scene-level,
+  can't do per-fixture. So the persistent sender is blocked on (1) recovering
+  the per-session AES key from the TCP/2431 handshake and (2) the first-block
+  IV setup. See `tools/ghidra/README.md` and
+  `memory/stick-cipher-is-stream-not-aes.md`.
+
+## Reference
+
+- Existing plugin by same author for style reference: https://github.com/ecopoesis/homebridge-unifi-ap-rgb/tree/main
+- WAC fixture spec: RGBWW, 1650K-8000K CCT range
+- Manufacturer ID (RDM): 0x0776

package/README.md

@@ -0,0 +1,146 @@
+# homebridge-dmx
+
+Homebridge platform plugin that exposes DMX fixtures as HomeKit Lightbulb
+accessories. The DMX controller is abstracted so additional controllers can be
+plugged in without rewriting your patch; the supported controller today is the
+**Nicolaudie Stick-DE3** (TCP/2431 + AES-256-CBC-encrypted 576-byte UDP DMX
+stream, reverse-engineered from the ESA2 Hardware Manager).
+
+[![npm](https://img.shields.io/npm/v/@ecopoesis/homebridge-dmx.svg)](https://www.npmjs.com/package/@ecopoesis/homebridge-dmx)
+
+## Status
+
+| Piece | State |
+| --- | --- |
+| Stick-DE3 control (auth, ECDH, encrypted DMX stream) | ✅ working |
+| Color models: dimmer, cct, rgb, rgbw, rgbww, rgbaw, hsvcct | ✅ |
+| YAML and Homebridge-UI config | ✅ |
+| Multiple controllers in one patch | ✅ (only `StickDE3` type supported today) |
+| Universe B on the Stick | 🚧 plumbed but the wire encoding is unknown |
+| Stick-DE3 password / "Cloud Access" auth | 🚧 not implemented |
+| State read-back | 🚧 Homebridge holds the canonical state; local drift accepted |
+
+## How it works
+
+Each HomeKit change is rendered into DMX bytes by the fixture's color model
+(HSV → channel values for the appropriate model), written into a per-universe
+buffer, and dispatched via a debounced controller. After 750 ms of quiet (or
+during a slider drag, continuously), the controller spawns
+**`tools/send_dmx.mjs`** as a child process which runs the full Stick-DE3
+handshake + 750 ms of 25 Hz encrypted UDP frames + a dirty close (RST → Stick
+latches the last values).
+
+The subprocess-per-transaction architecture is an empirical workaround:
+running the same protocol in-process in a long-lived plugin only worked for
+the first transaction; sessions 2+ silently failed to drive output. Running
+each transaction in a fresh node process bypasses whatever in-process state
+poisons subsequent sessions. Each transaction costs ~1.5–2 s total.
+
+## Install
+
+```bash
+npm install -g @ecopoesis/homebridge-dmx
+```
+
+Or, in the Homebridge UI: **Plugins** → search for "DMX" → install.
+
+## Config
+
+Two flavours: inline JSON via the Homebridge UI, or external YAML pointed to by
+`yamlPath`. YAML is recommended for anything beyond a couple of fixtures.
+
+Minimal inline config:
+
+```json
+"platforms": [
+  {
+    "platform": "DMX",
+    "name": "DMX",
+    "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", "start": 6 }
+    ]
+  }
+]
+```
+
+External YAML form (recommended):
+
+```json
+"platforms": [
+  { "platform": "DMX", "yamlPath": "/homebridge/dmx.yaml" }
+]
+```
+
+See [`examples/dmx.yaml`](examples/dmx.yaml) for a starting point.
+
+## Color models
+
+| Model | Channels | HomeKit characteristics |
+| --- | --- | --- |
+| `dimmer` | 1 (Intensity, +optional Fine) | On, Brightness |
+| `cct` | 2 (Intensity, ColorTemp `KMin-KMax`) | On, Brightness, ColorTemperature |
+| `rgb` | 3 (Red, Green, Blue — any order) | On, Brightness, Hue, Saturation |
+| `rgbw` | 4 (+ White; W = min(R,G,B)) | On, Brightness, Hue, Saturation |
+| `rgbww` | 5 (+ WarmWhite, CoolWhite — split by CCT) | On, Brightness, Hue, Saturation, ColorTemperature |
+| `rgbaw` | 5 (+ Amber, White) | On, Brightness, Hue, Saturation |
+| `hsvcct` | 5 (Intensity, Intensity (Fine), ColorTemp, Saturation, Hue) | All five characteristics; HomeKit-native (the WAC DC-WD05 layout) |
+
+Channel-name syntax:
+
+- `(Fine)` appended → 16-bit companion to the preceding channel
+  (e.g. `Intensity (Fine)` is the low byte of a 16-bit intensity).
+- CCT channels carry a Kelvin range: `ColorTemp 1650-8000`,
+  `WarmWhite 2700`, `CoolWhite 6500`.
+- Names are case-insensitive and recognise common aliases (`R`/`Red`,
+  `WW`/`Warm White`/`WarmWhite`, etc.).
+
+## CLI
+
+A `stick` CLI is included for hand-testing without Homebridge:
+
+```bash
+# Set channel 6 of universe A to 255 on a Stick at 192.168.96.2
+npx -p @ecopoesis/homebridge-dmx stick 192.168.96.2 uA,6=255
+
+# Named fixture from your YAML
+stick --config ~/.config/dmx.yaml 192.168.96.2 a_down=#ff8800
+```
+
+Value forms: `#rrggbb`, `#rgb`, `hsl(120, 100%, 50%)`, `hwb(180 10% 20%)`,
+`rgb(255,128,0)`, `kelvin(2700)`, `0..255` (dimmer profiles), `on`, `off`,
+`50%`.
+
+## Required Stick-DE3 device setup
+
+Brand-new (or factory-reset) Stick-DE3 devices ship with pathological DMX
+output timing. Symptom: every DMX change applies ~2–3 minutes late then snaps.
+Fix via **USB-connected Hardware Manager** → DMX/fader screen → set
+**Standard/Recommended** (MBB 100 / Break 180 / MAB 20 / MBS 4). This screen
+is USB-only; a factory Reset does NOT fix it. See `CLAUDE.md` →
+"Required device setup" for the full landmine.
+
+## Single-session lock
+
+While the plugin is mid-transaction (~1.5 s per change), the Stick is unusable
+from Hardware Manager (single TCP/2431 session, mutually exclusive). For an
+idle Homebridge the Stick is free for HWM commissioning at all other times.
+The latch model (clean disconnect leaves the last value lit) is what lets us
+be polite about this.
+
+## License
+
+Apache-2.0

package/config.schema.json

@@ -0,0 +1,143 @@
+{
+  "pluginAlias": "DMX",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Homebridge platform for DMX controllers. Currently supports the Nicolaudie Stick-DE3; the controller abstraction is structured so additional DMX controllers can be added later without rewriting your patch.",
+  "footerDisplay": "For larger setups, point **yamlPath** at an external YAML file containing the controllers + profiles + patch. The YAML replaces the inline JSON below entirely.",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "DMX",
+        "required": false
+      },
+      "yamlPath": {
+        "title": "YAML config path (optional)",
+        "type": "string",
+        "description": "Absolute or relative path to a YAML file containing the full config. When set, the YAML replaces the JSON fields below.",
+        "required": false
+      },
+      "controllers": {
+        "title": "DMX Controllers",
+        "type": "array",
+        "required": false,
+        "description": "One entry per physical controller. Patch entries below reference these by id.",
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "title": "Controller id",
+              "type": "string",
+              "required": true,
+              "description": "kebab-case identifier; referenced from patch entries."
+            },
+            "type": {
+              "title": "Controller type",
+              "type": "string",
+              "required": true,
+              "default": "StickDE3",
+              "oneOf": [
+                { "title": "Nicolaudie Stick-DE3", "enum": ["StickDE3"] }
+              ]
+            },
+            "ip": {
+              "title": "IP address",
+              "type": "string",
+              "format": "ipv4",
+              "required": true,
+              "description": "Static IP of the controller on its DMX VLAN (e.g. 192.168.96.2). Discovery is not supported."
+            }
+          }
+        }
+      },
+      "profiles": {
+        "title": "Fixture Profiles",
+        "type": "array",
+        "required": false,
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {
+              "title": "Profile name",
+              "type": "string",
+              "required": true,
+              "description": "Used as the 'type' in patch entries below."
+            },
+            "colormodel": {
+              "title": "Color model",
+              "type": "string",
+              "required": true,
+              "oneOf": [
+                { "title": "Dimmer (1ch)", "enum": ["dimmer"] },
+                { "title": "CCT (2ch intensity + colortemp)", "enum": ["cct"] },
+                { "title": "RGB (3ch)", "enum": ["rgb"] },
+                { "title": "RGBW (4ch + white)", "enum": ["rgbw"] },
+                { "title": "RGBWW (5ch + warm/cool white)", "enum": ["rgbww"] },
+                { "title": "RGBAW (5ch + amber + white)", "enum": ["rgbaw"] },
+                { "title": "HSV+CCT (5ch — WAC DC-WD05 native)", "enum": ["hsvcct"] }
+              ]
+            },
+            "channel_order": {
+              "title": "Channel order",
+              "type": "array",
+              "required": true,
+              "description": "Names in DMX-slot order. Append ' (Fine)' for a 16-bit companion, e.g. 'Intensity (Fine)'. CCT channels include a K range: 'ColorTemp 1650-8000'.",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      },
+      "patch": {
+        "title": "Patch",
+        "type": "array",
+        "required": false,
+        "items": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "title": "Fixture id",
+              "type": "string",
+              "required": true,
+              "description": "kebab-case identifier; the fixture's stable handle."
+            },
+            "name": {
+              "title": "HomeKit name",
+              "type": "string",
+              "required": true
+            },
+            "type": {
+              "title": "Profile",
+              "type": "string",
+              "required": true,
+              "description": "Must match a Profile name above."
+            },
+            "controller": {
+              "title": "Controller",
+              "type": "string",
+              "required": false,
+              "description": "Controller id this fixture is wired to. Optional when only one controller is configured."
+            },
+            "universe": {
+              "title": "DMX universe",
+              "type": "string",
+              "default": "A",
+              "oneOf": [
+                { "title": "A", "enum": ["A"] },
+                { "title": "B (untested)", "enum": ["B"] }
+              ]
+            },
+            "start": {
+              "title": "DMX start channel",
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 512,
+              "required": true
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/dist/cli/stick.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=stick.d.ts.map

package/dist/cli/stick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stick.d.ts","sourceRoot":"","sources":["../../src/cli/stick.ts"],"names":[],"mappings":""}

package/dist/cli/stick.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// stick — set DMX channels on a Stick-DE3, transactionally.
+//
+//   stick [--config <yaml>] <ip> <assignment> [<assignment>...]
+//
+// Assignment forms:
+//   <fixture-id>=<value>            named fixture from config
+//                                   value: "#FFFFFF", "hsl(120,50%,50%)",
+//                                          "hwb(180 10% 20%)", "rgb(255,128,0)",
+//                                          "kelvin(2700)", "50%", "128", "on", "off"
+//   u<universe>,<channel>=<byte>    raw single-channel write (e.g. "uA,6=255")
+//
+// Env knobs (same as the StickSession opts):
+//   STREAM_MS, CHATTER_MS, SETTLE_2E_MS, FRAME_HZ, SECTORS, RUN_PROBE,
+//   PROBE_GAP_MS, KEY_DUMP
+//
+// Config search order if --config not given:
+//   $STICK_CONFIG, ./stick-de3.yaml, ~/.config/stick-de3.yaml.
+// A config is OPTIONAL when ONLY raw u<universe>,<channel>=<byte> assignments
+// are used (and the ip is on the command line).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { loadConfig } from '../config.js';
+import { parseValue } from '../color/parsers.js';
+import { StickSession } from '../stick/session.js';
+function findDefaultConfig() {
+    const candidates = [
+        process.env.STICK_CONFIG,
+        path.resolve(process.cwd(), 'stick-de3.yaml'),
+        path.resolve(os.homedir(), '.config/stick-de3.yaml'),
+    ].filter(Boolean);
+    for (const c of candidates) {
+        try {
+            fs.accessSync(c, fs.constants.R_OK);
+            return c;
+        }
+        catch { /* miss */ }
+    }
+    return null;
+}
+function usage() {
+    console.error('usage: stick [--config <yaml>] <ip> <assignment> [<assignment>...]\n' +
+        '  assignments:\n' +
+        '    <fixture-id>=<value>        named fixture (config required)\n' +
+        '    u<universe>,<channel>=<n>   raw, e.g. uA,6=255');
+    process.exit(1);
+}
+function parseArgs(argv) {
+    let configPath = null;
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--config' || argv[i] === '-c') {
+            configPath = argv[++i];
+        }
+        else if (argv[i] === '-h' || argv[i] === '--help') {
+            usage();
+        }
+        else {
+            rest.push(argv[i]);
+        }
+    }
+    if (rest.length < 2)
+        usage();
+    return { configPath, ip: rest[0], assigns: rest.slice(1) };
+}
+function loadOptionalConfig(configPath, ip) {
+    const p = configPath ?? findDefaultConfig();
+    if (!p)
+        return null;
+    const cwd = path.dirname(p);
+    const text = fs.readFileSync(p, 'utf8');
+    const raw = p.endsWith('.yaml') || p.endsWith('.yml') ? yaml.load(text) : JSON.parse(text);
+    // CLI convenience: if the config doesn't define controllers, synthesize
+    // one from the cmdline ip (or a legacy top-level `ip:` field).
+    if (!raw.controllers || raw.controllers.length === 0) {
+        raw.controllers = [{ id: 'cli', type: 'StickDE3', ip: raw.ip ?? ip }];
+    }
+    return loadConfig(raw, cwd);
+}
+// Build a Map<universe, Uint8Array(512)> of channel targets from CLI args.
+function resolveAssignments(assigns, cfg) {
+    const universes = new Map();
+    const slot = (u) => {
+        let arr = universes.get(u);
+        if (!arr) {
+            arr = new Uint8Array(512);
+            universes.set(u, arr);
+        }
+        return arr;
+    };
+    for (const a of assigns) {
+        const eq = a.indexOf('=');
+        if (eq < 0)
+            throw new Error(`bad assignment "${a}": expected key=value`);
+        const lhs = a.slice(0, eq).trim();
+        const rhs = a.slice(eq + 1).trim();
+        // Raw: u<universe>,<channel>=<byte>
+        const raw = /^u([ab]),(\d+)$/i.exec(lhs);
+        if (raw) {
+            const u = raw[1].toUpperCase() === 'A' ? 0 : 1;
+            const ch = Number(raw[2]);
+            const byte = Number(rhs);
+            if (!Number.isInteger(ch) || ch < 1 || ch > 512) {
+                throw new Error(`raw "${a}": channel out of 1..512`);
+            }
+            if (!Number.isInteger(byte) || byte < 0 || byte > 255) {
+                throw new Error(`raw "${a}": value out of 0..255`);
+            }
+            slot(u)[ch - 1] = byte;
+            continue;
+        }
+        // Named fixture
+        if (!cfg) {
+            throw new Error(`assignment "${a}" needs a config; use --config or set STICK_CONFIG`);
+        }
+        const fx = cfg.fixtures.find((f) => f.id === lhs);
+        if (!fx) {
+            throw new Error(`unknown fixture id "${lhs}". Known: ${cfg.fixtures.map((f) => f.id).join(', ')}`);
+        }
+        const state = parseValue(rhs);
+        const bytes = fx.profile.model.render(state, fx.profile.channels);
+        const arr = slot(fx.universe);
+        for (let i = 0; i < bytes.length; i++) {
+            arr[fx.startCh - 1 + i] = bytes[i];
+        }
+    }
+    return universes;
+}
+async function main() {
+    const { configPath, ip, assigns } = parseArgs(process.argv.slice(2));
+    const cfg = loadOptionalConfig(configPath, ip);
+    // CLI ip arg overrides config ip if both present
+    const target = ip;
+    const universes = resolveAssignments(assigns, cfg);
+    if (universes.size === 0) {
+        console.error('no channels to set');
+        process.exit(1);
+    }
+    // Summarise what we're sending
+    for (const [u, arr] of universes) {
+        const lit = [...arr.entries()].filter(([, v]) => v).map(([i, v]) => `ch${i + 1}=${v}`);
+        console.log(`  universe ${u ? 'B' : 'A'}: ${lit.length} channel${lit.length === 1 ? '' : 's'}: ${lit.join(' ')}`);
+    }
+    const session = await StickSession.connect(target, {
+        log: (...a) => console.log('  ', ...a),
+    });
+    // Optional key dump (for offline pcap decryption)
+    try {
+        const keyPath = process.env.KEY_DUMP || `${os.homedir()}/.send_dmx-key.txt`;
+        // Access the key indirectly: it's a private field of StickSession, so we
+        // dump the most recent value we know about. Since we don't expose it,
+        // skip the dump here — the diagnostic tools in tools/ already do this.
+        void keyPath;
+    }
+    catch { /* silent */ }
+    const STREAM_MS = Number(process.env.STREAM_MS || 750);
+    const FRAME_HZ = Number(process.env.FRAME_HZ || 25);
+    const frameMs = Math.max(1, Math.round(1000 / FRAME_HZ));
+    console.log(`  streaming at ${FRAME_HZ} Hz (${frameMs}ms) for ${STREAM_MS}ms`);
+    let nFrames = 0;
+    const timer = setInterval(() => {
+        for (const [u, arr] of universes) {
+            session.send(arr, u);
+            nFrames++;
+        }
+    }, frameMs);
+    await new Promise((res) => setTimeout(res, STREAM_MS));
+    clearInterval(timer);
+    console.log(`  streamed ${nFrames} frames`);
+    session.destroy();
+    console.log('  disconnected (RST) — Stick should hold the last value');
+}
+main().catch((e) => { console.error('failed:', e); process.exit(1); });
+//# sourceMappingURL=stick.js.map

package/dist/cli/stick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stick.js","sourceRoot":"","sources":["../../src/cli/stick.ts"],"names":[],"mappings":"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"}

package/dist/color/cct.d.ts

@@ -0,0 +1,3 @@
+import { ColorModel } from './types.js';
+export declare const cct: ColorModel;
+//# sourceMappingURL=cct.d.ts.map

package/dist/color/cct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cct.d.ts","sourceRoot":"","sources":["../../src/color/cct.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,UAAU,EAMX,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,GAAG,EAAE,UA0BjB,CAAC"}