odelic 0.0.0-stage → 0.2.0

package/src/controller.js

@@ -0,0 +1,219 @@
+/**
+ * High-level controller shared by the CLI, the HTTP API and the MCP server.
+ *
+ * - connects lazily, serialises operations and reconnects once if the link dropped
+ * - disconnects after `idleTimeout` seconds without commands, so the phone app can use the mesh again
+ *   (0 = keep the link open)
+ * - accepts light names from the config file ("living"), "all", or a raw vaddr ("00000000")
+ */
+import { InputError, LoginError } from './errors.js';
+import { log } from './log.js';
+import * as P from './protocol.js';
+import { OdelicMesh } from './client.js';
+import { Config } from './config.js';
+
+/** Integer from a number or numeric string (like Python's int()); throws InputError otherwise. */
+export function toInt(v, what = 'value') {
+  const n = typeof v === 'string' && v.trim() !== '' ? Number(v) : v;
+  if (typeof n !== 'number' || !Number.isFinite(n)) throw new InputError(`${what} must be a number (got ${JSON.stringify(v)})`);
+  return Math.trunc(n);
+}
+
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+const cmpBuf = (a, b) => Buffer.compare(a.vaddr, b.vaddr);
+
+export class Controller {
+  /**
+   * @param {string|null} [appId] default: $ODELIC_ID / config file
+   * @param {{node?: string|null, config?: Config, idleTimeout?: number|string|null, mesh?: OdelicMesh}} [opts]
+   *        idleTimeout: seconds before an idle link is released; 0 = stay connected;
+   *        null = $ODELIC_IDLE_TIMEOUT / config file / 60 s.
+   */
+  constructor(appId = null, { node = null, config = null, idleTimeout = null, mesh = null } = {}) {
+    this.config = config ?? Config.load();
+    const aid = this.config.appId(appId);
+    if (!aid && !mesh) throw new InputError('no app ID: pass --id, set ODELIC_ID, or run `odelic setup --id <ID>`');
+    this.mesh = mesh ?? new OdelicMesh(aid, { device: node ?? this.config.node });
+    this.idleTimeout = this.config.idle(idleTimeout);
+    this._queue = Promise.resolve();
+    this._idle = null;
+  }
+
+  // ------------------------------------------------------------ connection handling
+  /** Run `fn` after every previously queued operation (a simple mutex). */
+  _locked(fn) {
+    const run = this._queue.then(fn);
+    this._queue = run.catch(() => {});
+    return run;
+  }
+
+  _run(fn) {
+    return this._locked(async () => {
+      this._cancelIdle();
+      try {
+        for (let attempt = 0; ; attempt++) {
+          if (!this.mesh.isConnected) await this.mesh.connect();
+          try {
+            return await fn(this.mesh);
+          } catch (e) {
+            // retry once when the BLE link dropped under us; input / login errors are final
+            if (attempt || this.mesh.isConnected || e instanceof InputError || e instanceof LoginError) throw e;
+            log.info(`link lost (${e.message}), reconnecting`);
+            await this.mesh.disconnect();
+          }
+        }
+      } finally {
+        this._armIdle();
+      }
+    });
+  }
+
+  _cancelIdle() {
+    if (this._idle) clearTimeout(this._idle);
+    this._idle = null;
+  }
+
+  _armIdle() {
+    if (!this.idleTimeout || !this.mesh.isConnected) return;
+    this._idle = setTimeout(() => {
+      this._locked(async () => {
+        this._idle = null;
+        if (this.mesh.isConnected) {
+          log.info('idle, disconnecting');
+          await this.mesh.disconnect();
+        }
+      }).catch((e) => log.warning(`idle disconnect failed: ${e.message}`));
+    }, this.idleTimeout * 1000);
+    this._idle.unref?.();
+  }
+
+  /** Connect now (otherwise the first command connects). */
+  async connect() {
+    await this._run(async () => {});
+  }
+
+  async close() {
+    this._cancelIdle();
+    await this._locked(() => this.mesh.disconnect());
+  }
+
+  get connected() {
+    return this.mesh.isConnected;
+  }
+
+  get keepConnected() {
+    return !this.idleTimeout;
+  }
+
+  info() {
+    return { connected: this.connected, node: this.mesh.nodeName, mode: this.keepConnected ? 'keep' : 'idle', idle_timeout: this.idleTimeout };
+  }
+
+  // ------------------------------------------------------------ helpers
+  _label(v) {
+    return v.equals(P.BROADCAST) ? 'all' : (this.config.nameOf(v) ?? v.toString('hex'));
+  }
+
+  _done(action, v, extra = {}) {
+    return { ok: true, action, target: this._label(v), ...extra };
+  }
+
+  // ------------------------------------------------------------ actions
+  async on(target = 'all') {
+    const v = this.config.resolve(target);
+    await this._run((m) => m.on(v));
+    return this._done('on', v);
+  }
+
+  async off(target = 'all') {
+    const v = this.config.resolve(target);
+    await this._run((m) => m.off(v));
+    return this._done('off', v);
+  }
+
+  /** color 0 (warm) .. 100 (cool), brightness 1..100 % */
+  async setLight(target = 'all', color = 50, brightness = 100) {
+    const v = this.config.resolve(target);
+    color = clamp(toInt(color, 'color'), 0, 100);
+    brightness = clamp(toInt(brightness, 'brightness'), 1, 100);
+    await this._run((m) => m.setLight({ color, brightness, target: v }));
+    return this._done('light', v, { color, brightness });
+  }
+
+  async nightLight(target = 'all', level = 0) {
+    const v = this.config.resolve(target);
+    level = clamp(toInt(level, 'level'), 0, 2);
+    await this._run((m) => m.nightLight(level, v));
+    return this._done('night', v, { level });
+  }
+
+  /** action: "on", "off" or "light" (uses color / brightness) */
+  async group(groupId, action = 'on', color = 50, brightness = 100) {
+    const id = toInt(groupId, 'group id');
+    if (action === 'light') {
+      const c = clamp(toInt(color, 'color'), 0, 100);
+      const b = clamp(toInt(brightness, 'brightness'), 1, 100);
+      await this._run((m) => m.setGroup(id, { color: c, brightness: b }));
+    } else if (action === 'on' || action === 'off') {
+      await this._run((m) => m.setGroup(id, { on: action === 'on' }));
+    } else {
+      throw new InputError('action must be on, off or light');
+    }
+    return { ok: true, action: `group_${action}`, group: id };
+  }
+
+  async scene(index, save = false) {
+    const i = toInt(index, 'scene index');
+    await this._run((m) => (save ? m.saveScene(i) : m.playScene(i)));
+    return { ok: true, action: save ? 'scene_save' : 'scene_play', index: i };
+  }
+
+  async changeColor(target) {
+    const v = this.config.resolve(target);
+    await this._run((m) => m.changeColor(v));
+    return this._done('change_color', v);
+  }
+
+  /** Lights answering a mesh ping, plus named lights that did not answer (online: false). */
+  async lights(timeout = 3) {
+    const devs = await this._run((m) => m.devices(timeout));
+    const out = [];
+    const seen = new Set();
+    for (const d of [...devs].sort(cmpBuf)) {
+      const hex = d.vaddr.toString('hex');
+      seen.add(hex);
+      out.push({ name: this.config.nameOf(d.vaddr), vaddr: hex, online: true, mac: d.mac, product: d.product, version: d.version });
+    }
+    for (const [name, v] of Object.entries(this.config.lights)) {
+      if (!seen.has(v)) out.push({ name, vaddr: v, online: false });
+    }
+    return out;
+  }
+
+  /** State of one light, or of every responding light for "all". */
+  async status(target = 'all') {
+    const v = this.config.resolve(target);
+    if (v.equals(P.BROADCAST)) {
+      const devs = await this._run((m) => m.devices());
+      const out = [];
+      for (const d of [...devs].sort(cmpBuf)) out.push(await this.status(d.vaddr));
+      return out;
+    }
+    const st = await this._run((m) => m.status(v));
+    if (st === null) return { name: this.config.nameOf(v), vaddr: v.toString('hex'), online: false };
+    return { name: this.config.nameOf(v), online: true, ...st.toJSON() };
+  }
+
+  // ------------------------------------------------------------ names (no BLE needed)
+  nameLight(name, target) {
+    this.config.setName(name, target);
+    this.config.save();
+    return { ok: true, name, vaddr: this.config.lights[name] };
+  }
+
+  forgetName(name) {
+    this.config.removeName(name);
+    this.config.save();
+    return { ok: true, removed: name };
+  }
+}

