scrypted-kasa 1.0.0

package/src/iot/bulb.ts

@@ -0,0 +1,178 @@
+import {
+    Brightness,
+    ColorHsv,
+    ColorSettingHsv,
+    ColorSettingTemperature,
+    OnOff,
+    ScryptedDeviceBase,
+    Setting,
+    Settings,
+    SettingValue,
+} from '@scrypted/sdk';
+import { StorageSettings } from '@scrypted/sdk/storage-settings';
+import { KASA_IOT_PORT, getSysInfo, kasaIotCall } from './protocol';
+
+const STATE_POLL_INTERVAL_MS = 30000;
+
+// Smart bulbs (LB100/110/120/130, KL110/120/130/135/...). All bulb state — on/off,
+// brightness, hue, saturation, color temperature — is controlled by a single command:
+//   {"smartlife.iot.smartbulb.lightingservice":{"transition_light_state":{...}}}
+//
+// Capability flags from sysinfo:
+//   is_dimmable           1 = supports brightness
+//   is_color              1 = supports hue/saturation
+//   is_variable_color_temp 1 = supports color temperature
+// Color temperature range is determined per-model; we expose the values the bulb returns
+// in `getTemperatureMinK`/`getTemperatureMaxK` and fall back to a safe pair otherwise.
+export class KasaBulb
+    extends ScryptedDeviceBase
+    implements OnOff, Brightness, ColorSettingHsv, ColorSettingTemperature, Settings
+{
+    storageSettings = new StorageSettings(this, {
+        ip: {
+            title: 'IP Address',
+            placeholder: '192.168.1.100',
+        },
+        port: {
+            title: 'Port',
+            type: 'number',
+            defaultValue: KASA_IOT_PORT,
+        },
+        // Capability flags captured from sysinfo at adoption — internal only, drive which
+        // interfaces the device advertises. Hidden because users don't typically need to
+        // toggle them (auto-detected from the bulb's own metadata).
+        isColor: {
+            type: 'boolean',
+            hide: true,
+        },
+        isVariableColorTemp: {
+            type: 'boolean',
+            hide: true,
+        },
+        colorTemperatureMinK: {
+            type: 'number',
+            defaultValue: 2700,
+            hide: true,
+        },
+        colorTemperatureMaxK: {
+            type: 'number',
+            defaultValue: 6500,
+            hide: true,
+        },
+    });
+
+    private pollTimer?: NodeJS.Timeout;
+    private pollStartTimer?: NodeJS.Timeout;
+    // See KasaIotDevice for rationale: shared in-flight promise prevents overlapping
+    // refreshState calls from racing if a poll takes longer than the interval.
+    private refreshInFlight?: Promise<void>;
+
+    constructor(nativeId: string) {
+        super(nativeId);
+        process.nextTick(() => this.refreshState().catch(e => this.console.warn('refresh state failed', e)));
+        // Random first-fire offset to spread load when many bulbs are constructed together.
+        const jitter = Math.floor(Math.random() * STATE_POLL_INTERVAL_MS);
+        this.pollStartTimer = setTimeout(() => {
+            this.pollStartTimer = undefined;
+            this.pollTimer = setInterval(() => this.refreshState().catch(() => {}), STATE_POLL_INTERVAL_MS);
+        }, jitter);
+    }
+
+    getSettings(): Promise<Setting[]> {
+        return this.storageSettings.getSettings();
+    }
+
+    putSetting(key: string, value: SettingValue): Promise<void> {
+        return this.storageSettings.putSetting(key, value);
+    }
+
+    async turnOn(): Promise<void> {
+        await this.lightState({ on_off: 1 });
+        this.on = true;
+    }
+
+    async turnOff(): Promise<void> {
+        await this.lightState({ on_off: 0 });
+        this.on = false;
+    }
+
+    async setBrightness(brightness: number): Promise<void> {
+        await this.lightState({ brightness });
+        this.brightness = brightness;
+    }
+
+    async setHsv(hue: number, saturation: number, value: number): Promise<void> {
+        // Switch the bulb to color mode (mode 1) when HSV is set; without this some bulbs
+        // ignore the hue/saturation while in color-temperature mode.
+        await this.lightState({
+            color_temp: 0,
+            hue,
+            saturation,
+            brightness: value,
+        });
+        this.hsv = { h: hue, s: saturation, v: value };
+        this.brightness = value;
+    }
+
+    async setColorTemperature(kelvin: number): Promise<void> {
+        await this.lightState({ color_temp: kelvin });
+        this.colorTemperature = kelvin;
+    }
+
+    async getTemperatureMinK(): Promise<number> {
+        return this.storageSettings.values.colorTemperatureMinK;
+    }
+
+    async getTemperatureMaxK(): Promise<number> {
+        return this.storageSettings.values.colorTemperatureMaxK;
+    }
+
+    async refreshState(): Promise<void> {
+        if (this.refreshInFlight) return this.refreshInFlight;
+        this.refreshInFlight = this.refreshStateInternal().finally(() => {
+            this.refreshInFlight = undefined;
+        });
+        return this.refreshInFlight;
+    }
+
+    private async refreshStateInternal(): Promise<void> {
+        if (!this.storageSettings.values.ip) return;
+        const sys = await getSysInfo(this.iotOptions());
+        const ls = sys?.light_state;
+        if (!ls) return;
+        // light_state during off-state nests the actual values under `dft_on_state`.
+        const active = ls.on_off ? ls : ls.dft_on_state || {};
+        this.on = ls.on_off === 1;
+        if (typeof active.brightness === 'number') this.brightness = active.brightness;
+        if (typeof active.color_temp === 'number') this.colorTemperature = active.color_temp;
+        if (typeof active.hue === 'number' && typeof active.saturation === 'number') {
+            const hsv: ColorHsv = {
+                h: active.hue,
+                s: active.saturation,
+                v: typeof active.brightness === 'number' ? active.brightness : 100,
+            };
+            this.hsv = hsv;
+        }
+    }
+
+    private lightState(state: Record<string, any>): Promise<any> {
+        // ignore_default tells the bulb to merge with current state instead of resetting.
+        return kasaIotCall(this.iotOptions(), {
+            'smartlife.iot.smartbulb.lightingservice': {
+                transition_light_state: { ignore_default: 1, ...state },
+            },
+        });
+    }
+
+    private iotOptions() {
+        return {
+            host: this.storageSettings.values.ip,
+            port: this.storageSettings.values.port,
+        };
+    }
+
+    release(): void {
+        clearInterval(this.pollTimer);
+        clearTimeout(this.pollStartTimer);
+    }
+}

