@ecopoesis/homebridge-dmx 0.1.0

package/src/cli/stick.ts

@@ -0,0 +1,198 @@
+#!/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 { Buffer } from 'node:buffer';
+import yaml from 'js-yaml';
+
+import { LoadedConfig, loadConfig, RawConfig } from '../config.js';
+import { parseValue } from '../color/parsers.js';
+import { StickSession } from '../stick/session.js';
+
+interface CliAssignment {
+  /** universe 0/1 */
+  universe: number;
+  /** 1-based channel */
+  channel: number;
+  /** byte value */
+  value: number;
+}
+
+function findDefaultConfig(): string | null {
+  const candidates = [
+    process.env.STICK_CONFIG,
+    path.resolve(process.cwd(), 'stick-de3.yaml'),
+    path.resolve(os.homedir(), '.config/stick-de3.yaml'),
+  ].filter(Boolean) as string[];
+  for (const c of candidates) {
+    try { fs.accessSync(c, fs.constants.R_OK); return c; } catch { /* miss */ }
+  }
+  return null;
+}
+
+function usage(): never {
+  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: string[]): { configPath: string | null; ip: string; assigns: string[] } {
+  let configPath: string | null = null;
+  const rest: string[] = [];
+  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: string | null, ip: string): LoadedConfig | null {
+  const p = configPath ?? findDefaultConfig();
+  if (!p) return null;
+  const cwd = path.dirname(p);
+  const text = fs.readFileSync(p, 'utf8');
+  const raw: RawConfig & { ip?: string } =
+    p.endsWith('.yaml') || p.endsWith('.yml') ? (yaml.load(text) as RawConfig) : 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: string[],
+  cfg: LoadedConfig | null,
+): Map<number, Uint8Array> {
+  const universes = new Map<number, Uint8Array>();
+  const slot = (u: number) => {
+    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(): Promise<void> {
+  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); });

package/src/color/cct.ts

@@ -0,0 +1,40 @@
+// cct — tunable-white (2 channel): intensity + color temp. No color.
+// channel_order: intensity (+optional fine) and a cct channel with K range.
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  brightness16,
+  ctByte,
+  requireRoles,
+  writeMaybe16,
+} from './types.js';
+
+export const cct: ColorModel = {
+  id: 'cct',
+  characteristics: ['On', 'Brightness', 'ColorTemperature'],
+  validate(channels) {
+    requireRoles(channels, ['intensity', 'cct']);
+    const c = channels.find((ch) => ch.role === 'cct');
+    if (!c || c.kMin == null || c.kMax == null) {
+      throw new Error("cct model needs a Kelvin range, e.g. 'ColorTemp 2700-6500'");
+    }
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const out = new Uint8Array(channels.length);
+    let i = 0;
+    while (i < channels.length) {
+      const ch = channels[i];
+      if (ch.role === 'intensity' && !ch.fine) {
+        i = writeMaybe16(out, channels, i, brightness16(state));
+      } else if (ch.role === 'cct' && !ch.fine) {
+        out[i] = ctByte(state.colorTemperatureMireds, ch.kMin!, ch.kMax!);
+        i++;
+      } else {
+        i++;
+      }
+    }
+    return out;
+  },
+};

package/src/color/dimmer.ts

@@ -0,0 +1,24 @@
+// dimmer — single-channel intensity-only fixture.
+// channel_order: 1 entry, role 'intensity' (optionally followed by a 'fine').
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  brightness16,
+  requireRoles,
+  writeMaybe16,
+} from './types.js';
+
+export const dimmer: ColorModel = {
+  id: 'dimmer',
+  characteristics: ['On', 'Brightness'],
+  validate(channels) {
+    requireRoles(channels, ['intensity']);
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const out = new Uint8Array(channels.length);
+    writeMaybe16(out, channels, 0, brightness16(state));
+    return out;
+  },
+};

package/src/color/hsvcct.ts