package/src/crypto.js

@@ -0,0 +1,99 @@
+/**
+ * Pairlink connected-mesh crypto.
+ *
+ * Reverse-engineered from libnative-lib.so in the ODELIC app (jp.co.odelic.smt.remote10):
+ *
+ * - key material = HomeID (4B, little endian) and password (4 ASCII bytes) interleaved
+ *                  -> h0 p0 h1 p1 h2 p2 h3 p3
+ * - login key    = material + "LOGINKEY"   (AES-128)
+ * - event key    = material + "EVENTKEY"   (AES-128)
+ * - login        : node sends 02 20 <AES_LK(homeid | session4 | pad)>,
+ *                  we answer 01 16 03 <AES_LK(homeid | pwd | session4 | pad)>
+ * - data packets : 03 <dst4> <ch> <payload>  ->  06 <dst4> <ch> XOR4(AES_EK(pkcs7(payload)), session4)
+ */
+import { createCipheriv, createDecipheriv } from 'node:crypto';
+
+import { InputError, LoginError } from './errors.js';
+
+/** AES-128-ECB without padding; `data` must be a multiple of 16 bytes. */
+export function aes128(key, data, { decrypt = false } = {}) {
+  const c = (decrypt ? createDecipheriv : createCipheriv)('aes-128-ecb', key, null);
+  c.setAutoPadding(false);
+  return Buffer.concat([c.update(data), c.final()]);
+}
+
+export function pkcs7Pad(data) {
+  const n = 16 - (data.length % 16);
+  return Buffer.concat([data, Buffer.alloc(n, n)]);
+}
+
+export function pkcs7Unpad(data) {
+  const n = data.length ? data[data.length - 1] : 0;
+  if (n < 1 || n > 16 || n > data.length || !data.subarray(-n).every((b) => b === n)) {
+    throw new InputError('bad padding');
+  }
+  return data.subarray(0, data.length - n);
+}
+
+/** Keys for one mesh (HomeID + password) and the per-connection session value. */
+export class MeshCrypto {
+  /**
+   * @param {number} homeid
+   * @param {string} password 4 ASCII characters
+   */
+  constructor(homeid, password) {
+    if (!Number.isInteger(homeid) || homeid < 0 || homeid > 0xffffffff) {
+      throw new InputError(`HomeID must be a 32-bit unsigned integer (got ${homeid})`);
+    }
+    if (typeof password !== 'string' || !/^[\x00-\x7f]{4}$/.test(password)) {
+      throw new InputError('password must be 4 ASCII characters');
+    }
+    this.homeid = Buffer.alloc(4);
+    this.homeid.writeUInt32LE(homeid);
+    this.password = Buffer.from(password, 'ascii');
+    const mat = Buffer.alloc(8);
+    for (let i = 0; i < 4; i++) {
+      mat[2 * i] = this.homeid[i];
+      mat[2 * i + 1] = this.password[i];
+    }
+    this._loginKey = Buffer.concat([mat, Buffer.from('LOGINKEY')]);
+    this._eventKey = Buffer.concat([mat, Buffer.from('EVENTKEY')]);
+    /** @type {Buffer|null} */
+    this.session = null;
+  }
+
+  /** `challenge` = the 16 encrypted bytes following `02 20`. Returns the login packet. */
+  answerChallenge(challenge) {
+    const plain = aes128(this._loginKey, Buffer.from(challenge).subarray(0, 16), { decrypt: true });
+    if (!plain.subarray(0, 4).equals(this.homeid)) {
+      throw new LoginError(`node belongs to another HomeID (${plain.readUInt32LE(0)})`);
+    }
+    this.session = Buffer.from(plain.subarray(4, 8));
+    const body = aes128(this._loginKey, pkcs7Pad(Buffer.concat([this.homeid, this.password, this.session])));
+    return Buffer.concat([Buffer.from([0x01, 0x16, 0x03]), body]);
+  }
+
+  _xor(data) {
+    const k = this.session;
+    return Buffer.from(data.map((b, i) => b ^ k[i % 4]));
+  }
+
+  /** `03 <dst4> <ch> <payload>`  ->  `06 <dst4> <ch> <cipher>` */
+  encrypt(plain) {
+    plain = Buffer.from(plain);
+    if (this.session === null) throw new LoginError('not logged in');
+    if (plain.length < 7 || plain[0] !== 0x03) throw new InputError('expected a data-event packet (type 3)');
+    const cipher = aes128(this._eventKey, pkcs7Pad(plain.subarray(6)));
+    return Buffer.concat([Buffer.from([0x06]), plain.subarray(1, 6), this._xor(cipher)]);
+  }
+
+  /** `06 <src/dst4> <ch> <cipher>`  ->  `03 <...> <payload>`; other packet types pass through. */
+  decrypt(packet) {
+    packet = Buffer.from(packet);
+    if (!packet.length || packet[0] !== 0x06 || this.session === null) return packet;
+    let body = this._xor(packet.subarray(6));
+    body = body.subarray(0, body.length - (body.length % 16));
+    const plain = pkcs7Unpad(aes128(this._eventKey, body, { decrypt: true }));
+    return Buffer.concat([Buffer.from([0x03]), packet.subarray(1, 6), plain]);
+  }
+}