package/src/iot/device.ts

@@ -0,0 +1,103 @@
+import { OnOff, ScryptedDeviceBase, Setting, Settings, SettingValue } from '@scrypted/sdk';
+import { StorageSettings } from '@scrypted/sdk/storage-settings';
+import { KASA_IOT_PORT, getSysInfo, kasaIotCall } from './protocol';
+
+const STATE_POLL_INTERVAL_MS = 30000;
+
+// Shared base for every Kasa "smarthome" single-relay device — outlets, switches, and
+// dimmers. Only the on/off relay protocol lives here; dimmable devices add Brightness on
+// top in KasaDimmer.
+//
+// Wire protocol (TCP/9999):
+//   on/off:    {"system":{"set_relay_state":{"state":1|0}}}
+//   query:     {"system":{"get_sysinfo":{}}}
+//
+// Multi-outlet strips (HS300, KP303) aren't modeled — they need per-child relay handling.
+export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff, Settings {
+    storageSettings = new StorageSettings(this, {
+        ip: {
+            title: 'IP Address',
+            placeholder: '192.168.1.100',
+        },
+        port: {
+            title: 'Port',
+            type: 'number',
+            defaultValue: KASA_IOT_PORT,
+        },
+    });
+
+    private pollTimer?: NodeJS.Timeout;
+    private pollStartTimer?: NodeJS.Timeout;
+    // Guard against overlapping polls: if a refresh is in-flight when the interval fires
+    // (e.g., the camera is slow), the second call would open a parallel TCP connection
+    // and could race the first response. Sharing the in-flight promise avoids that.
+    private refreshInFlight?: Promise<void>;
+
+    constructor(nativeId: string) {
+        super(nativeId);
+        // Drive an initial state refresh on next tick (so storageSettings is ready) and a
+        // periodic poll thereafter so external state changes (other apps, physical button
+        // presses) eventually surface in Scrypted/HomeKit. A small per-instance jitter on
+        // the first poll spreads the load when many devices were started together.
+        process.nextTick(() => this.refreshState().catch(e => this.console.warn('refresh state failed', e)));
+        const jitter = Math.floor(Math.random() * STATE_POLL_INTERVAL_MS);
+        this.pollStartTimer = setTimeout(() => {
+            this.pollStartTimer = undefined;
+            this.pollTimer = setInterval(() => this.refreshState().catch(() => {}), STATE_POLL_INTERVAL_MS);
+        }, jitter);
+    }
+
+    getSettings(): Promise<Setting[]> {
+        return this.storageSettings.getSettings();
+    }
+
+    putSetting(key: string, value: SettingValue): Promise<void> {
+        return this.storageSettings.putSetting(key, value);
+    }
+
+    async turnOn(): Promise<void> {
+        await this.callIot({ system: { set_relay_state: { state: 1 } } });
+        this.on = true;
+    }
+
+    async turnOff(): Promise<void> {
+        await this.callIot({ system: { set_relay_state: { state: 0 } } });
+        this.on = false;
+    }
+
+    async refreshState(): Promise<void> {
+        if (this.refreshInFlight) return this.refreshInFlight;
+        this.refreshInFlight = this.refreshStateInternal().finally(() => {
+            this.refreshInFlight = undefined;
+        });
+        return this.refreshInFlight;
+    }
+
+    private async refreshStateInternal(): Promise<void> {
+        if (!this.storageSettings.values.ip) return;
+        const sys = await getSysInfo(this.iotOptions());
+        if (!sys) return;
+        if (typeof sys.relay_state === 'number') this.on = sys.relay_state === 1;
+        // Subclasses with extra state extend via onSysInfo hook.
+        this.onSysInfo(sys);
+    }
+
+    // Hook for subclasses to consume additional sysinfo fields (e.g. brightness for dimmers).
+    protected onSysInfo(_sys: Record<string, any>): void {}
+
+    protected callIot(command: Record<string, any>): Promise<any> {
+        return kasaIotCall(this.iotOptions(), command);
+    }
+
+    protected iotOptions() {
+        return {
+            host: this.storageSettings.values.ip,
+            port: this.storageSettings.values.port,
+        };
+    }
+
+    release(): void {
+        clearInterval(this.pollTimer);
+        clearTimeout(this.pollStartTimer);
+    }
+}