@@ -0,0 +1,59 @@
+// hsvcct — the WAC DC-WD05 native model.
+//
+// 5 channels: intensity, intensity (fine), cct, saturation, hue. Saturation
+// = 0  →  fixture is in CCT-only white mode (uses the cct channel).
+// Saturation > 0  →  fixture is in color mode (uses hue + saturation).
+//
+// Mapping per CLAUDE.md (verified on hardware 2026-05-23):
+//   On         → ch0 high byte / ch1 low byte = intensity
+//   Brightness → ch0/ch1 16-bit
+//   Hue        → ch4 = round(hue * 255 / 360)
+//   Saturation → ch3 = round(sat * 2.55)
+//   CCT        → ch2 = scale-to-Krange (K from 1000000/mireds)
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  brightness16,
+  clamp,
+  ctByte,
+  requireRoles,
+  writeMaybe16,
+} from './types.js';
+
+export const hsvcct: ColorModel = {
+  id: 'hsvcct',
+  characteristics: ['On', 'Brightness', 'Hue', 'Saturation', 'ColorTemperature'],
+  validate(channels) {
+    requireRoles(channels, ['intensity', 'cct', 'saturation', 'hue']);
+    const c = channels.find((ch) => ch.role === 'cct');
+    if (!c || c.kMin == null || c.kMax == null) {
+      throw new Error("hsvcct model needs a Kelvin range, e.g. 'ColorTemp 1650-8000'");
+    }
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const out = new Uint8Array(channels.length);
+    let i = 0;
+    while (i < channels.length) {
+      const ch = channels[i];
+      if (ch.fine) { i++; continue; }
+      switch (ch.role) {
+        case 'intensity':
+          i = writeMaybe16(out, channels, i, brightness16(state));
+          continue;
+        case 'cct':
+          out[i] = ctByte(state.colorTemperatureMireds, ch.kMin!, ch.kMax!);
+          break;
+        case 'saturation':
+          out[i] = Math.round(clamp(state.saturation ?? 0, 0, 100) * 2.55);
+          break;
+        case 'hue':
+          out[i] = Math.round((((state.hue ?? 0) % 360) / 360) * 255);
+          break;
+      }
+      i++;
+    }
+    return out;
+  },
+};

package/src/color/index.ts

@@ -0,0 +1,34 @@
+// Color-model registry. Look up a model by its lowercase id.
+
+import { ColorModel } from './types.js';
+import { dimmer } from './dimmer.js';
+import { cct } from './cct.js';
+import { rgb } from './rgb.js';
+import { rgbw } from './rgbw.js';
+import { rgbww } from './rgbww.js';
+import { rgbaw } from './rgbaw.js';
+import { hsvcct } from './hsvcct.js';
+
+export const COLOR_MODELS: Record<string, ColorModel> = {
+  dimmer: dimmer,
+  cct:    cct,
+  rgb:    rgb,
+  rgbw:   rgbw,
+  rgbww:  rgbww,
+  rgbaw:  rgbaw,
+  hsvcct: hsvcct,
+};
+
+/** Resolve a model by id (case-insensitive). Throws if unknown. */
+export function getColorModel(id: string): ColorModel {
+  const m = COLOR_MODELS[id.toLowerCase()];
+  if (!m) {
+    throw new Error(
+      `unknown colormodel "${id}". Supported: ${Object.keys(COLOR_MODELS).join(', ')}`,
+    );
+  }
+  return m;
+}
+
+export * from './types.js';
+export * from './parsers.js';

package/src/color/parsers.ts