package/src/errors.js

@@ -0,0 +1,17 @@
+/** Error types. `InputError` = bad user input (HTTP 400); the others come from the mesh / BLE side. */
+
+export class OdelicError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+}
+
+/** Invalid argument: unknown light name, malformed vaddr / ID, out-of-range number, ... */
+export class InputError extends OdelicError {}
+
+/** The node rejected the login (wrong HomeID / password, or another controller is connected). */
+export class LoginError extends OdelicError {}
+
+/** No mesh node found, or the BLE link could not be established. */
+export class ConnectionError extends OdelicError {}

package/src/index.js

@@ -0,0 +1,11 @@
+/** Unofficial Node.js library for ODELIC Bluetooth lights (Pairlink connected-mesh). */
+export { OdelicMesh, findNodes } from './client.js';
+export { Config, configPath, parseIdle } from './config.js';
+export { Controller } from './controller.js';
+export { MeshCrypto } from './crypto.js';
+export { ConnectionError, InputError, LoginError, OdelicError } from './errors.js';
+export { setLogLevel } from './log.js';
+export { BROADCAST, Device, LightState, parseAppId } from './protocol.js';
+export * as protocol from './protocol.js';
+export { serve } from './server.js';
+export { VERSION } from './version.js';

package/src/log.js

@@ -0,0 +1,20 @@
+/** Minimal leveled logger writing to stderr (stdout stays clean for the CLI output and MCP stdio). */
+
+const LEVELS = { debug: 10, info: 20, warning: 30, error: 40, silent: 100 };
+let current = LEVELS[String(process.env.ODELIC_LOG || '').toLowerCase()] ?? LEVELS.warning;
+
+export function setLogLevel(level) {
+  if (!(level in LEVELS)) throw new RangeError(`unknown log level ${level}`);
+  current = LEVELS[level];
+}
+
+function emit(level, args) {
+  if (LEVELS[level] >= current) console.error('odelic:', ...args);
+}
+
+export const log = {
+  debug: (...a) => emit('debug', a),
+  info: (...a) => emit('info', a),
+  warning: (...a) => emit('warning', a),
+  error: (...a) => emit('error', a),
+};

