@martyndevries/xiaomi-miio 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# xiaomi-miio
+
+Zero-dependency Node.js TypeScript library for communicating with Xiaomi devices via the miIO protocol.
+
+miIO is Xiaomi's local LAN protocol used by many devices (fans, lamps, etc.) for discovery and command/control.
+It is UDP-based, uses a 32-byte header, and encrypts JSON-RPC payloads with AES-128-CBC.
+
+This library focuses on the protocol and transport layer only:
+
+- No device-specific logic (that lives in the Homey app in this repo)
+- No external dependencies
+- No filesystem access
+
+## Requirements
+
+- Node.js 22+
+- npm 10+
+
+## Background and references
+
+- miIO binary protocol notes: https://github.com/OpenMiHome/mihome-binary-protocol
+- miIO protocol notes (archived): https://github.com/OpenMiHome/mihome-binary-protocol/blob/master/doc/PROTOCOL.md
+- Xiaomi developer portal: https://developers.xiaomi.com
+- Xiaomi IoT platform: https://iot.mi.com
+- Similar projects:
+  - python-miio: https://github.com/rytilahti/python-miio
+  - miio (Node.js): https://www.npmjs.com/package/miio
+
+## Run locally
+
+```bash
+cd xiaomi-miio
+npm install
+npm run build
+```
+
+The build compiles TypeScript to `dist/` and is required before consuming the library from other packages.
+
+Run tests:
+
+```bash
+npm run test:dev
+```
+
+Tests compile to `dist-test/` and run with Node's built-in test runner.
+
+## Examples
+
+Bedside Lamp 2 CLI (interactive control of a single device):
+
+```bash
+npm run example:bedlamp2
+```
+
+This will prompt for the device IP and token, perform a handshake, and then let you send simple commands.
+
+Discovery CLI (scan the local network for miIO devices via UDP broadcast):
+
+```bash
+npm run example:discovery
+```
+
+This prints each responding device with its IP address, device ID, and stamp. Tokens are optional.
+
+## Minimal usage (TypeScript)
+
+This example connects to a known device IP and token, turns it on, and sets the speed level.
+
+```ts
+import { MiioDevice, MiioProtocol } from 'xiaomi-miio';
+
+const device = new MiioDevice({
+  address: '192.168.1.50',
+  token: MiioProtocol.tokenFromHex('00112233445566778899aabbccddeeff'),
+  model: 'zhimi.fan.sa1',
+});
+
+const info = await device.connect();
+console.log('Device ID:', info.deviceId);
+
+await device.call('set_power', ['on']);
+await device.call('set_speed_level', [50]);
+
+device.destroy();
+```
+
+## Discovery usage (TypeScript)
+
+This example broadcasts a discovery packet and prints all devices that respond.
+
+```ts
+import { discoverMiioDevices } from 'xiaomi-miio';
+
+const devices = await discoverMiioDevices({ timeout: 3000, includeToken: false });
+for (const device of devices) {
+  console.log(`${device.address} id=${device.deviceId} stamp=${device.stamp}`);
+}
+```
+
+## Contributors
+
+- Martyn de Vries (maintainer)

package/dist/device.d.ts

@@ -0,0 +1,31 @@
+import { MiioTransport, type TransportOptions } from './protocol/transport.js';
+export interface DeviceOptions extends TransportOptions {
+    /** Device model identifier (e.g. "yeelink.light.bslamp2"). */
+    model?: string | undefined;
+}
+export interface DeviceInfo {
+    address: string;
+    deviceId: number;
+    model?: string | undefined;
+}
+/**
+ * Base class for miIO devices.
+ *
+ * Provides the transport layer and common command methods.
+ * Subclass this to implement device-specific commands.
+ */
+export declare class MiioDevice {
+    protected readonly transport: MiioTransport;
+    readonly model?: string | undefined;
+    readonly address: string;
+    constructor(options: DeviceOptions);
+    /** Connect to the device by performing the handshake. */
+    connect(): Promise<DeviceInfo>;
+    /** Send a raw miIO command. */
+    call(method: string, params?: unknown[]): Promise<unknown>;
+    /** Query device properties. */
+    getProperties(props: string[]): Promise<unknown>;
+    /** Disconnect and clean up resources. */
+    destroy(): void;
+}
+//# sourceMappingURL=device.d.ts.map

