amaran-light-cli 1.10.0 → 1.12.0

package/scripts/ble-probe.ts

@@ -0,0 +1,45 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { importMesh } from '../src/ble/setup.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { cctPacket, powerPacket } from '../src/ble/telink.js';
+import { MeshTransport } from '../src/ble/transport.js';
+import { captureWebcam } from './webcam.js';
+
+if (process.argv[2] === 'import') {
+  importMesh(process.argv[3]);
+} else {
+  const config = loadMeshConfig();
+  const crypto = new MeshCrypto(config.netKey, config.appKey);
+  const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+  const transport = new MeshTransport(config, sequence, true);
+  try {
+    await transport.connect();
+    if (process.argv[2] === 'test-desk') {
+      const light = config.lights.find((entry) => entry.key === 'desk');
+      if (!light) throw new Error('Desk fixture not configured');
+      try {
+        await transport.send(light.address, cctPacket(3200, 10));
+        await delay(300);
+        await transport.send(light.address, powerPacket(true));
+        await delay(300);
+        console.log('ON state', await transport.readState(light.address));
+        console.log(captureWebcam(`ble-desk-on-${Date.now()}`));
+      } finally {
+        await transport.send(light.address, powerPacket(false));
+        await delay(300);
+        console.log('OFF state', await transport.readState(light.address));
+      }
+      console.log(captureWebcam(`ble-desk-off-${Date.now()}`));
+    } else {
+      for (const light of config.lights) {
+        console.log(light.name, await transport.readState(light.address));
+        console.log('Fan', await transport.readFan(light.address));
+      }
+    }
+  } finally {
+    await transport.disconnect();
+    sequence.close();
+  }
+  process.exit(0);
+}

package/scripts/calibrate-webcam.ts