package/src/mcp.js

@@ -0,0 +1,89 @@
+/**
+ * MCP server exposing ODELIC lights to AI assistants (stdio).
+ *
+ *     npm install odelic @modelcontextprotocol/sdk zod
+ *     odelic-mcp       # reads the ID from ODELIC_ID or the config file (`odelic setup --id ...`)
+ *
+ * The BLE link is opened on the first command. By default it is released after 60 s without
+ * commands so the official phone app can still connect; set ODELIC_IDLE_TIMEOUT (seconds, 0 = stay
+ * connected) or `odelic setup --keep-connected` to change that.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+import { Controller } from './controller.js';
+import { VERSION } from './version.js';
+
+export const INSTRUCTIONS = `Controls ODELIC Bluetooth ceiling/room lights in the user's home.
+Targets: a light name (see list_lights), or "all" for every light.
+Colour is 0 = warm/電球色 (orange) ... 100 = cool/昼光色 (bluish white); brightness is 1..100 %.
+Commands are fire-and-forget; use light_status to confirm the result if needed.`;
+
+const READ_ONLY = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
+const ACTION = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+
+const target = z.string().default('all').describe('light name, vaddr, or "all"');
+const color = z.number().int().min(0).max(100).default(50).describe('0 = warm/電球色 .. 50 = neutral .. 100 = cool/昼光色');
+const brightness = z.number().int().min(1).max(100).default(100).describe('1..100 (%)');
+
+const result = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] });
+
+/**
+ * Build the MCP server.
+ * @param {() => Controller} getController called lazily on the first tool call
+ */
+export function createMcpServer(getController = lazyController()) {
+  const server = new McpServer({ name: 'odelic', version: VERSION }, { instructions: INSTRUCTIONS });
+  const ctl = () => getController();
+  const tool = (name, description, annotations, inputSchema, fn) =>
+    server.registerTool(name, { description, annotations, inputSchema }, async (args) => {
+      try {
+        return result(await fn(args));
+      } catch (e) {
+        return { ...result({ ok: false, error: `${e.name}: ${e.message}` }), isError: true };
+      }
+    });
+
+  tool('list_lights', 'List the lights in the mesh (name, vaddr, online, product). Takes a few seconds.',
+    READ_ONLY, {}, () => ctl().lights());
+  tool('light_status', 'Current state of a light: on/off, colour (0 warm..100 cool) and brightness (%).',
+    READ_ONLY, { target }, async (a) => {
+      const res = await ctl().status(a.target);
+      return Array.isArray(res) ? { lights: res } : res;
+    });
+  tool('turn_on', 'Turn a light (or "all") on with its previous colour and brightness.',
+    ACTION, { target }, (a) => ctl().on(a.target));
+  tool('turn_off', 'Turn a light (or "all") off.', ACTION, { target }, (a) => ctl().off(a.target));
+  tool('set_light', 'Turn on with a given colour and brightness.',
+    ACTION, { target, color, brightness }, (a) => ctl().setLight(a.target, a.color, a.brightness));
+  tool('night_light', 'Very dim warm night light. level 0..2.',
+    ACTION, { target, level: z.number().int().min(0).max(2).default(0) }, (a) => ctl().nightLight(a.target, a.level));
+  tool('control_group', 'Control a group configured in the ODELIC app. action: "on", "off" or "light" (uses color/brightness).',
+    ACTION, { group_id: z.number().int().min(0).max(255), action: z.enum(['on', 'off', 'light']).default('on'), color, brightness },
+    (a) => ctl().group(a.group_id, a.action, a.color, a.brightness));
+  tool('play_scene', 'Recall a scene saved in the lights (index as in the app).',
+    ACTION, { index: z.number().int().min(0).max(255) }, (a) => ctl().scene(a.index, false));
+  tool('save_scene', 'Store the current state of all lights as scene `index` (overwrites that scene).',
+    DESTRUCTIVE, { index: z.number().int().min(0).max(255) }, (a) => ctl().scene(a.index, true));
+  tool('name_light', 'Give a light (vaddr from list_lights) a friendly name such as "living" or "リビング".',
+    { readOnlyHint: false, destructiveHint: false, openWorldHint: false }, { name: z.string().min(1), vaddr: z.string() },
+    (a) => ctl().nameLight(a.name, a.vaddr));
+  tool('forget_light_name', 'Remove a light name from the config.',
+    DESTRUCTIVE, { name: z.string() }, (a) => ctl().forgetName(a.name));
+  return server;
+}
+
+function lazyController() {
+  let c = null;
+  // idle timeout from $ODELIC_IDLE_TIMEOUT / config (0 = stay connected)
+  return () => (c ??= new Controller());
+}
+
+/** Run the MCP server on stdio (logs go to stderr). */
+export async function main() {
+  const getController = lazyController();
+  const server = createMcpServer(getController);
+  await server.connect(new StdioServerTransport());
+}