package/dist/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE/E,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,aAAa;IAMlC,yDAAyD;IACnD,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;IASpC,+BAA+B;IACzB,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpE,+BAA+B;IACzB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAItD,yCAAyC;IACzC,OAAO,IAAI,IAAI;CAGhB"}

package/dist/device.js

@@ -0,0 +1,39 @@
+import { MiioTransport } from './protocol/transport.js';
+/**
+ * Base class for miIO devices.
+ *
+ * Provides the transport layer and common command methods.
+ * Subclass this to implement device-specific commands.
+ */
+export class MiioDevice {
+    transport;
+    model;
+    address;
+    constructor(options) {
+        this.transport = new MiioTransport(options);
+        this.model = options.model;
+        this.address = options.address;
+    }
+    /** Connect to the device by performing the handshake. */
+    async connect() {
+        const { deviceId } = await this.transport.handshake();
+        return {
+            address: this.address,
+            deviceId,
+            model: this.model,
+        };
+    }
+    /** Send a raw miIO command. */
+    async call(method, params = []) {
+        return this.transport.send(method, params);
+    }
+    /** Query device properties. */
+    async getProperties(props) {
+        return this.call('get_prop', props);
+    }
+    /** Disconnect and clean up resources. */
+    destroy() {
+        this.transport.destroy();
+    }
+}
+//# sourceMappingURL=device.js.map

package/dist/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../src/device.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAyB,MAAM,yBAAyB,CAAC;AAa/E;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACF,SAAS,CAAgB;IACnC,KAAK,CAAsB;IAC3B,OAAO,CAAS;IAEzB,YAAY,OAAsB;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,yDAAyD;IACzD,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,CAAC;QACtD,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ;YACR,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,KAAK,CAAC,IAAI,CAAC,MAAc,EAAE,SAAoB,EAAE;QAC/C,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED,+BAA+B;IAC/B,KAAK,CAAC,aAAa,CAAC,KAAe;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,yCAAyC;IACzC,OAAO;QACL,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;IAC3B,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { MiioProtocol } from './protocol/protocol.js';
+export { MiioPacket } from './protocol/packet.js';
+export { MiioCrypto } from './protocol/crypto.js';
+export { MiioTransport, type TransportOptions } from './protocol/transport.js';
+export { discoverMiioDevices, type DiscoveryOptions, type MiioDiscoveredDevice } from './protocol/discovery.js';
+export { MiioDevice, type DeviceInfo, type DeviceOptions } from './device.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAChH,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { MiioProtocol } from './protocol/protocol.js';
+export { MiioPacket } from './protocol/packet.js';
+export { MiioCrypto } from './protocol/crypto.js';
+export { MiioTransport } from './protocol/transport.js';
+export { discoverMiioDevices } from './protocol/discovery.js';
+export { MiioDevice } from './device.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAyB,MAAM,yBAAyB,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAoD,MAAM,yBAAyB,CAAC;AAChH,OAAO,EAAE,UAAU,EAAuC,MAAM,aAAa,CAAC"}

package/dist/protocol/crypto.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Handles miIO protocol encryption and decryption.
+ *
+ * The miIO protocol uses AES-128-CBC with PKCS#7 padding.
+ * - Key = MD5(token)
+ * - IV  = MD5(Key + token)
+ */
+export declare class MiioCrypto {
+    private readonly key;
+    private readonly iv;
+    constructor(token: Buffer);
+    /** Encrypt a plaintext buffer using AES-128-CBC. */
+    encrypt(plaintext: Buffer): Buffer;
+    /** Decrypt a ciphertext buffer using AES-128-CBC. */
+    decrypt(ciphertext: Buffer): Buffer;
+    /** Compute MD5 hash of the given data. */
+    static md5(data: Buffer): Buffer;
+}
+//# sourceMappingURL=crypto.d.ts.map

package/dist/protocol/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/protocol/crypto.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAS;gBAEhB,KAAK,EAAE,MAAM;IAQzB,oDAAoD;IACpD,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAKlC,qDAAqD;IACrD,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAKnC,0CAA0C;IAC1C,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAGjC"}

package/dist/protocol/crypto.js

