odelic 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rbstxt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# odelic.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An **unofficial** Node.js library for controlling ODELIC Bluetooth lights from a PC. This is the JavaScript port of the Python package [odelic.py](https://github.com/rbstxt/odelic.py), with the same features.
+
+It was built by analyzing the communication protocol of the official Android app (`jp.co.odelic.smt.remote10` v1.10.39). It targets devices that use the Pairlink connected-mesh protocol. It does not use the cloud; it controls the lights directly and locally over BLE.
+
+- The only BLE dependency is [@stoprocent/noble](https://github.com/stoprocent/noble). Encryption (AES-128) uses Node's built-in `crypto`.
+- Tested on macOS. It should also work in any environment noble supports (Linux / Windows).
+- The config file (`~/.config/odelic/config.json`) has the same format as the Python version and can be shared with it.
+- This tool is not endorsed by the manufacturer. Use it at your own risk.
+
+## Setup
+
+Requires Node.js 20 or later.
+
+```sh
+npm install odelic
+# To use the MCP server, also install these
+npm install @modelcontextprotocol/sdk zod
+```
+
+For development (from this repository):
+
+```sh
+npm install
+npm test
+```
+
+### Required information: the app ID
+
+The app's menu screen shows something like `ID:12345678`. It is **the HomeID followed by the password (the last 4 characters)**. In this example the HomeID is 1234 and the password is `5678`.
+
+```sh
+odelic setup --id 12345678        # save it to the config file (permissions 600)
+# or specify it each time with --id / the ODELIC_ID environment variable
+```
+
+## CLI
+
+```sh
+odelic scan                                   # find nearby mesh nodes (no login)
+odelic lights                                 # list the lights in the mesh (vaddr / MAC / product code)
+odelic on                                     # turn all on (restores the previous color and brightness)
+odelic off                                    # turn all off
+odelic light --color 0 --brightness 100       # warm (電球色) at full brightness
+odelic light --color 100 --brightness 30      # cool (昼光色) at 30%
+odelic night --level 0                        # night light (0-2)
+odelic status                                 # on/off, color and brightness of every light
+odelic name add リビング 00000000              # give a light a name (vaddr from `lights`)
+odelic off リビング                            # control a single light by name or vaddr
+odelic group 1 on                             # per group (the group ID is set in the app)
+odelic scene save 1 / odelic scene play 1     # save and recall scenes
+odelic -v ...                                 # show sent and received packets
+```
+
+### Auto-disconnect or stay connected
+
+A mesh node **can connect to only one controller at a time**. To keep the phone app usable, the HTTP API and MCP server drop the BLE connection after 60 seconds of inactivity by default. If you don't use the phone app, you can keep the connection open.
+
+```sh
+odelic setup --keep-connected     # always stay connected
+odelic setup --idle 300           # disconnect after 300 idle seconds
+```
+
+Priority: command option (`--idle` / `--keep-connected`) → environment variable `ODELIC_IDLE_TIMEOUT` (`0` keeps the connection) → config file → default 60 seconds.
+
+## Using it as a library
+
+```js
+import { OdelicMesh } from 'odelic';
+
+const mesh = new OdelicMesh(process.env.ODELIC_ID);
+await mesh.connect();
+try {
+  await mesh.setLight({ color: 0, brightness: 100 }); // 0 = warm .. 100 = cool
+  for (const d of await mesh.devices()) console.log(String(d));
+  console.log((await mesh.status('00000000'))?.toJSON());
+  await mesh.off();
+} finally {
+  await mesh.disconnect();
+}
+```
+
+| Method | Description |
+|---|---|
+| `on(target)` / `off(target)` | Turn on / off. Omit `target` (vaddr) to target every light |
+| `setLight({color, brightness, target, x, y})` | Set color and brightness. Raw values x (0–20) / y (0–19, 0 is brightest) also work |
+| `nightLight(level, target)` | Night light (the 3 dimmest warm levels) |
+| `setGroup(groupId, {color, brightness, on})` | Per-group control |
+| `changeColor(target)` | Cycle color presets (supported models only) |
+| `saveScene(i)` / `playScene(i)` | Save and recall scenes |
+| `devices()` | List the lights in the mesh via ping |
+| `status(target)` | Query state (`LightState`: `on` / `color` / `brightness`) |
+| `send(packet)` | Encrypt and send any type-3 packet (see `protocol`) |
+| `addListener(cb)` | Receive every incoming packet, decrypted |
+
+`Controller` is a higher-level class that handles name resolution, auto connect/reconnect, and idle disconnect (used internally by the CLI, HTTP, and MCP).
+
+```js
+import { Controller } from 'odelic';
+
+const ctl = new Controller();               // ID from ODELIC_ID / config file
+await ctl.setLight('リビング', 0, 100);      // target, color, brightness
+console.log(await ctl.status('all'));
+await ctl.close();
+```
+
+Timeouts and the idle duration are all given in **seconds**, matching the Python version and the config file.
+
+## HTTP API
+
+```sh
+odelic serve                          # http://127.0.0.1:8765
+odelic serve --keep-connected         # connect at startup and keep the connection
+odelic serve --host 0.0.0.0 --token s3cret   # a token is required to listen beyond localhost
+```
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/health` | Connection status |
+| GET | `/lights` | List lights |
+| GET | `/lights/<target>` | State (`all` = every light) |
+| POST | `/lights/<target>/on` · `/off` | Turn 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` | Group control |
+| POST | `/scenes/<index>/play` · `/save` | Scenes |
+
+Parameters can be passed as a JSON body or as query parameters. When a token is set, use `Authorization: Bearer <token>` (or `?token=`).
+
+```sh
+curl -X POST localhost:8765/lights/リビング/light -d '{"color": 0, "brightness": 80}'
+```
+
+## MCP server (for AI assistants)
+
+This lets Claude and other AI tools control the lights. It requires `@modelcontextprotocol/sdk` and `zod`.
+
+```sh
+claude mcp add odelic -e ODELIC_ID=12345678 -- npx -y -p odelic -p @modelcontextprotocol/sdk -p zod odelic-mcp
+```
+
+Configuration file example (Claude Desktop, etc.):
+
+```json
+{
+  "mcpServers": {
+    "odelic": {
+      "command": "npx",
+      "args": ["-y", "-p", "odelic", "-p", "@modelcontextprotocol/sdk", "-p", "zod", "odelic-mcp"],
+      "env": { "ODELIC_ID": "12345678" }
+    }
+  }
+}
+```
+
+To run it from a local checkout, use `"command": "node", "args": ["/path/to/odelic-js/bin/odelic-mcp.js"]`.
+
+Tools: `list_lights` `light_status` `turn_on` `turn_off` `set_light` `night_light` `control_group` `play_scene` `save_scene` `name_light` `forget_light_name`
+
+## Notes
+
+- If the phone app is connected, you'll get `node is already in use by another controller`. Close the app or turn off Bluetooth on the phone and try again.
+- On macOS, the first run asks for Bluetooth permission for the terminal (or whatever app runs it).
+- **Registering new lights** is not supported. The app registers lights by having the phone broadcast a custom-format signal, and macOS's standard Bluetooth stack cannot broadcast that format. Register lights with the app.
+
+## Protocol overview
+
+| Item | Details |
+|---|---|
+| GATT service | `9e5d1e47-5c13-43a0-8635-82adffc0386f` (write `…ffc1…` / notify `…ffc2…`) |
+| Key | An AES-128 key made of the 8 bytes formed by interleaving the HomeID (4B, little endian) and the password (4B) one byte at a time, followed by `"LOGINKEY"` or `"EVENTKEY"` |
+| Login | Send `01 20` → node returns `02 20 + AES_L(homeid, session4)` → reply with `01 16 03 + AES_L(homeid, pwd, session4)` → `02 16 00` means success (`08` means another device is connected) → `01 0a <own vaddr>` assigns your address |
+| Data | Plaintext `03 <dst4> <ch> <payload>` becomes `06 <dst4> <ch> XOR(AES_E(pkcs7(payload)), session4)` |
+| Light command | `<own vaddr> C0 <index> <x> <y> 00 00 00 00`, ch=0x20 (0x2A when broadcasting to all). x=55,y=55 turns on, 50,50 turns off |
+
+The tests use test vectors generated by running the original app's native library in an emulator (the same ones as the Python version; see `tools/native_oracle.py` in odelic.py).
+
+## Releasing
+
+Publishing a GitHub release runs `.github/workflows/publish.yml`, which publishes to npm via npm Trusted Publishing (OIDC) — no token needed.
+
+1. Bump the version in `package.json` and `src/version.js`, then push
+2. Create a GitHub release with the tag `v<version>` (e.g. `v0.2.1`)
+
+## License
+
+MIT License ([LICENSE](LICENSE))

package/bin/odelic-mcp.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+const code = await main(['mcp']);
+if (code !== null) process.exit(code);

package/bin/odelic.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+const code = await main();
+// noble keeps native handles open after use, so exit explicitly (null = long-running, e.g. `odelic mcp`)
+if (code !== null) process.exit(code);

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "odelic",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Unofficial Node.js library for ODELIC Bluetooth lights (Pairlink connected-mesh)",
+  "type": "module",
+  "license": "MIT",
+  "author": "rbstxt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rbstxt/odelic.js.git"
+  },
+  "homepage": "https://github.com/rbstxt/odelic.js#readme",
+  "bugs": {
+    "url": "https://github.com/rbstxt/odelic.js/issues"
+  },
+  "keywords": [
+    "odelic",
+    "bluetooth",
+    "ble",
+    "mesh",
+    "lighting",
+    "smart-home",
+    "mcp"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./mcp": "./src/mcp.js",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "odelic": "bin/odelic.js",
+    "odelic-mcp": "bin/odelic-mcp.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@stoprocent/noble": "^2.8.0"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "@types/node": "^24.19.2",
+    "typescript": "^7.0.2",
+    "zod": "^4.1.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cli.js

@@ -0,0 +1,253 @@
+/** odelic command line.  `odelic setup --id <APP_ID>` once, then e.g. `odelic off`, `odelic light living --color 0`. */
+import { setTimeout as sleep } from 'node:timers/promises';
+import { parseArgs } from 'node:util';
+
+import { InputError, OdelicError } from './errors.js';
+import { log, setLogLevel } from './log.js';
+import { findNodes } from './client.js';
+import { Config, configPath, parseIdle } from './config.js';
+import { Controller } from './controller.js';
+import { parseAppId } from './protocol.js';
+import { VERSION } from './version.js';
+
+const HELP = `usage: odelic [--id ID] [--node NODE] [-v] <command> [...]
+
+Control ODELIC Bluetooth lights.
+
+global options:
+  --id ID            ID shown in the app (ID:xxxx); default: $ODELIC_ID or the config file
+  --node NODE        BLE name/address of the node to connect through
+  -v, --verbose      show BLE packets
+  -h, --help         show this help
+  --version          show the version
+
+commands:
+  setup [--id ID] [--node NODE] [--idle SECONDS | --keep-connected]
+                     save the app ID (and optionally a node / connection mode) to the config file
+  scan               list nearby mesh nodes (no login)
+  lights             list lights in the mesh (alias: devices)
+  on [TARGET]        turn on (previous colour/brightness)
+  off [TARGET]       turn off
+  light [TARGET] [--color 0..100] [--brightness 1..100]
+                     turn on with colour (0 = warm 電球色 .. 100 = cool 昼光色) and brightness
+  night [TARGET] [--level 0..2]
+                     night light
+  status [TARGET]    show on/off, colour and brightness
+  group ID on|off|light [--color N] [--brightness N]
+                     control a group (id as configured in the app)
+  scene save|play INDEX
+                     save or play a scene
+  name add NAME VADDR | name rm NAME | name list
+                     manage light names
+  serve [--host H] [--port P] [--token T] [--idle SECONDS | --keep-connected]
+                     run the HTTP API (token default: $ODELIC_HTTP_TOKEN)
+  mcp                run the MCP server on stdio (needs @modelcontextprotocol/sdk and zod)
+
+TARGET is a light name, a vaddr or "all" (default).`;
+
+const OPTIONS = {
+  id: { type: 'string' },
+  node: { type: 'string' },
+  verbose: { type: 'boolean', short: 'v' },
+  help: { type: 'boolean', short: 'h' },
+  version: { type: 'boolean' },
+  idle: { type: 'string' },
+  'keep-connected': { type: 'boolean' },
+  color: { type: 'string' },
+  brightness: { type: 'string' },
+  level: { type: 'string' },
+  host: { type: 'string' },
+  port: { type: 'string' },
+  token: { type: 'string' },
+};
+
+/** Which options each command accepts (besides the global ones). */
+const COMMAND_OPTIONS = {
+  setup: ['idle', 'keep-connected'],
+  scan: [],
+  lights: [],
+  devices: [],
+  on: [],
+  off: [],
+  light: ['color', 'brightness'],
+  night: ['level'],
+  status: [],
+  group: ['color', 'brightness'],
+  scene: [],
+  name: [],
+  serve: ['host', 'port', 'token', 'idle', 'keep-connected'],
+  mcp: [],
+};
+const GLOBAL = ['id', 'node', 'verbose', 'help', 'version'];
+
+function intArg(v, name, { min = -Infinity, max = Infinity, def } = {}) {
+  if (v === undefined) return def;
+  if (!/^-?\d+$/.test(v)) throw new InputError(`--${name}: invalid int value: '${v}'`);
+  const n = Number(v);
+  if (n < min || n > max) throw new InputError(`--${name}: must be between ${min} and ${max}`);
+  return n;
+}
+
+function choice(v, name, choices) {
+  if (!choices.includes(v)) throw new InputError(`${name}: expected one of ${choices.join(', ')} (got ${v === undefined ? 'nothing' : `'${v}'`})`);
+  return v;
+}
+
+/** Parse argv into `{cmd, args, opts}`; throws InputError on bad usage. */
+export function parseCli(argv) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+  } catch (e) {
+    throw new InputError(e.message);
+  }
+  const { values: o, positionals } = parsed;
+  if (o.help || o.version) return { cmd: o.help ? 'help' : 'version', args: [], opts: o };
+  const [cmd, ...args] = positionals;
+  if (!cmd) throw new InputError('missing command (see odelic --help)');
+  if (!(cmd in COMMAND_OPTIONS)) throw new InputError(`unknown command '${cmd}' (see odelic --help)`);
+  for (const k of Object.keys(o)) {
+    if (!GLOBAL.includes(k) && !COMMAND_OPTIONS[cmd].includes(k)) throw new InputError(`${cmd}: unrecognized option --${k}`);
+  }
+  if (o.idle !== undefined && o['keep-connected']) throw new InputError('--idle and --keep-connected are mutually exclusive');
+  if (o.idle !== undefined) parseIdle(o.idle); // validate early
+  const maxArgs = { on: 1, off: 1, light: 1, night: 1, status: 1, group: 2, scene: 2, name: 3 }[cmd] ?? 0;
+  if (args.length > maxArgs) throw new InputError(`${cmd}: unexpected argument '${args[maxArgs]}'`);
+  return { cmd, args, opts: o };
+}
+
+function idleValue(o) {
+  return o['keep-connected'] ? 0 : parseIdle(o.idle);
+}
+
+function show(obj) {
+  console.log(typeof obj === 'string' ? obj : JSON.stringify(obj, null, 2));
+}
+
+async function runBle(cmd, args, o, cfg) {
+  if (cmd === 'scan') {
+    const aid = cfg.appId(o.id);
+    const homeid = aid ? parseAppId(aid).homeid : null;
+    for (const n of await findNodes({ homeid })) {
+      console.log(`${String(n.name).padEnd(20)} ${n.address}  HomeID=${n.homeid}  rssi=${n.rssi}`);
+    }
+    return;
+  }
+
+  if (cmd === 'serve') {
+    const { serve } = await import('./server.js');
+    const ctl = new Controller(o.id, { node: o.node, config: cfg, idleTimeout: idleValue(o) });
+    const server = await serve(ctl, {
+      host: o.host ?? '127.0.0.1',
+      port: intArg(o.port, 'port', { min: 0, max: 65535, def: 8765 }),
+      token: o.token ?? process.env.ODELIC_HTTP_TOKEN ?? null,
+    });
+    await new Promise((resolve) => {
+      const stop = () => server.close(resolve);
+      process.once('SIGINT', stop);
+      process.once('SIGTERM', stop);
+    });
+    await ctl.close();
+    return;
+  }
+
+  const target = args[0] ?? 'all';
+  const ctl = new Controller(o.id, { node: o.node, config: cfg, idleTimeout: 0 });
+  try {
+    if (cmd === 'lights' || cmd === 'devices') {
+      for (const d of await ctl.lights()) {
+        if (d.online) console.log(`${(d.name ?? '-').padEnd(12)} vaddr=${d.vaddr} mac=${d.mac} product=${d.product} ver=${d.version}`);
+        else console.log(`${d.name.padEnd(12)} vaddr=${d.vaddr} (offline)`);
+      }
+      return;
+    }
+    if (cmd === 'on') show(await ctl.on(target));
+    else if (cmd === 'off') show(await ctl.off(target));
+    else if (cmd === 'light') {
+      show(await ctl.setLight(target, intArg(o.color, 'color', { def: 50 }), intArg(o.brightness, 'brightness', { def: 100 })));
+    } else if (cmd === 'night') show(await ctl.nightLight(target, intArg(o.level, 'level', { min: 0, max: 2, def: 0 })));
+    else if (cmd === 'status') show(await ctl.status(target));
+    else if (cmd === 'group') {
+      const id = intArg(args[0], 'group_id');
+      if (id === undefined) throw new InputError('group: missing group id');
+      show(await ctl.group(id, choice(args[1], 'group action', ['on', 'off', 'light']),
+        intArg(o.color, 'color', { def: 50 }), intArg(o.brightness, 'brightness', { def: 100 })));
+    } else if (cmd === 'scene') {
+      const action = choice(args[0], 'scene action', ['save', 'play']);
+      const index = intArg(args[1], 'index');
+      if (index === undefined) throw new InputError('scene: missing index');
+      show(await ctl.scene(index, action === 'save'));
+    }
+    await sleep(500); // let write-without-response packets drain before disconnecting
+  } finally {
+    await ctl.close();
+  }
+}
+
+/** CLI entry point. Resolves to the process exit code. */
+export async function main(argv = process.argv.slice(2)) {
+  let cmd;
+  let args;
+  let o;
+  try {
+    ({ cmd, args, opts: o } = parseCli(argv));
+  } catch (e) {
+    console.error(`odelic: error: ${e.message}`);
+    return 2;
+  }
+  if (cmd === 'help') {
+    console.log(HELP);
+    return 0;
+  }
+  if (cmd === 'version') {
+    console.log(VERSION);
+    return 0;
+  }
+  if (o.verbose) setLogLevel('debug');
+
+  try {
+    const cfg = Config.load();
+    if (cmd === 'setup') {
+      if (o.id) {
+        parseAppId(o.id);
+        cfg.id = o.id;
+      }
+      if (o.node) cfg.node = o.node;
+      const idle = idleValue(o);
+      if (idle !== null) cfg.idleTimeout = idle;
+      cfg.save();
+      const mode = cfg.idle();
+      console.log(`saved to ${configPath()} (id: ${cfg.id ? 'set' : 'not set'}, connection: ${
+        mode ? `disconnect after ${mode}s idle` : 'keep connected'})`);
+    } else if (cmd === 'name') {
+      const sub = choice(args[0], 'name command', ['add', 'rm', 'list']);
+      if (sub === 'add') {
+        if (args.length !== 3) throw new InputError('usage: odelic name add NAME VADDR');
+        cfg.setName(args[1], args[2]);
+        cfg.save();
+      } else if (sub === 'rm') {
+        if (args.length !== 2) throw new InputError('usage: odelic name rm NAME');
+        cfg.removeName(args[1]);
+        cfg.save();
+      }
+      for (const [name, v] of Object.entries(cfg.lights)) console.log(`${name.padEnd(12)} ${v}`);
+    } else if (cmd === 'mcp') {
+      let mcp;
+      try {
+        mcp = await import('./mcp.js');
+      } catch (e) {
+        if (e.code !== 'ERR_MODULE_NOT_FOUND') throw e;
+        throw new OdelicError(`${e.message} (install with: npm install @modelcontextprotocol/sdk zod)`);
+      }
+      await mcp.main();
+      return null; // keep running until stdin closes
+    } else {
+      await runBle(cmd, args, o, cfg);
+    }
+    return 0;
+  } catch (e) {
+    if (o.verbose || !(e instanceof OdelicError)) log.debug(e.stack);
+    console.error(`error: ${e.message}`);
+    return 1;
+  }
+}