package/src/iot/dimmer.ts

@@ -0,0 +1,19 @@
+import { Brightness } from '@scrypted/sdk';
+import { KasaIotDevice } from './device';
+
+// Dimmable Kasa devices (HS220 dimmer plug, KS230 3-way dimmer switch, etc.). Same
+// relay protocol as KasaPlug/KasaSwitch plus a brightness command:
+//   {"smartlife.iot.dimmer":{"set_brightness":{"brightness":N}}}
+//
+// Always exposed as `Light` since these are essentially always wired to a light fixture
+// (the Kasa app does the same). On/off uses the relay; brightness uses the dimmer module.
+export class KasaDimmer extends KasaIotDevice implements Brightness {
+    async setBrightness(brightness: number): Promise<void> {
+        await this.callIot({ 'smartlife.iot.dimmer': { set_brightness: { brightness } } });
+        this.brightness = brightness;
+    }
+
+    protected onSysInfo(sys: Record<string, any>): void {
+        if (typeof sys.brightness === 'number') this.brightness = sys.brightness;
+    }
+}

package/src/iot/plug.ts

@@ -0,0 +1,5 @@
+import { KasaIotDevice } from './device';
+
+// Plain Kasa plugs/outlets (HS100/HS103/HS105/HS107/HS110/KP100/etc.) — single relay,
+// no brightness. Dimmer plugs (HS220) are handled by KasaDimmer instead.
+export class KasaPlug extends KasaIotDevice {}

package/src/iot/protocol.ts