@@ -0,0 +1,232 @@
+// Parsers — channel-name parser (used during config load) and CLI value
+// parser (`#hex`, `hsl(...)`, `hwb(...)`, `0..255` for dimmer).
+
+import { ChannelDef, ChannelRole, HomeKitLightState, clamp } from './types.js';
+
+// ── channel-name parser ────────────────────────────────────────────────────
+
+const NAME_TO_ROLE: Record<string, ChannelRole> = {
+  intensity:   'intensity',
+  brightness:  'intensity',
+  dimmer:      'intensity',
+  master:      'intensity',
+  cct:         'cct',
+  colortemp:   'cct',
+  colortemperature: 'cct',
+  temp:        'cct',
+  tunable:     'cct',
+  saturation:  'saturation',
+  sat:         'saturation',
+  hue:         'hue',
+  red:         'red',
+  r:           'red',
+  green:       'green',
+  g:           'green',
+  blue:        'blue',
+  b:           'blue',
+  white:       'white',
+  w:           'white',
+  warmwhite:   'warm-white',
+  ww:          'warm-white',
+  coolwhite:   'cool-white',
+  cw:          'cool-white',
+  amber:       'amber',
+  a:           'amber',
+};
+
+/** Parse a channel_order entry, e.g.:
+ *    "Intensity"            → { role: 'intensity' }
+ *    "Intensity (Fine)"     → { role: 'intensity', fine: true }
+ *    "ColorTemp 1650-8000"  → { role: 'cct', kMin: 1650, kMax: 8000 }
+ *    "Warm White"           → { role: 'warm-white' }
+ */
+export function parseChannelName(raw: string): ChannelDef {
+  const s = raw.trim();
+  // Strip a trailing (Fine) marker
+  const fineMatch = /\((fine|lo|low)\)\s*$/i.exec(s);
+  const beforeFine = fineMatch ? s.slice(0, fineMatch.index).trim() : s;
+  // K range "Name <kMin>-<kMax>"
+  const kMatch = /\s+(\d+)\s*[-–]\s*(\d+)\s*K?\s*$/.exec(beforeFine);
+  const beforeK = kMatch ? beforeFine.slice(0, kMatch.index).trim() : beforeFine;
+  // Normalize: strip whitespace, lowercase
+  const key = beforeK.replace(/\s+/g, '').toLowerCase();
+  const role = NAME_TO_ROLE[key];
+  if (!role) throw new Error(`unknown channel name: "${raw}"`);
+
+  const def: ChannelDef = { role };
+  if (fineMatch) def.fine = true;
+  if (kMatch) {
+    const kMin = Number(kMatch[1]);
+    const kMax = Number(kMatch[2]);
+    if (!(kMin > 0 && kMax > kMin)) {
+      throw new Error(`bad K range in "${raw}": expected positive ascending`);
+    }
+    def.kMin = kMin;
+    def.kMax = kMax;
+  }
+  return def;
+}
+
+// ── CLI value parser ───────────────────────────────────────────────────────
+
+/** Parse a CLI fixture value into a canonical HomeKit state.
+ *  Supports:
+ *    "#rrggbb" / "#rgb"   — hex color
+ *    "rgb(r,g,b)"          — 0..255 each
+ *    "hsl(h, s%, l%)"      — CSS HSL
+ *    "hwb(h, w%, b%)"      — CSS HWB
+ *    "kelvin(K)" / "K=K"   — CCT (sat=0, brightness=100)
+ *    "0".."255"            — single byte (dimmer profile)
+ *    "off" / "0%" / "on" / "100%"   — convenience
+ */
+export function parseValue(raw: string): HomeKitLightState {
+  const s = raw.trim();
+
+  // off / on
+  if (/^off$/i.test(s))  return { on: false, brightness: 0 };
+  if (/^on$/i.test(s))   return { on: true,  brightness: 100 };
+
+  // bare number / percent — checked before hex because a 3-digit decimal
+  // like "128" is ALSO a valid 3-char hex string.
+  if (/^\d+%?$/.test(s)) {
+    const isPct = s.endsWith('%');
+    const v = Number(s.replace('%', ''));
+    if (isPct) {
+      return { on: v > 0, brightness: clamp(v, 0, 100) };
+    }
+    return { on: v > 0, brightness: Math.round((clamp(v, 0, 255) / 255) * 100) };
+  }
+
+  // hex (requires # for clarity unless it contains a non-decimal hex char)
+  const hex = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(s);
+  if (hex) {
+    const h = hex[1];
+    const expand = h.length === 3 ? [...h].map((c) => c + c).join('') : h;
+    const r = parseInt(expand.slice(0, 2), 16);
+    const g = parseInt(expand.slice(2, 4), 16);
+    const b = parseInt(expand.slice(4, 6), 16);
+    return rgbToState(r, g, b);
+  }
+
+  // rgb(r,g,b)
+  const rgb = /^rgb\s*\(\s*([^)]+)\)$/i.exec(s);
+  if (rgb) {
+    const parts = splitArgs(rgb[1]);
+    if (parts.length !== 3) throw new Error(`bad rgb(): need 3 args in "${raw}"`);
+    const [r, g, b] = parts.map((p) => numberOrPercent(p, 255));
+    return rgbToState(r, g, b);
+  }
+
+  // hsl(h, s%, l%)
+  const hsl = /^hsl\s*\(\s*([^)]+)\)$/i.exec(s);
+  if (hsl) {
+    const parts = splitArgs(hsl[1]);
+    if (parts.length !== 3) throw new Error(`bad hsl(): need 3 args in "${raw}"`);
+    const h = angle(parts[0]);
+    const sPct = percent(parts[1]);
+    const lPct = percent(parts[2]);
+    return hslToState(h, sPct, lPct);
+  }
+
+  // hwb(h, w%, b%)
+  const hwb = /^hwb\s*\(\s*([^)]+)\)$/i.exec(s);
+  if (hwb) {
+    const parts = splitArgs(hwb[1]);
+    if (parts.length !== 3) throw new Error(`bad hwb(): need 3 args in "${raw}"`);
+    const h = angle(parts[0]);
+    const wPct = percent(parts[1]);
+    const bPct = percent(parts[2]);
+    return hwbToState(h, wPct, bPct);
+  }
+
+  // kelvin
+  const k = /^(?:k|kelvin)\s*[=:(]?\s*(\d+)\s*K?\)?$/i.exec(s);
+  if (k) {
+    const K = Number(k[1]);
+    if (!(K > 0)) throw new Error(`bad kelvin in "${raw}"`);
+    return { on: true, brightness: 100, saturation: 0, colorTemperatureMireds: Math.round(1_000_000 / K) };
+  }
+
+  throw new Error(`can't parse value: "${raw}"`);
+}
+
+function splitArgs(s: string): string[] {
+  // Support both comma and space separators (CSS Level 4 syntax).
+  return s.replace(/,/g, ' ').split(/\s+/).filter((p) => p.length > 0);
+}
+
+function percent(s: string): number {
+  const m = /^(-?\d*\.?\d+)\s*%?$/.exec(s);
+  if (!m) throw new Error(`bad percent: "${s}"`);
+  return Number(m[1]);
+}
+
+function numberOrPercent(s: string, base: number): number {
+  const m = /^(-?\d*\.?\d+)\s*(%?)$/.exec(s);
+  if (!m) throw new Error(`bad number: "${s}"`);
+  const v = Number(m[1]);
+  return m[2] === '%' ? Math.round((v / 100) * base) : v;
+}
+
+function angle(s: string): number {
+  const m = /^(-?\d*\.?\d+)\s*(deg|rad|turn)?$/i.exec(s);
+  if (!m) throw new Error(`bad angle: "${s}"`);
+  let v = Number(m[1]);
+  if (/^rad$/i.test(m[2] ?? '')) v = (v * 180) / Math.PI;
+  else if (/^turn$/i.test(m[2] ?? '')) v = v * 360;
+  return ((v % 360) + 360) % 360;
+}
+
+/** Convert RGB (0..255) into HomeKit HSV+brightness state. */
+function rgbToState(r: number, g: number, b: number): HomeKitLightState {
+  const rN = clamp(r, 0, 255) / 255;
+  const gN = clamp(g, 0, 255) / 255;
+  const bN = clamp(b, 0, 255) / 255;
+  const max = Math.max(rN, gN, bN);
+  const min = Math.min(rN, gN, bN);
+  const v = max;
+  const d = max - min;
+  let h = 0;
+  if (d !== 0) {
+    if (max === rN)      h = 60 * (((gN - bN) / d) % 6);
+    else if (max === gN) h = 60 * (((bN - rN) / d) + 2);
+    else                 h = 60 * (((rN - gN) / d) + 4);
+  }
+  if (h < 0) h += 360;
+  const s = max === 0 ? 0 : (d / max) * 100;
+  return {
+    on: v > 0,
+    brightness: Math.round(v * 100),
+    hue: Math.round(h),
+    saturation: Math.round(s),
+  };
+}
+
+function hslToState(h: number, sPct: number, lPct: number): HomeKitLightState {
+  // CSS HSL → HSV
+  const s = clamp(sPct, 0, 100) / 100;
+  const l = clamp(lPct, 0, 100) / 100;
+  const v = l + s * Math.min(l, 1 - l);
+  const sv = v === 0 ? 0 : 2 * (1 - l / v);
+  return {
+    on: v > 0,
+    brightness: Math.round(v * 100),
+    hue: ((h % 360) + 360) % 360,
+    saturation: Math.round(sv * 100),
+  };
+}
+
+function hwbToState(h: number, wPct: number, bPct: number): HomeKitLightState {
+  // CSS HWB → HSV
+  let w = clamp(wPct, 0, 100) / 100;
+  let bk = clamp(bPct, 0, 100) / 100;
+  if (w + bk > 1) { const t = w + bk; w /= t; bk /= t; }
+  const v = 1 - bk;
+  const s = v === 0 ? 0 : 1 - w / v;
+  return {
+    on: v > 0,
+    brightness: Math.round(v * 100),
+    hue: ((h % 360) + 360) % 360,
+    saturation: Math.round(s * 100),
+  };
+}