@@ -0,0 +1,34 @@
+import * as crypto from 'node:crypto';
+/**
+ * Handles miIO protocol encryption and decryption.
+ *
+ * The miIO protocol uses AES-128-CBC with PKCS#7 padding.
+ * - Key = MD5(token)
+ * - IV  = MD5(Key + token)
+ */
+export class MiioCrypto {
+    key;
+    iv;
+    constructor(token) {
+        if (token.length !== 16) {
+            throw new Error(`Token must be 16 bytes, got ${token.length}`);
+        }
+        this.key = MiioCrypto.md5(token);
+        this.iv = MiioCrypto.md5(Buffer.concat([this.key, token]));
+    }
+    /** Encrypt a plaintext buffer using AES-128-CBC. */
+    encrypt(plaintext) {
+        const cipher = crypto.createCipheriv('aes-128-cbc', this.key, this.iv);
+        return Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    }
+    /** Decrypt a ciphertext buffer using AES-128-CBC. */
+    decrypt(ciphertext) {
+        const decipher = crypto.createDecipheriv('aes-128-cbc', this.key, this.iv);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    }
+    /** Compute MD5 hash of the given data. */
+    static md5(data) {
+        return crypto.createHash('md5').update(data).digest();
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/protocol/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../../src/protocol/crypto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACJ,GAAG,CAAS;IACZ,EAAE,CAAS;IAE5B,YAAY,KAAa;QACvB,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,+BAA+B,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,oDAAoD;IACpD,OAAO,CAAC,SAAiB;QACvB,MAAM,MAAM,GAAG,MAAM,CAAC,cAAc,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QACvE,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,qDAAqD;IACrD,OAAO,CAAC,UAAkB;QACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,gBAAgB,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3E,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,0CAA0C;IAC1C,MAAM,CAAC,GAAG,CAAC,IAAY;QACrB,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;IACxD,CAAC;CACF"}

package/dist/protocol/discovery.d.ts

@@ -0,0 +1,30 @@
+import * as dgram from 'node:dgram';
+export interface DiscoveryOptions {
+    /** Broadcast address for discovery. Default: 255.255.255.255 */
+    address?: string | undefined;
+    /** UDP port for miIO discovery. Default: 54321 */
+    port?: number | undefined;
+    /** Discovery timeout in milliseconds. Default: 5000 */
+    timeout?: number | undefined;
+    /** Include the token from the Hello response (if present). Default: false */
+    includeToken?: boolean | undefined;
+    /** Optional factory for creating the UDP socket (for testing). */
+    createSocket?: (() => dgram.Socket) | undefined;
+}
+export interface MiioDiscoveredDevice {
+    /** Device IP address. */
+    address: string;
+    /** Device ID from the Hello response. */
+    deviceId: number;
+    /** Device stamp from the Hello response. */
+    stamp: number;
+    /** Token from the Hello response (if includeToken is true). */
+    token?: Buffer | undefined;
+}
+/**
+ * Discover miIO devices on the local network via UDP broadcast.
+ *
+ * Sends a Hello packet and collects all Hello responses until timeout.
+ */
+export declare function discoverMiioDevices(options?: DiscoveryOptions): Promise<MiioDiscoveredDevice[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/protocol/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/protocol/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAQpC,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,kEAAkE;IAClE,YAAY,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA8DjC"}

package/dist/protocol/discovery.js

@@ -0,0 +1,73 @@
+import * as dgram from 'node:dgram';
+import { MiioPacket } from './packet.js';
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_BROADCAST_ADDRESS = '255.255.255.255';
+const DEFAULT_PORT = 54321;
+const EMPTY_TOKEN = Buffer.alloc(16, 0);
+/**
+ * Discover miIO devices on the local network via UDP broadcast.
+ *
+ * Sends a Hello packet and collects all Hello responses until timeout.
+ */
+export async function discoverMiioDevices(options = {}) {
+    const address = options.address ?? DEFAULT_BROADCAST_ADDRESS;
+    const port = options.port ?? DEFAULT_PORT;
+    const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    const includeToken = options.includeToken ?? false;
+    const createSocket = options.createSocket ?? (() => dgram.createSocket('udp4'));
+    const socket = createSocket();
+    const results = new Map();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeListener('message', onMessage);
+            socket.removeListener('error', onError);
+            try {
+                socket.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve([...results.values()]);
+            }
+        };
+        const timer = setTimeout(() => { finish(); }, timeout);
+        const onError = (err) => { finish(err); };
+        const onMessage = (msg, rinfo) => {
+            try {
+                const { deviceId, stamp } = MiioPacket.decode(msg, EMPTY_TOKEN);
+                const device = {
+                    address: rinfo.address,
+                    deviceId,
+                    stamp,
+                };
+                if (includeToken) {
+                    device.token = MiioPacket.extractToken(msg);
+                }
+                results.set(rinfo.address, device);
+            }
+            catch {
+                // Ignore malformed or non-miIO responses
+            }
+        };
+        socket.on('message', onMessage);
+        socket.on('error', onError);
+        socket.bind(0, () => {
+            socket.setBroadcast(true);
+            const hello = MiioPacket.createHello();
+            socket.send(hello, 0, hello.length, port, address, (err) => {
+                if (err)
+                    finish(err);
+            });
+        });
+    });
+}
+//# sourceMappingURL=discovery.js.map