@@ -0,0 +1,143 @@
+import net from 'net';
+import { xorDecrypt, xorEncryptInPlace } from '../shared/cipher';
+
+// Legacy Kasa "IOT" protocol used by plugs, switches, and bulbs (everything that isn't a
+// camera). Wire format on TCP/9999:
+//   4-byte big-endian length prefix + XOR-AB(plaintext-json) bytes
+// Same XOR-AB autokey cipher as UDP discovery; the only difference is the framing.
+//
+// Same-port UDP/9999 also accepts the encrypted JSON without the 4-byte prefix, but TCP
+// is more reliable for control commands so we use it exclusively here.
+
+export const KASA_IOT_PORT = 9999;
+const REQUEST_TIMEOUT_MS = 5000;
+
+export interface KasaIotOptions {
+    host: string;
+    port?: number;
+    timeoutMs?: number;
+}
+
+export async function kasaIotCall(options: KasaIotOptions, command: Record<string, any>): Promise<any> {
+    const port = options.port || KASA_IOT_PORT;
+    const timeoutMs = options.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    const json = JSON.stringify(command);
+    // Encode the 4-byte length prefix and JSON in one allocation, encrypt the JSON portion
+    // in-place (we own this buffer and don't read the plaintext again).
+    const jsonBytes = Buffer.byteLength(json, 'utf8');
+    const payload = Buffer.allocUnsafe(4 + jsonBytes);
+    payload.writeUInt32BE(jsonBytes, 0);
+    payload.write(json, 4, 'utf8');
+    xorEncryptInPlace(payload.subarray(4));
+
+    return new Promise((resolve, reject) => {
+        const socket = new net.Socket();
+        // Queue of received TCP chunks plus byte total, so we don't repeatedly Buffer.concat
+        // the accumulator on every 'data' event (O(n²) over multi-chunk responses; bulb
+        // light_state replies span 2-3 chunks).
+        const chunks: Buffer[] = [];
+        let queuedBytes = 0;
+        let expected = -1;
+        let settled = false;
+
+        const finish = (err?: Error, value?: any) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            try {
+                socket.destroy();
+            } catch {}
+            // Drop references so any retained chunks can be GC'd promptly.
+            chunks.length = 0;
+            if (err) reject(err);
+            else resolve(value);
+        };
+
+        const timer = setTimeout(() => finish(new Error(`kasa iot call timeout after ${timeoutMs}ms`)), timeoutMs);
+
+        const peek4 = (): number => {
+            // We've verified queuedBytes >= 4 before calling. Read big-endian uint32 either
+            // straight from the head buffer (common case) or after walking the queue.
+            if (chunks[0].length >= 4) return chunks[0].readUInt32BE(0);
+            // Rare: 4-byte length straddles two chunks. Concat just the first two.
+            return Buffer.concat(chunks.slice(0, 2), 4).readUInt32BE(0);
+        };
+
+        const consume = (n: number): Buffer => {
+            // Pop and return exactly n bytes from the head of the queue.
+            queuedBytes -= n;
+            if (chunks[0].length === n) return chunks.shift()!;
+            if (chunks[0].length > n) {
+                const out = chunks[0].subarray(0, n);
+                chunks[0] = chunks[0].subarray(n);
+                return out;
+            }
+            const out = Buffer.allocUnsafe(n);
+            let written = 0;
+            while (written < n) {
+                const head = chunks[0];
+                const need = n - written;
+                if (head.length <= need) {
+                    head.copy(out, written);
+                    written += head.length;
+                    chunks.shift();
+                } else {
+                    head.copy(out, written, 0, need);
+                    chunks[0] = head.subarray(need);
+                    written = n;
+                }
+            }
+            return out;
+        };
+
+        socket.on('data', chunk => {
+            chunks.push(chunk);
+            queuedBytes += chunk.length;
+            if (expected < 0) {
+                if (queuedBytes < 4) return;
+                expected = peek4();
+                consume(4);
+            }
+            if (queuedBytes >= expected) {
+                const cipher = consume(expected);
+                const plain = xorDecrypt(cipher).toString('utf8');
+                try {
+                    finish(undefined, JSON.parse(plain));
+                } catch (e) {
+                    finish(e as Error);
+                }
+            }
+        });
+
+        socket.on('error', e => finish(e));
+        socket.on('close', () => {
+            if (!settled) finish(new Error('kasa iot socket closed before response'));
+        });
+
+        socket.connect(port, options.host, () => {
+            socket.write(payload);
+        });
+    });
+}
+
+// Common helpers used by both plugs/switches and bulbs.
+
+export interface KasaSysInfoCommon {
+    alias?: string;
+    model?: string;
+    mac?: string;
+    mic_mac?: string;
+    deviceId?: string;
+    sw_ver?: string;
+    hw_ver?: string;
+    type?: string;
+    mic_type?: string;
+    dev_name?: string;
+    feature?: string;
+    [k: string]: any;
+}
+
+export async function getSysInfo(options: KasaIotOptions): Promise<KasaSysInfoCommon | undefined> {
+    const r = await kasaIotCall(options, { system: { get_sysinfo: {} } });
+    return r?.system?.get_sysinfo;
+}

package/src/iot/switch.ts

@@ -0,0 +1,5 @@
+import { KasaIotDevice } from './device';
+
+// Plain Kasa wall switches (HS200/HS210/KS200/etc.) — single relay, no brightness.
+// Dimmer switches like KS230 are handled by KasaDimmer instead.
+export class KasaSwitch extends KasaIotDevice {}