package/src/protocol.js

@@ -0,0 +1,179 @@
+/**
+ * Packet builders/parsers for ODELIC lights on the Pairlink mesh.
+ *
+ * Mirrors jp.co.odelic.smt.remote03.act.module.ControllerAct in "central" (Tiger) mode:
+ *     03 <dst vaddr 4B> <channel> <own vaddr 4B> <msg id> <args...>
+ */
+import { InputError } from './errors.js';
+
+export const BROADCAST = Buffer.from([0xff, 0xff, 0xff, 0xff]);
+
+// channels
+export const CH_TO_LIGHT = 0x20;
+export const CH_TO_LIGHT_BROADCAST = 0x2a;
+export const CH_PING = 0xfe;
+export const CH_PING_RESPONSE = 0xff;
+
+// message ids (MeshProfile.DATAEVENT_MSGID_*)
+export const MSG_LIGHT = 0xc0; //         SM_BRIGHT_LIGHT
+export const MSG_LIGHT_GROUP = 0xc1; //   SM_BRIGHT_LIGHT_GROUP
+export const MSG_CHANGE_COLOR = 0xe2; //  SM_CHANGE_COLOR (cycle colour preset)
+export const MSG_SCENE_SAVE = 0x40; //    SM_SCENE_IN
+export const MSG_SCENE_PLAY = 0x42; //    SM_SCENE_PLAY
+export const MSG_STATUS = 0x70; //        SM_STATUS
+export const MSG_STATUS_RESPONSES = [0x71, 0x35]; // STATUS_MAIN / STATE_RESPONSE_FD
+
+// special (x, y) pairs
+export const XY_ON = [55, 55];
+export const XY_OFF = [50, 50];
+
+export const X_MAX = 20; // colour: 0 = warm (電球色) ... 20 = cool (昼光色)
+export const Y_MAX = 19; // brightness: 0 = brightest ... 19 = dimmest
+
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+
+/** 0 (warmest) .. 100 (coolest) -> x 0..20 */
+export function colorToX(color) {
+  return clamp(Math.round((color * X_MAX) / 100), 0, X_MAX);
+}
+
+/** 1..100 % -> y 19..0 (same rule as the app: (100 - b) / 5, clamped) */
+export function brightnessToY(brightness) {
+  return clamp(Math.floor((100 - brightness) / 5), 0, Y_MAX);
+}
+
+/** 4-byte vaddr from a Buffer/Uint8Array, a number (little endian) or a hex string ("00000000", "00:00:00:00"). */
+export function vaddr(v) {
+  let b;
+  if (v instanceof Uint8Array) {
+    b = Buffer.from(v);
+  } else if (typeof v === 'number') {
+    if (!Number.isInteger(v) || v < 0 || v > 0xffffffff) throw new InputError(`vaddr out of range: ${v}`);
+    b = Buffer.alloc(4);
+    b.writeUInt32LE(v);
+  } else {
+    const s = String(v).replace(/:/g, '');
+    if (!/^[0-9a-fA-F]*$/.test(s) || s.length % 2) throw new InputError(`invalid vaddr: ${v}`);
+    b = Buffer.from(s, 'hex');
+  }
+  if (b.length !== 4) throw new InputError('vaddr must be 4 bytes');
+  return b;
+}
+
+/** Concatenate Buffers and byte arrays; like Python's bytes(), array values must be integers 0..255. */
+function bytes(...parts) {
+  return Buffer.concat(parts.map((p) => {
+    if (Buffer.isBuffer(p)) return p;
+    for (const v of p) {
+      if (!Number.isInteger(v) || v < 0 || v > 255) throw new InputError(`byte value out of range: ${v}`);
+    }
+    return Buffer.from(p);
+  }));
+}
+
+export function dataEvent(dst, channel, payload) {
+  return bytes([0x03], dst, [channel], payload);
+}
+
+/** ControllerAct.setlight: on/off/colour/brightness for one light or all (broadcast). */
+export function light(own, dst, x, y, index = 0) {
+  const ch = dst.equals(BROADCAST) ? CH_TO_LIGHT_BROADCAST : CH_TO_LIGHT;
+  return dataEvent(dst, ch, bytes(own, [MSG_LIGHT, index, x, y, 0, 0, 0, 0]));
+}
+
+/** ControllerAct.sendgroup_new */
+export function groupLight(own, groupId, x, y) {
+  return dataEvent(BROADCAST, CH_TO_LIGHT, bytes(own, [MSG_LIGHT_GROUP, x, y, 0, 0, 0, 0, 0, 0, groupId]));
+}
+
+export function changeColor(own, dst) {
+  return dataEvent(dst, CH_TO_LIGHT, bytes(own, [MSG_CHANGE_COLOR]));
+}
+
+export function scene(own, index, save, dst = BROADCAST) {
+  const msg = save ? MSG_SCENE_SAVE : MSG_SCENE_PLAY;
+  return dataEvent(dst, CH_TO_LIGHT, bytes(own, [msg, 0, 0, 0, 0, 0, 0, index]));
+}
+
+export function statusRequest(own, dst) {
+  return dataEvent(dst, CH_TO_LIGHT, bytes(own, [MSG_STATUS]));
+}
+
+export function pingAll(own) {
+  return dataEvent(BROADCAST, CH_PING, own);
+}
+
+export class Device {
+  constructor({ vaddr, mac, product, version }) {
+    this.vaddr = vaddr;
+    this.mac = mac;
+    this.product = product;
+    this.version = version;
+  }
+
+  toString() {
+    return `vaddr=${this.vaddr.toString('hex')} mac=${this.mac} product=${this.product} ver=${this.version}`;
+  }
+}
+
+/** MeshCommon.GetPingResponse; `p` is a decrypted type-3 packet with channel 0xFF. */
+export function parsePingResponse(p) {
+  if (p.length < 20 || p[0] !== 0x03 || p[5] !== CH_PING_RESPONSE) return null;
+  const mac = [...p.subarray(6, 12)].reverse().map((b) => b.toString(16).toUpperCase().padStart(2, '0')).join(':');
+  const product = p[16] | (p[17] << 8);
+  return new Device({ vaddr: Buffer.from(p.subarray(12, 16)), mac, product, version: `${product}.${p[18]}.${p[19]}` });
+}
+
+export class LightState {
+  constructor({ vaddr, on, x, y }) {
+    this.vaddr = vaddr;
+    this.on = on;
+    this.x = x;
+    this.y = y;
+  }
+
+  /** 0 = warm .. 100 = cool, null if unknown (light reports a plain "on"). */
+  get color() {
+    return !this.on || this.x > X_MAX ? null : this.x * 5;
+  }
+
+  /** 1..100 %, 0 when off, null if unknown. */
+  get brightness() {
+    if (!this.on) return 0;
+    return this.y > Y_MAX ? null : 100 - this.y * 5;
+  }
+
+  toJSON() {
+    return { vaddr: this.vaddr.toString('hex'), on: this.on, color: this.color, brightness: this.brightness, x: this.x, y: this.y };
+  }
+}
+
+/** Status reply (MeshBlePresenter.syncState): `03 <dst4> <ch> <src4> 71 <x> <y> ...` */
+export function parseStatus(p) {
+  if (p.length < 13 || p[0] !== 0x03 || !MSG_STATUS_RESPONSES.includes(p[10])) return null;
+  const x = p[11];
+  const y = p[12];
+  return new LightState({ vaddr: Buffer.from(p.subarray(6, 10)), on: !(x === XY_OFF[0] && y === XY_OFF[1]), x, y });
+}
+
+/** The app shows "ID:<HomeID><4-char password>", e.g. "ID:12345678" -> { homeid: 1234, password: "5678" }. */
+export function parseAppId(appId) {
+  let s = String(appId).trim();
+  if (s.toUpperCase().startsWith('ID:')) s = s.slice(3);
+  if (s.length < 5) throw new InputError(`ID looks too short: ${JSON.stringify(String(appId))}`);
+  const head = s.slice(0, -4);
+  if (!/^\d+$/.test(head)) throw new InputError(`ID must start with the numeric HomeID: ${JSON.stringify(String(appId))}`);
+  return { homeid: Number(head), password: s.slice(-4) };
+}
+
+/**
+ * HomeID advertised by a mesh node (manufacturer id 0xFFFF, c0/c1 ff 01|02 <homeid LE>).
+ * `manufacturerData` is the raw AD field as noble reports it, i.e. starting with the 2-byte company id.
+ */
+export function advHomeid(manufacturerData) {
+  const m = manufacturerData;
+  if (!m || m.length < 9 || m[0] !== 0xff || m[1] !== 0xff) return null;
+  const v = m.subarray(2);
+  if ((v[0] === 0xc0 || v[0] === 0xc1) && v[1] === 0xff && (v[2] === 1 || v[2] === 2)) return v.readUInt32LE(3);
+  return null;
+}