package/dist/protocol/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/protocol/discovery.ts"],"names":[],"mappings":"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"}

package/dist/protocol/packet.d.ts

@@ -0,0 +1,28 @@
+/**
+ * miIO binary packet structure.
+ *
+ * Header (32 bytes):
+ *   - Magic:      2 bytes (0x2131)
+ *   - Length:      2 bytes (total packet length including header)
+ *   - Unknown:     4 bytes (0x00000000, or 0xFFFFFFFF for Hello)
+ *   - Device ID:   4 bytes (0xFFFFFFFF for Hello)
+ *   - Stamp:       4 bytes (incrementing counter)
+ *   - Checksum:    16 bytes (MD5 of header + token + payload, or token in Hello response)
+ */
+export declare class MiioPacket {
+    static readonly MAGIC = 8497;
+    static readonly HEADER_SIZE = 32;
+    /** Create a Hello discovery packet (all 0xFF except magic and length). */
+    static createHello(): Buffer;
+    /** Encode a JSON command into an encrypted miIO packet. */
+    static encode(deviceId: number, stamp: number, token: Buffer, payload: object): Buffer;
+    /** Decode a miIO packet, returning parsed header and decrypted payload. */
+    static decode(data: Buffer, token: Buffer): {
+        deviceId: number;
+        stamp: number;
+        payload: object | null;
+    };
+    /** Extract the device token from a Hello response packet. */
+    static extractToken(helloResponse: Buffer): Buffer;
+}
+//# sourceMappingURL=packet.d.ts.map

package/dist/protocol/packet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"packet.d.ts","sourceRoot":"","sources":["../../src/protocol/packet.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,qBAAa,UAAU;IACrB,MAAM,CAAC,QAAQ,CAAC,KAAK,QAAU;IAC/B,MAAM,CAAC,QAAQ,CAAC,WAAW,MAAM;IAEjC,0EAA0E;IAC1E,MAAM,CAAC,WAAW,IAAI,MAAM;IAO5B,2DAA2D;IAC3D,MAAM,CAAC,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM;IAwBT,2EAA2E;IAC3E,MAAM,CAAC,MAAM,CACX,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;IA4B9D,6DAA6D;IAC7D,MAAM,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM;CAMnD"}

package/dist/protocol/packet.js

