odelic 0.0.0-stage → 0.2.1

package/src/protocol.ts

@@ -0,0 +1,205 @@
+/**
+ * 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.ts';
+
+/** A light address: 4 bytes, a number (little endian) or a hex string ("00000000", "00:00:00:00"). */
+export type VaddrLike = Uint8Array | number | string;
+
+export const BROADCAST: Buffer = 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: readonly number[] = [0x71, 0x35]; // STATUS_MAIN / STATE_RESPONSE_FD
+
+// special (x, y) pairs
+export const XY_ON = [55, 55] as const;
+export const XY_OFF = [50, 50] as const;
+
+export const X_MAX = 20; // colour: 0 = warm (電球色) ... 20 = cool (昼光色)
+export const Y_MAX = 19; // brightness: 0 = brightest ... 19 = dimmest
+
+const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
+
+/** 0 (warmest) .. 100 (coolest) -> x 0..20 */
+export function colorToX(color: number): number {
+  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: number): number {
+  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. */
+export function vaddr(v: VaddrLike): Buffer {
+  let b: Buffer;
+  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: (Uint8Array | readonly number[])[]): Buffer {
+  return Buffer.concat(parts.map((p) => {
+    if (p instanceof Uint8Array) 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: Uint8Array, channel: number, payload: Uint8Array): Buffer {
+  return bytes([0x03], dst, [channel], payload);
+}
+
+/** ControllerAct.setlight: on/off/colour/brightness for one light or all (broadcast). */
+export function light(own: Uint8Array, dst: Buffer, x: number, y: number, index = 0): Buffer {
+  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: Uint8Array, groupId: number, x: number, y: number): Buffer {
+  return dataEvent(BROADCAST, CH_TO_LIGHT, bytes(own, [MSG_LIGHT_GROUP, x, y, 0, 0, 0, 0, 0, 0, groupId]));
+}
+
+export function changeColor(own: Uint8Array, dst: Uint8Array): Buffer {
+  return dataEvent(dst, CH_TO_LIGHT, bytes(own, [MSG_CHANGE_COLOR]));
+}
+
+export function scene(own: Uint8Array, index: number, save: boolean, dst: Uint8Array = BROADCAST): Buffer {
+  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: Uint8Array, dst: Uint8Array): Buffer {
+  return dataEvent(dst, CH_TO_LIGHT, bytes(own, [MSG_STATUS]));
+}
+
+export function pingAll(own: Uint8Array): Buffer {
+  return dataEvent(BROADCAST, CH_PING, own);
+}
+
+/** A light that answered a mesh ping. */
+export class Device {
+  readonly vaddr: Buffer;
+  readonly mac: string;
+  readonly product: number;
+  readonly version: string;
+
+  constructor({ vaddr, mac, product, version }: { vaddr: Buffer; mac: string; product: number; version: string }) {
+    this.vaddr = vaddr;
+    this.mac = mac;
+    this.product = product;
+    this.version = version;
+  }
+
+  toString(): string {
+    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: Buffer): Device | null {
+  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 interface LightStateJSON {
+  vaddr: string;
+  on: boolean;
+  /** 0 = warm .. 100 = cool, null if unknown */
+  color: number | null;
+  /** 1..100 %, 0 when off, null if unknown */
+  brightness: number | null;
+  x: number;
+  y: number;
+}
+
+/** State reported by one light. */
+export class LightState {
+  readonly vaddr: Buffer;
+  readonly on: boolean;
+  readonly x: number;
+  readonly y: number;
+
+  constructor({ vaddr, on, x, y }: { vaddr: Buffer; on: boolean; x: number; y: number }) {
+    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(): number | null {
+    return !this.on || this.x > X_MAX ? null : this.x * 5;
+  }
+
+  /** 1..100 %, 0 when off, null if unknown. */
+  get brightness(): number | null {
+    if (!this.on) return 0;
+    return this.y > Y_MAX ? null : 100 - this.y * 5;
+  }
+
+  toJSON(): LightStateJSON {
+    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: Buffer): LightState | null {
+  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: string): { homeid: number; password: string } {
+  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: Buffer | null | undefined): number | null {
+  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;
+}

package/src/server.ts

@@ -0,0 +1,195 @@
+/**
+ * Tiny dependency-free HTTP/JSON API on top of Controller.
+ *
+ *     GET  /health
+ *     GET  /lights                      list lights (ping)
+ *     GET  /lights/<target>             state ("all" = every light)
+ *     POST /lights/<target>/on | off
+ *     POST /lights/<target>/light       {"color": 0..100, "brightness": 1..100}
+ *     POST /lights/<target>/night       {"level": 0..2}
+ *     POST /groups/<id>/on | off | light
+ *     POST /scenes/<index>/play | save
+ *
+ * Parameters may be sent as a JSON body or as query parameters. <target> is a light name, "all" or a vaddr.
+ * When a token is configured every request needs `Authorization: Bearer <token>` (or ?token=...).
+ */
+import { createHash, timingSafeEqual } from 'node:crypto';
+import http from 'node:http';
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+import { InputError } from './errors.ts';
+import { log } from './log.ts';
+import { toInt } from './controller.ts';
+import type { Controller } from './controller.ts';
+
+export const LOOPBACK: readonly string[] = ['127.0.0.1', 'localhost', '::1'];
+const MAX_BODY = 65536;
+
+/** The part of Controller the HTTP API uses. */
+export type HttpController = Pick<Controller,
+  'info' | 'lights' | 'status' | 'on' | 'off' | 'setLight' | 'nightLight' | 'group' | 'scene'>;
+
+type Params = Record<string, unknown>;
+
+export class HttpError extends Error {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'HttpError';
+    this.status = status;
+  }
+}
+
+function need(method: string, expected: string): void {
+  if (method !== expected) throw new HttpError(405, `use ${expected}`);
+}
+
+const num = (v: unknown, def: number) => (v ?? def) as number | string;
+
+/** Route one request to the controller. Returns the JSON-able result. */
+export async function dispatch(ctl: HttpController, method: string, path: string, params: Params): Promise<unknown> {
+  let parts: string[];
+  try {
+    parts = path.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean).map(decodeURIComponent);
+  } catch {
+    throw new HttpError(400, 'bad URL encoding');
+  }
+  if (parts.length === 1 && parts[0] === 'health') return { ok: true, ...ctl.info() };
+  if (!parts.length) throw new HttpError(404, 'not found');
+  const [head] = parts;
+  if (head === 'lights') {
+    if (parts.length === 1) {
+      need(method, 'GET');
+      return ctl.lights();
+    }
+    const target = parts[1];
+    if (parts.length === 2) {
+      need(method, 'GET');
+      return ctl.status(target);
+    }
+    need(method, 'POST');
+    const act = parts[2];
+    if (act === 'on') return ctl.on(target);
+    if (act === 'off') return ctl.off(target);
+    if (act === 'light') return ctl.setLight(target, num(params.color, 50), num(params.brightness, 100));
+    if (act === 'night') return ctl.nightLight(target, num(params.level, 0));
+  } else if (head === 'groups' && parts.length === 3) {
+    need(method, 'POST');
+    return ctl.group(toInt(parts[1], 'group id'), parts[2], num(params.color, 50), num(params.brightness, 100));
+  } else if (head === 'scenes' && parts.length === 3 && (parts[2] === 'play' || parts[2] === 'save')) {
+    need(method, 'POST');
+    return ctl.scene(toInt(parts[1], 'scene index'), parts[2] === 'save');
+  }
+  throw new HttpError(404, 'not found');
+}
+
+function readBody(req: IncomingMessage): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const declared = Number(req.headers['content-length'] || 0);
+    if (declared > MAX_BODY) {
+      reject(new HttpError(413, 'body too large'));
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let size = 0;
+    req.on('data', (c: Buffer) => {
+      size += c.length;
+      if (size > MAX_BODY) {
+        reject(new HttpError(413, 'body too large'));
+        req.destroy();
+      } else {
+        chunks.push(c);
+      }
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+const digest = (s: unknown) => createHash('sha256').update(String(s)).digest();
+
+/** A `(req, res)` handler for node:http. */
+export function makeHandler(ctl: HttpController, token: string | null = null) {
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    let status = 200;
+    let payload: unknown;
+    try {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      const params: Params = Object.fromEntries(url.searchParams);
+      const body = await readBody(req);
+      if (body.length) {
+        let data: unknown;
+        try {
+          data = JSON.parse(body.toString('utf8'));
+        } catch {
+          throw new HttpError(400, 'body must be JSON');
+        }
+        if (data && typeof data === 'object' && !Array.isArray(data)) Object.assign(params, data);
+      }
+      if (token) {
+        const auth = req.headers.authorization ?? '';
+        const given = auth.toLowerCase().startsWith('bearer ') ? auth.slice(7) : (params.token ?? '');
+        if (!timingSafeEqual(digest(given), digest(token))) throw new HttpError(401, 'bad or missing token');
+      }
+      delete params.token;
+      payload = await dispatch(ctl, (req.method ?? 'GET').toUpperCase(), url.pathname, params);
+    } catch (e) {
+      const err = e as Error;
+      if (err instanceof HttpError) {
+        status = err.status;
+      } else if (err instanceof InputError) {
+        status = 400;
+      } else { // BLE / login failures
+        status = 502;
+        log.error('request failed:', err);
+      }
+      payload = { ok: false, error: err instanceof HttpError || err instanceof InputError ? err.message : `${err.name}: ${err.message}` };
+    }
+    const data = Buffer.from(JSON.stringify(payload ?? null), 'utf8');
+    if (res.headersSent || res.destroyed) return;
+    res.writeHead(status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Content-Length': data.length,
+      Connection: 'close',
+    });
+    res.end(data);
+  };
+}
+
+export interface ServeOptions {
+  host?: string;
+  port?: number;
+  /** bearer token; required when listening on a non-loopback address */
+  token?: string | null;
+}
+
+/** Start the HTTP API. Resolves to the listening server; closing the server also closes the controller. */
+export async function serve(ctl: Controller, { host = '127.0.0.1', port = 8765, token = null }: ServeOptions = {}): Promise<Server> {
+  if (!LOOPBACK.includes(host) && !token) {
+    throw new InputError(`refusing to listen on ${host} without a token (use --token or ODELIC_HTTP_TOKEN)`);
+  }
+  const server = http.createServer(makeHandler(ctl, token));
+  server.headersTimeout = 10_000;
+  server.requestTimeout = 10_000 + 60_000; // BLE operations (scan + login) can take a while
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => {
+      server.removeListener('error', reject);
+      resolve();
+    });
+  });
+  server.on('close', () => {
+    ctl.close().catch(() => {});
+  });
+  const addr = server.address() as AddressInfo;
+  log.warning(`HTTP API on http://${host}:${addr.port} (${ctl.keepConnected
+    ? 'keeping the BLE link open' : `idle disconnect after ${ctl.idleTimeout}s`})`);
+  if (ctl.keepConnected) {
+    ctl.connect()
+      .then(() => log.warning(`connected via ${ctl.mesh.nodeName}`))
+      .catch((e: Error) => log.warning(`initial connect failed: ${e.message}`)); // the next request retries
+  }
+  return server;
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = '0.2.1';