@@ -0,0 +1,152 @@
+import { readdirSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import { MeshCrypto } from '../src/ble/crypto.js';
+import { loadMeshConfig, meshDirectory, SequenceStore } from '../src/ble/storage.js';
+import { cctPacket, type FixtureState, powerPacket } from '../src/ble/telink.js';
+import { MeshTransport } from '../src/ble/transport.js';
+import { type CameraRegion, captureWebcam, imagePixels, regionsFile } from './webcam.js';
+
+function locateLight(dark: Buffer, lit: Buffer, name: string): CameraRegion {
+  const width = 320;
+  const height = 180;
+  const mask = new Uint8Array(width * height);
+  for (let y = 1; y < height - 1; y++)
+    for (let x = 1; x < width - 1; x++) {
+      let bright = true;
+      for (let dy = -1; dy <= 1; dy++)
+        for (let dx = -1; dx <= 1; dx++) {
+          const offset = ((y + dy) * 4 * 1280 + (x + dx) * 4) * 3;
+          const light = (lit[offset] + lit[offset + 1] + lit[offset + 2]) / 3;
+          const before = (dark[offset] + dark[offset + 1] + dark[offset + 2]) / 3;
+          if (light < 248 || light - before < 65) bright = false;
+        }
+      if (bright) mask[y * width + x] = 1;
+    }
+  const candidates: { count: number; x: number; y: number; width: number; height: number }[] = [];
+  for (let start = 0; start < mask.length; start++) {
+    if (!mask[start]) continue;
+    const queue = [start];
+    mask[start] = 0;
+    let minX = width,
+      maxX = 0,
+      minY = height,
+      maxY = 0;
+    for (let i = 0; i < queue.length; i++) {
+      const index = queue[i],
+        x = index % width,
+        y = Math.floor(index / width);
+      minX = Math.min(minX, x);
+      maxX = Math.max(maxX, x);
+      minY = Math.min(minY, y);
+      maxY = Math.max(maxY, y);
+      for (const next of [
+        index - width,
+        index + width,
+        ...(x > 0 ? [index - 1] : []),
+        ...(x < width - 1 ? [index + 1] : []),
+      ]) {
+        if (next >= 0 && next < mask.length && mask[next]) {
+          mask[next] = 0;
+          queue.push(next);
+        }
+      }
+    }
+    const w = maxX - minX + 1,
+      h = maxY - minY + 1;
+    if (queue.length >= 8 && w / h > 0.35 && w / h < 2.8 && w < 70 && h < 70) {
+      candidates.push({ count: queue.length, x: (minX + maxX) * 2, y: (minY + maxY) * 2, width: w * 4, height: h * 4 });
+    }
+  }
+  candidates.sort((a, b) => b.count - a.count);
+  const best = candidates[0];
+  if (!best || (candidates[1] && candidates[1].count > best.count * 0.7))
+    throw new Error(`Cannot identify a unique emitting fixture for ${name}: ${JSON.stringify(candidates)}`);
+  const size = Math.max(8, Math.min(24, Math.floor(Math.min(best.width, best.height) / 2)));
+  return { name, x: Math.round(best.x - size / 2), y: Math.round(best.y - size / 2), width: size, height: size };
+}
+
+const config = loadMeshConfig();
+if (process.argv.includes('--reuse')) {
+  const capture = readdirSync('artifacts/webcam')
+    .filter((name) => /^calibration-\d+-off\.png$/.test(name))
+    .sort()
+    .at(-1);
+  if (!capture) throw new Error('No saved calibration captures');
+  const prefix = `artifacts/webcam/${capture.replace(/-off\.png$/, '')}`;
+  const dark = imagePixels(`${prefix}-off.png`);
+  const regions = config.lights.map((light) => locateLight(dark, imagePixels(`${prefix}-${light.key}.png`), light.key));
+  writeFileSync(
+    regionsFile,
+    JSON.stringify(
+      { cameraIndex: process.env.AMARAN_CAMERA_INDEX ?? '0', capturedAt: new Date().toISOString(), regions },
+      null,
+      2
+    ),
+    { mode: 0o600 }
+  );
+  console.log(prefix, regions);
+  process.exit(0);
+}
+const crypto = new MeshCrypto(config.netKey, config.appKey);
+const sequence = new SequenceStore(meshDirectory(), crypto.networkId.toString('hex'), config.source);
+const transport = new MeshTransport(config, sequence);
+const original = new Map<number, FixtureState>();
+const regions: CameraRegion[] = [];
+const errors: unknown[] = [];
+try {
+  await transport.connect();
+  for (const light of config.lights) {
+    const state = await transport.readState(light.address);
+    if (state.mode !== 'cct')
+      throw new Error('Camera calibration currently requires CCT mode so all settings can be restored');
+    original.set(light.address, state);
+  }
+  for (const light of config.lights) await transport.send(light.address, powerPacket(false));
+  await delay(300);
+  const stamp = Date.now();
+  const dark = imagePixels(captureWebcam(`calibration-${stamp}-off`));
+  for (const light of config.lights) {
+    await transport.send(light.address, cctPacket(3200, 10, 0));
+    await delay(300);
+    const frame = captureWebcam(`calibration-${stamp}-${light.key}`);
+    regions.push(locateLight(dark, imagePixels(frame), light.key));
+    await transport.send(light.address, powerPacket(false));
+    await delay(300);
+  }
+  writeFileSync(
+    regionsFile,
+    JSON.stringify(
+      { cameraIndex: process.env.AMARAN_CAMERA_INDEX ?? '0', capturedAt: new Date().toISOString(), regions },
+      null,
+      2
+    ),
+    { mode: 0o600 }
+  );
+  console.log('Identified fixture regions:', regions);
+} catch (error) {
+  errors.push(error);
+} finally {
+  for (const light of config.lights) {
+    const state = original.get(light.address);
+    if (!state) continue;
+    try {
+      await transport.send(light.address, cctPacket(state.cct ?? 3200, state.intensity, state.gm ?? 0));
+      await delay(200);
+      await transport.send(light.address, powerPacket(!state.sleep));
+      const actual = await transport.readState(light.address);
+      if (
+        actual.cct !== state.cct ||
+        actual.intensity !== state.intensity ||
+        actual.sleep !== state.sleep ||
+        (light.model === '150c' && actual.gm !== state.gm)
+      )
+        errors.push(new Error(`Failed to restore ${light.key}`));
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  await transport.disconnect();
+  sequence.close();
+}
+if (errors.length) throw new AggregateError(errors, 'Camera calibration failed');
+process.exit(0);

package/scripts/desktop-reference.ts

@@ -0,0 +1,85 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import WebSocket from 'ws';
+import { captureWebcam } from './webcam.js';
+
+const ws = new WebSocket(process.env.AMARAN_REFERENCE_WS ?? 'ws://127.0.0.1:12345');
+const pending = new Map<string, { resolve: (value: unknown) => void; reject: (error: Error) => void }>();
+ws.on('message', (raw) => {
+  const message = JSON.parse(raw.toString());
+  const key = `${message.request?.type}:${message.request?.node_id ?? ''}`;
+  const request = pending.get(key);
+  if (!request) return;
+  if (message.code !== 0) request.reject(new Error(message.message));
+  else request.resolve(message.data?.data ?? message.data);
+});
+
+async function command(type: string, nodeId?: string, args?: Record<string, unknown>): Promise<unknown> {
+  const key = `${type}:${nodeId ?? ''}`;
+  if (pending.has(key)) throw new Error(`Concurrent duplicate command: ${key}`);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await new Promise((resolve, reject) => {
+      pending.set(key, { resolve, reject });
+      timer = setTimeout(() => reject(new Error(`Desktop response timeout: ${key}`)), 8000);
+      ws.send(JSON.stringify({ version: 1, client_id: 'hardware-reference', type, node_id: nodeId, args }));
+    });
+  } finally {
+    clearTimeout(timer);
+    pending.delete(key);
+  }
+}
+
+const fixtures = [
+  { key: 'desk', nodeId: '400Q5-11B2F8' },
+  { key: 'front', nodeId: '400Q5-119B16' },
+  { key: 'back', nodeId: '400J5-F2C008' },
+];
+
+try {
+  await new Promise<void>((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('Desktop connection timeout')), 8000);
+    ws.once('open', () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+    ws.once('error', (error) => {
+      clearTimeout(timeout);
+      reject(error);
+    });
+  });
+  mkdirSync('artifacts', { recursive: true });
+  const snapshot = [];
+  for (const fixture of fixtures) {
+    snapshot.push({
+      ...fixture,
+      sleep: await command('get_sleep', fixture.nodeId),
+      intensity: await command('get_intensity', fixture.nodeId),
+      cct: await command('get_cct', fixture.nodeId),
+    });
+  }
+  writeFileSync(`artifacts/desktop-state-${Date.now()}.json`, JSON.stringify(snapshot, null, 2), { mode: 0o600 });
+  console.log(JSON.stringify(snapshot, null, 2));
+  if (process.argv[2] === 'reference') {
+    const stamp = Date.now();
+    for (const fixture of fixtures) {
+      await command('set_intensity', fixture.nodeId, { intensity: 10 });
+      await command('set_sleep', fixture.nodeId, { sleep: true });
+    }
+    await delay(1000);
+    console.log(captureWebcam(`desktop-${stamp}-all-off`));
+    for (const fixture of fixtures) {
+      await command('set_cct', fixture.nodeId, { cct: 3200, intensity: 10 });
+      await command('set_sleep', fixture.nodeId, { sleep: false });
+      await delay(1000);
+      console.log(captureWebcam(`desktop-${stamp}-${fixture.key}-3200-1pct`));
+      await command('set_cct', fixture.nodeId, { cct: 6500, intensity: 10 });
+      await delay(1000);
+      console.log(captureWebcam(`desktop-${stamp}-${fixture.key}-6500-1pct`));
+      await command('set_sleep', fixture.nodeId, { sleep: true });
+    }
+    console.log('Reference complete. All fixtures left asleep at 1%; original state saved in artifacts.');
+  }
+} finally {
+  ws.close();
+}

package/scripts/webcam.ts

@@ -0,0 +1,129 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+
+export const RegionSchema = z
+  .object({
+    name: z.string(),
+    x: z.number().int().min(0),
+    y: z.number().int().min(0),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+  })
+  .refine((r) => r.x + r.width <= 1280 && r.y + r.height <= 720, 'Camera ROI is outside the frame');
+export type CameraRegion = z.infer<typeof RegionSchema>;
+export const regionsFile = path.resolve('artifacts/webcam/regions.json');
+
+export function imagePixels(filename: string): Buffer {
+  const pixels = execFileSync(
+    'ffmpeg',
+    ['-hide_banner', '-loglevel', 'error', '-i', filename, '-f', 'rawvideo', '-pix_fmt', 'rgb24', '-'],
+    { timeout: 10_000, maxBuffer: 1280 * 720 * 3 + 1024 }
+  );
+  if (pixels.length !== 1280 * 720 * 3) throw new Error('Unexpected camera frame dimensions');
+  return pixels;
+}
+
+export function measureRegion(rgb: Buffer, region: CameraRegion) {
+  const sum = [0, 0, 0];
+  let clipped = 0;
+  for (let y = region.y; y < region.y + region.height; y++) {
+    for (let x = region.x; x < region.x + region.width; x++) {
+      const offset = (y * 1280 + x) * 3;
+      for (let channel = 0; channel < 3; channel++) sum[channel] += rgb[offset + channel];
+      if (Math.max(rgb[offset], rgb[offset + 1], rgb[offset + 2]) >= 250) clipped++;
+    }
+  }
+  const pixels = region.width * region.height;
+  const centerX = region.x + region.width / 2;
+  const centerY = region.y + region.height / 2;
+  const inner = Math.max(region.width, region.height);
+  const outer = inner * 2;
+  const halo = [0, 0, 0];
+  let haloPixels = 0;
+  // The directly facing emitter clips white; its surrounding halo retains color information.
+  for (let y = Math.max(0, Math.floor(centerY - outer)); y < Math.min(720, centerY + outer); y++) {
+    for (let x = Math.max(0, Math.floor(centerX - outer)); x < Math.min(1280, centerX + outer); x++) {
+      const radius = (x - centerX) ** 2 + (y - centerY) ** 2;
+      if (radius < inner ** 2 || radius > outer ** 2) continue;
+      const offset = (y * 1280 + x) * 3;
+      if (Math.min(rgb[offset], rgb[offset + 1], rgb[offset + 2]) >= 245) continue;
+      for (let channel = 0; channel < 3; channel++) halo[channel] += rgb[offset + channel];
+      haloPixels++;
+    }
+  }
+  return {
+    ...region,
+    rgb: sum.map((value) => value / pixels),
+    clippedFraction: clipped / pixels,
+    haloRgb: haloPixels ? halo.map((value) => value / haloPixels) : undefined,
+    haloPixels,
+  };
+}
+
+export function captureWebcam(label: string): string {
+  if (!/^[a-zA-Z0-9_-]+$/.test(label)) throw new Error('Camera label must contain only letters, numbers, - or _');
+  const directory = path.resolve('artifacts/webcam');
+  mkdirSync(directory, { recursive: true });
+  chmodSync(directory, 0o700);
+  const output = path.join(directory, `${label}.png`);
+  execFileSync(
+    'ffmpeg',
+    [
+      '-hide_banner',
+      '-loglevel',
+      'error',
+      '-f',
+      'avfoundation',
+      '-pixel_format',
+      'nv12',
+      '-framerate',
+      '30',
+      '-video_size',
+      '1280x720',
+      '-i',
+      `${process.env.AMARAN_CAMERA_INDEX ?? '0'}:none`,
+      '-vf',
+      "select='gte(t,3)'",
+      '-frames:v',
+      '1',
+      '-update',
+      '1',
+      '-n',
+      output,
+    ],
+    { timeout: 20_000, stdio: ['ignore', 'ignore', 'pipe'] }
+  );
+  chmodSync(output, 0o600);
+  const rgb = imagePixels(output);
+  const calibration = existsSync(regionsFile)
+    ? z
+        .object({ cameraIndex: z.string(), regions: z.array(RegionSchema) })
+        .parse(JSON.parse(readFileSync(regionsFile, 'utf8')))
+    : undefined;
+  if (calibration && calibration.cameraIndex !== (process.env.AMARAN_CAMERA_INDEX ?? '0'))
+    throw new Error('Camera calibration belongs to a different camera');
+  const regions = (calibration?.regions ?? []).map((region) => measureRegion(rgb, region));
+  writeFileSync(
+    output.replace(/\.png$/, '.json'),
+    JSON.stringify(
+      {
+        capturedAt: new Date().toISOString(),
+        note: calibration
+          ? 'Calibrated fixture ROIs; automatic exposure/white balance, not a lux or CCT meter. Recalibrate after moving equipment.'
+          : 'Uncalibrated: run scripts/calibrate-webcam.ts before optical assertions.',
+        regions,
+      },
+      null,
+      2
+    ),
+    { mode: 0o600 }
+  );
+  return output;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  console.log(captureWebcam(process.argv[2] ?? `capture-${Date.now()}`));
+}

package/dist/__tests__/lightControl.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=lightControl.test.d.ts.map

package/dist/__tests__/lightControl.test.d.ts.map

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