@@ -0,0 +1,73 @@
+import { MiioCrypto } from './crypto.js';
+/**
+ * miIO binary packet structure.
+ *
+ * Header (32 bytes):
+ *   - Magic:      2 bytes (0x2131)
+ *   - Length:      2 bytes (total packet length including header)
+ *   - Unknown:     4 bytes (0x00000000, or 0xFFFFFFFF for Hello)
+ *   - Device ID:   4 bytes (0xFFFFFFFF for Hello)
+ *   - Stamp:       4 bytes (incrementing counter)
+ *   - Checksum:    16 bytes (MD5 of header + token + payload, or token in Hello response)
+ */
+export class MiioPacket {
+    static MAGIC = 0x2131;
+    static HEADER_SIZE = 32;
+    /** Create a Hello discovery packet (all 0xFF except magic and length). */
+    static createHello() {
+        const packet = Buffer.alloc(MiioPacket.HEADER_SIZE, 0xff);
+        packet.writeUInt16BE(MiioPacket.MAGIC, 0);
+        packet.writeUInt16BE(MiioPacket.HEADER_SIZE, 2);
+        return packet;
+    }
+    /** Encode a JSON command into an encrypted miIO packet. */
+    static encode(deviceId, stamp, token, payload) {
+        const miiocrypto = new MiioCrypto(token);
+        const jsonStr = JSON.stringify(payload);
+        const encrypted = miiocrypto.encrypt(Buffer.from(jsonStr, 'utf-8'));
+        const packetLength = MiioPacket.HEADER_SIZE + encrypted.length;
+        const header = Buffer.alloc(MiioPacket.HEADER_SIZE);
+        header.writeUInt16BE(MiioPacket.MAGIC, 0);
+        header.writeUInt16BE(packetLength, 2);
+        header.writeUInt32BE(0x00000000, 4);
+        header.writeUInt32BE(deviceId, 8);
+        header.writeUInt32BE(stamp, 12);
+        // Checksum placeholder (16 bytes of token for checksum calculation)
+        token.copy(header, 16);
+        // Calculate MD5 checksum over header + encrypted payload
+        const checksum = MiioCrypto.md5(Buffer.concat([header, encrypted]));
+        checksum.copy(header, 16);
+        return Buffer.concat([header, encrypted]);
+    }
+    /** Decode a miIO packet, returning parsed header and decrypted payload. */
+    static decode(data, token) {
+        if (data.length < MiioPacket.HEADER_SIZE) {
+            throw new Error(`Packet too short: ${data.length} bytes`);
+        }
+        const magic = data.readUInt16BE(0);
+        if (magic !== MiioPacket.MAGIC) {
+            throw new Error(`Invalid magic: 0x${magic.toString(16)}`);
+        }
+        const length = data.readUInt16BE(2);
+        const deviceId = data.readUInt32BE(8);
+        const stamp = data.readUInt32BE(12);
+        if (length === MiioPacket.HEADER_SIZE) {
+            // Hello response — no payload, checksum field contains the token
+            return { deviceId, stamp, payload: null };
+        }
+        const encrypted = data.subarray(MiioPacket.HEADER_SIZE, length);
+        const miiocrypto = new MiioCrypto(token);
+        const decrypted = miiocrypto.decrypt(encrypted);
+        const jsonStr = decrypted.toString('utf-8');
+        const payload = JSON.parse(jsonStr);
+        return { deviceId, stamp, payload };
+    }
+    /** Extract the device token from a Hello response packet. */
+    static extractToken(helloResponse) {
+        if (helloResponse.length < MiioPacket.HEADER_SIZE) {
+            throw new Error('Hello response too short');
+        }
+        return Buffer.from(helloResponse.subarray(16, 32));
+    }
+}
+//# sourceMappingURL=packet.js.map

package/dist/protocol/packet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"packet.js","sourceRoot":"","sources":["../../src/protocol/packet.ts"],"names":[],"mappings":"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"}

package/dist/protocol/protocol.d.ts