package/src/color/rgb.ts

@@ -0,0 +1,33 @@
+// rgb — 3-channel additive color.
+// channel_order: red, green, blue (any order).
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  hsvToRgb01,
+  rgbBytes,
+  requireRoles,
+} from './types.js';
+
+export const rgb: ColorModel = {
+  id: 'rgb',
+  characteristics: ['On', 'Brightness', 'Hue', 'Saturation'],
+  validate(channels) {
+    requireRoles(channels, ['red', 'green', 'blue']);
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const rgb01 = hsvToRgb01(state.hue ?? 0, state.saturation ?? 0);
+    const px = rgbBytes(rgb01, state);
+    const out = new Uint8Array(channels.length);
+    for (let i = 0; i < channels.length; i++) {
+      if (channels[i].fine) continue; // RGB fine channels not common; leave zero
+      switch (channels[i].role) {
+        case 'red':   out[i] = px.r; break;
+        case 'green': out[i] = px.g; break;
+        case 'blue':  out[i] = px.b; break;
+      }
+    }
+    return out;
+  },
+};

package/src/color/rgbaw.ts

@@ -0,0 +1,46 @@
+// rgbaw — RGB + Amber + White. Amber gets pulled out of the
+// yellow/orange region of the RGB, white from the remaining
+// achromatic component. Stage-lighting common.
+
+import {
+  ChannelDef,
+  ColorModel,
+  HomeKitLightState,
+  hsvToRgb01,
+  rgbBytes,
+  requireRoles,
+} from './types.js';
+
+export const rgbaw: ColorModel = {
+  id: 'rgbaw',
+  characteristics: ['On', 'Brightness', 'Hue', 'Saturation'],
+  validate(channels) {
+    requireRoles(channels, ['red', 'green', 'blue', 'amber', 'white']);
+  },
+  render(state: HomeKitLightState, channels: ChannelDef[]): Uint8Array {
+    const rgb01 = hsvToRgb01(state.hue ?? 0, state.saturation ?? 0);
+    const px = rgbBytes(rgb01, state);
+
+    // Amber ≈ min(R, ~0.75·G) where G is dominated by R, ie. yellow-orange region.
+    // Pull amber out of the green to avoid red dimming.
+    const amber = Math.min(px.r, Math.round(px.g * 0.75));
+    let r = px.r, g = px.g - amber, b = px.b;
+
+    // White from the remaining achromatic component.
+    const w = Math.min(r, g, b);
+    r -= w; g -= w; b -= w;
+
+    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] = r; break;
+        case 'green': out[i] = g; break;
+        case 'blue':  out[i] = b; break;
+        case 'amber': out[i] = amber; break;
+        case 'white': out[i] = w; break;
+      }
+    }
+    return out;
+  },
+};