@@ -0,0 +1,20 @@
+export { MiioCrypto } from './crypto.js';
+export { MiioPacket } from './packet.js';
+export { MiioTransport } from './transport.js';
+export { discoverMiioDevices, type DiscoveryOptions, type MiioDiscoveredDevice } from './discovery.js';
+/**
+ * Re-export of the protocol building blocks.
+ *
+ * The miIO protocol operates as follows:
+ * 1. Send a Hello packet to UDP port 54321
+ * 2. Receive device ID and stamp from the Hello response
+ * 3. Encrypt JSON-RPC commands with AES-128-CBC using the device token
+ * 4. Send commands and receive encrypted responses
+ */
+export declare class MiioProtocol {
+    /** Default miIO UDP port. */
+    static readonly PORT = 54321;
+    /** Convert a hex token string to a Buffer. */
+    static tokenFromHex(hex: string): Buffer;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/protocol/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAEvG;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,6BAA6B;IAC7B,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAS;IAE7B,8CAA8C;IAC9C,MAAM,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;CAMzC"}

package/dist/protocol/protocol.js

@@ -0,0 +1,25 @@
+export { MiioCrypto } from './crypto.js';
+export { MiioPacket } from './packet.js';
+export { MiioTransport } from './transport.js';
+export { discoverMiioDevices } from './discovery.js';
+/**
+ * Re-export of the protocol building blocks.
+ *
+ * The miIO protocol operates as follows:
+ * 1. Send a Hello packet to UDP port 54321
+ * 2. Receive device ID and stamp from the Hello response
+ * 3. Encrypt JSON-RPC commands with AES-128-CBC using the device token
+ * 4. Send commands and receive encrypted responses
+ */
+export class MiioProtocol {
+    /** Default miIO UDP port. */
+    static PORT = 54321;
+    /** Convert a hex token string to a Buffer. */
+    static tokenFromHex(hex) {
+        if (hex.length !== 32) {
+            throw new Error(`Token hex must be 32 characters, got ${hex.length}`);
+        }
+        return Buffer.from(hex, 'hex');
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/protocol/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAoD,MAAM,gBAAgB,CAAC;AAEvG;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IACvB,6BAA6B;IAC7B,MAAM,CAAU,IAAI,GAAG,KAAK,CAAC;IAE7B,8CAA8C;IAC9C,MAAM,CAAC,YAAY,CAAC,GAAW;QAC7B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,wCAAwC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjC,CAAC"}

package/dist/protocol/transport.d.ts

@@ -0,0 +1,43 @@
+import * as dgram from 'node:dgram';
+import { EventEmitter } from 'node:events';
+export interface TransportOptions {
+    /** Device IP address. */
+    address: string;
+    /** Device token (16-byte Buffer). */
+    token: Buffer;
+    /** Command timeout in milliseconds. Default: 5000. */
+    timeout?: number | undefined;
+    /** Optional factory for creating the UDP socket (for testing). */
+    createSocket?: (() => dgram.Socket) | undefined;
+}
+/**
+ * UDP transport layer for the miIO protocol.
+ *
+ * Handles socket management, handshake, command sending,
+ * and response correlation via message IDs.
+ */
+export declare class MiioTransport extends EventEmitter {
+    private readonly address;
+    private readonly token;
+    private readonly timeout;
+    private readonly createSocket;
+    private socket;
+    private deviceId;
+    private stamp;
+    private lastHandshake;
+    private messageId;
+    private readonly pendingRequests;
+    constructor(options: TransportOptions);
+    /** Perform the initial handshake to discover the device. */
+    handshake(): Promise<{
+        deviceId: number;
+        stamp: number;
+    }>;
+    /** Send a miIO JSON-RPC command and wait for the response. */
+    send(method: string, params?: unknown[]): Promise<unknown>;
+    /** Close the UDP socket and clean up. */
+    destroy(): void;
+    private ensureSocket;
+    private handleMessage;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/protocol/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/protocol/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAM3C,MAAM,WAAW,gBAAgB;IAC/B,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,kEAAkE;IAClE,YAAY,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;CACjD;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAElD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAK;IAEtB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG5B;gBAEQ,OAAO,EAAE,gBAAgB;IAQrC,4DAA4D;IACtD,SAAS,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IA6B/D,8DAA8D;IACxD,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,OAAO,EAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBpE,yCAAyC;IACzC,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,aAAa;CAqBtB"}

package/dist/protocol/transport.js

@@ -0,0 +1,120 @@
+import * as dgram from 'node:dgram';
+import { EventEmitter } from 'node:events';
+import { MiioPacket } from './packet.js';
+const MIIO_PORT = 54321;
+const DEFAULT_TIMEOUT = 5000;
+/**
+ * UDP transport layer for the miIO protocol.
+ *
+ * Handles socket management, handshake, command sending,
+ * and response correlation via message IDs.
+ */
+export class MiioTransport extends EventEmitter {
+    address;
+    token;
+    timeout;
+    createSocket;
+    socket = null;
+    deviceId = 0;
+    stamp = 0;
+    lastHandshake = 0;
+    messageId = 1;
+    pendingRequests = new Map();
+    constructor(options) {
+        super();
+        this.address = options.address;
+        this.token = options.token;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.createSocket = options.createSocket ?? (() => dgram.createSocket('udp4'));
+    }
+    /** Perform the initial handshake to discover the device. */
+    async handshake() {
+        const socket = this.ensureSocket();
+        const hello = MiioPacket.createHello();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Handshake timeout after ${this.timeout}ms`));
+            }, this.timeout);
+            const onMessage = (msg) => {
+                clearTimeout(timer);
+                socket.removeListener('message', onMessage);
+                try {
+                    const { deviceId, stamp } = MiioPacket.decode(msg, this.token);
+                    this.deviceId = deviceId;
+                    this.stamp = stamp;
+                    this.lastHandshake = Date.now();
+                    resolve({ deviceId, stamp });
+                }
+                catch (err) {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                }
+            };
+            socket.on('message', onMessage);
+            socket.send(hello, 0, hello.length, MIIO_PORT, this.address);
+        });
+    }
+    /** Send a miIO JSON-RPC command and wait for the response. */
+    async send(method, params = []) {
+        // Re-handshake if stale (older than 60 seconds)
+        if (Date.now() - this.lastHandshake > 60_000) {
+            await this.handshake();
+        }
+        const id = this.messageId++;
+        this.stamp++;
+        const payload = { id, method, params };
+        const packet = MiioPacket.encode(this.deviceId, this.stamp, this.token, payload);
+        const socket = this.ensureSocket();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Command '${method}' timed out after ${this.timeout}ms`));
+            }, this.timeout);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            socket.send(packet, 0, packet.length, MIIO_PORT, this.address);
+        });
+    }
+    /** Close the UDP socket and clean up. */
+    destroy() {
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Transport destroyed'));
+            this.pendingRequests.delete(id);
+        }
+        if (this.socket) {
+            this.socket.close();
+            this.socket = null;
+        }
+    }
+    ensureSocket() {
+        if (this.socket)
+            return this.socket;
+        const socket = this.createSocket();
+        socket.on('message', (msg) => { this.handleMessage(msg); });
+        socket.on('error', (err) => { this.emit('error', err); });
+        this.socket = socket;
+        return socket;
+    }
+    handleMessage(data) {
+        try {
+            const { payload } = MiioPacket.decode(data, this.token);
+            if (payload && typeof payload === 'object' && 'id' in payload) {
+                const response = payload;
+                const pending = this.pendingRequests.get(response.id);
+                if (pending) {
+                    clearTimeout(pending.timer);
+                    this.pendingRequests.delete(response.id);
+                    if (response.error) {
+                        pending.reject(new Error(`miIO error ${response.error.code}: ${response.error.message}`));
+                    }
+                    else {
+                        pending.resolve(response.result);
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore malformed packets
+        }
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/protocol/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/protocol/transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@martyndevries/xiaomi-miio",
+  "version": "0.1.0",
+  "description": "Zero-dependency Node.js library for Xiaomi miIO protocol",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "pretest": "tsc -p tsconfig.test.json",
+    "test": "node --test 'dist-test/**/*.test.js'",
+    "test:dev": "NODE_OPTIONS='' tsc -p tsconfig.test.json && node --test 'dist-test/**/*.test.js'",
+    "test:coverage": "c8 --reporter=text --reporter=json-summary --reporter=lcov --check-coverage --lines 80 --functions 80 --branches 80 --statements 80 node --test 'dist-test/**/*.test.js'",
+    "lint": "eslint src/",
+    "build:examples": "tsc -p tsconfig.examples.json",
+    "example:bedlamp2": "tsc -p tsconfig.examples.json && node dist-examples/examples/bedlamp2-cli.js",
+    "example:discovery": "tsc -p tsconfig.examples.json && node dist-examples/examples/discovery-cli.js",
+    "clean": "rm -rf dist dist-test dist-examples",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "devDependencies": {
+    "@semantic-release/exec": "^6.0.3",
+    "@types/node": "^22.0.0",
+    "c8": "^10.1.3",
+    "eslint": "^9.0.0",
+    "semantic-release": "^24.0.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mvdevries/xiaomi-miio.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "tagFormat": "xiaomi-miio-v${version}",
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      [
+        "@semantic-release/npm",
+        {
+          "npmPublish": false
+        }
+      ],
+      [
+        "@semantic-release/exec",
+        {
+          "publishCmd": "npm publish --access public --provenance"
+        }
+      ],
+      "@semantic-release/github"
+    ]
+  },
+  "license": "ISC"
+}