scrypted-kasa 1.1.0 → 1.2.2

package/.github/workflows/ci.yml

@@ -11,6 +11,11 @@ concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# Read-only is enough — CI just builds and lints, doesn't push commits, comments, or
+# release artifacts.
+permissions:
+  contents: read
+
 jobs:
   check:
     runs-on: ubuntu-latest

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "scrypted-kasa",
-   "version": "1.1.0",
+   "version": "1.2.2",
    "description": "TP-Link Kasa plugin for Scrypted — cameras (video, two-way audio, spotlight, siren, status LED), plugs/outlets, wall switches, dimmers, and smart bulbs (on/off, brightness, color, color temperature).",
    "author": "Sergey Vilgelm <sergey@vilgelm.com>",
    "license": "MIT",
@@ -73,5 +73,11 @@
       "eslint": "^10.2.1",
       "prettier": "^3.8.3",
       "typescript-eslint": "^8.59.1"
+   },
+   "overrides": {
+      "serialize-javascript": "^7.0.5"
+   },
+   "engines": {
+      "node": ">=20"
    }
 }

package/src/camera/rtsp.ts

@@ -173,7 +173,10 @@ export function handleRtspClient(client: net.Socket, opts: RtspHandlerOptions):
             const headerLines = headerStr.split('\r\n');
             const requestLine = headerLines.shift() || '';
             const [method, uri] = requestLine.split(' ');
-            const headers: Record<string, string> = {};
+            // Null-prototype map so a malicious peer can't reach Object.prototype via a
+            // crafted header name like `__proto__`. Practical risk is tiny — the server
+            // only listens on localhost — but the fix is one line and shuts up CodeQL.
+            const headers = Object.create(null) as Record<string, string>;
             for (const line of headerLines) {
                 const colon = line.indexOf(':');
                 if (colon < 0) continue;

package/src/iot/device.ts

@@ -1,7 +1,7 @@
-import { OnOff, Readme, ScryptedDeviceBase, Setting, Settings, SettingValue } from '@scrypted/sdk';
+import { OnOff, Readme, ScryptedDeviceBase, ScryptedInterface, Setting, Settings, SettingValue } from '@scrypted/sdk';
 import { StorageSettings } from '@scrypted/sdk/storage-settings';
 import { formatKasaMac, renderKv } from '../shared/readme';
-import { KASA_IOT_PORT, getSysInfo, kasaIotCall } from './protocol';
+import { EmeterReading, KASA_IOT_PORT, getEmeterRealtime, getSysInfo, kasaIotCall } from './protocol';
 
 const STATE_POLL_INTERVAL_MS = 30000;
 
@@ -25,6 +25,14 @@ export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff,
             type: 'number',
             defaultValue: KASA_IOT_PORT,
         },
+        // Energy-monitoring capability flag derived from sysinfo.feature (devices report
+        // "TIM:ENE" when they have an emeter). Hidden because users don't toggle it —
+        // it's set at adoption and re-evaluated on every sysinfo poll. Drives whether
+        // the Readme tab fetches and displays the live wattage.
+        hasEmeter: {
+            type: 'boolean',
+            hide: true,
+        },
     });
 
     private pollTimer?: NodeJS.Timeout;
@@ -48,21 +56,77 @@ export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff,
         }, jitter);
     }
 
-    getSettings(): Promise<Setting[]> {
-        return this.storageSettings.getSettings();
+    async getSettings(): Promise<Setting[]> {
+        const base = await this.storageSettings.getSettings();
+        if (!this.storageSettings.values.hasEmeter) return base;
+
+        // Devices with an emeter get a live readout block + a Refresh button so the user
+        // can force a fresh sample without waiting for the 5 s cache to expire. Reads go
+        // through the same cached emeterRealtime() the Readme uses, so opening the
+        // Settings tab right after viewing the Readme is free.
+        const reading = await this.emeterRealtime();
+        const energy: Setting[] = [
+            {
+                key: 'energyPower',
+                group: 'Energy',
+                title: 'Power',
+                readonly: true,
+                value: reading ? `${reading.powerW.toFixed(1)} W` : '?',
+            },
+            {
+                key: 'energyVoltage',
+                group: 'Energy',
+                title: 'Voltage',
+                readonly: true,
+                value: reading ? `${reading.voltageV.toFixed(1)} V` : '?',
+            },
+            {
+                key: 'energyCurrent',
+                group: 'Energy',
+                title: 'Current',
+                readonly: true,
+                value: reading ? `${reading.currentA.toFixed(3)} A` : '?',
+            },
+            {
+                key: 'energyTotal',
+                group: 'Energy',
+                title: 'Total energy',
+                readonly: true,
+                value: reading ? `${(reading.totalWh / 1000).toFixed(3)} kWh` : '?',
+            },
+            {
+                key: 'refreshEnergy',
+                group: 'Energy',
+                title: 'Refresh',
+                description: 'Discard the cached emeter sample and read fresh values from the device.',
+                type: 'button',
+            },
+        ];
+        return [...base, ...energy];
     }
 
-    putSetting(key: string, value: SettingValue): Promise<void> {
+    async putSetting(key: string, value: SettingValue): Promise<void> {
+        if (key === 'refreshEnergy') {
+            // Drop the cached value and fetch fresh; the new reading goes back into the
+            // cache so subsequent renders see it. Emit a Settings event so the UI knows
+            // to re-render with the updated readout fields.
+            this.emeterCache = undefined;
+            await this.emeterRealtime();
+            await this.onDeviceEvent(ScryptedInterface.Settings, undefined);
+            return;
+        }
         return this.storageSettings.putSetting(key, value);
     }
 
     // Per-device Readme tab. Surfaces static identity / network info — live state
     // (on/off, brightness) is not duplicated here, the device page already shows it.
+    // Devices that report energy-monitoring capability also get a live Energy section
+    // (lazy fetch — only fires when the user actually opens the Readme tab).
     async getReadmeMarkdown(): Promise<string> {
         const info = this.info || {};
         const ip = this.storageSettings.values.ip || info.ip || '?';
         const port = this.storageSettings.values.port || KASA_IOT_PORT;
-        return [
+        const lines: string[] = [
             `# ${this.name || 'Kasa Device'}`,
             '',
             '## Device',
@@ -77,11 +141,58 @@ export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff,
             ]),
             '```',
             '',
+        ];
+
+        if (this.storageSettings.values.hasEmeter) {
+            const reading = await this.emeterRealtime();
+            const fmt = (n: number, digits: number) => n.toFixed(digits);
+            const rows: [string, string][] = reading
+                ? [
+                      ['Power', `${fmt(reading.powerW, 1)} W`],
+                      ['Voltage', `${fmt(reading.voltageV, 1)} V`],
+                      ['Current', `${fmt(reading.currentA, 3)} A`],
+                      ['Total', `${fmt(reading.totalWh / 1000, 3)} kWh`],
+                  ]
+                : [
+                      ['Power', '?'],
+                      ['Voltage', '?'],
+                      ['Current', '?'],
+                      ['Total', '?'],
+                  ];
+            lines.push('## Energy', '', '```', renderKv(rows), '```', '');
+        }
+
+        lines.push(
             '## Protocol',
             '',
             `Local TCP/${port} — Kasa's legacy "smarthome" wire format. No cloud account or`,
             'credentials required, the plugin reaches the device directly on the LAN.',
-        ].join('\n');
+        );
+        return lines.join('\n');
+    }
+
+    // Cache the most recent emeter reading for a short window so quick re-renders of
+    // the Readme tab (focus events etc.) don't fan out into multiple TCP queries to the
+    // plug. Errors cache as `undefined` so an offline plug doesn't keep retrying on
+    // every render either — the next miss after the window will try again.
+    private static EMETER_CACHE_MS = 5000;
+    private emeterCache?: { value: EmeterReading | undefined; at: number };
+    private emeterInFlight?: Promise<EmeterReading | undefined>;
+
+    async emeterRealtime(): Promise<EmeterReading | undefined> {
+        const now = Date.now();
+        if (this.emeterCache && now - this.emeterCache.at < KasaIotDevice.EMETER_CACHE_MS) {
+            return this.emeterCache.value;
+        }
+        if (this.emeterInFlight) return this.emeterInFlight;
+        this.emeterInFlight = getEmeterRealtime(this.iotOptions())
+            .catch(() => undefined)
+            .finally(() => {
+                this.emeterInFlight = undefined;
+            });
+        const value = await this.emeterInFlight;
+        this.emeterCache = { value, at: Date.now() };
+        return value;
     }
 
     async turnOn(): Promise<void> {
@@ -107,6 +218,13 @@ export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff,
         const sys = await getSysInfo(this.iotOptions());
         if (!sys) return;
         if (typeof sys.relay_state === 'number') this.on = sys.relay_state === 1;
+        // Energy-monitoring capability is advertised in sysinfo.feature as "ENE"
+        // (e.g. "TIM:ENE"). Cache the boolean so the Readme tab knows whether to
+        // bother fetching live wattage.
+        const hasEmeter = /ENE/i.test(typeof sys.feature === 'string' ? sys.feature : '');
+        if (this.storageSettings.values.hasEmeter !== hasEmeter) {
+            this.storageSettings.values.hasEmeter = hasEmeter;
+        }
         // Subclasses with extra state extend via onSysInfo hook.
         this.onSysInfo(sys);
     }

package/src/iot/protocol.ts

@@ -141,3 +141,42 @@ export async function getSysInfo(options: KasaIotOptions): Promise<KasaSysInfoCo
     const r = await kasaIotCall(options, { system: { get_sysinfo: {} } });
     return r?.system?.get_sysinfo;
 }
+
+// Energy-monitoring readout for plugs that report sysinfo.feature containing "ENE"
+// (HS110, KP115, KP125, EP25, HS220, ...). The plug answers `emeter.get_realtime` with
+// either the newer milli-units schema or the older base-unit schema:
+//
+//   newer:  { voltage_mv, current_ma, power_mw, total_wh, err_code }
+//   older:  { voltage,    current,    power,    total,    err_code }   // V, A, W, kWh
+//
+// Normalize to a single V/A/W/Wh shape so callers don't care which firmware they're on.
+// Returns undefined on err_code or when neither schema matches.
+export interface EmeterReading {
+    voltageV: number;
+    currentA: number;
+    powerW: number;
+    totalWh: number;
+}
+
+export async function getEmeterRealtime(options: KasaIotOptions): Promise<EmeterReading | undefined> {
+    const r = await kasaIotCall(options, { emeter: { get_realtime: {} } });
+    const e = r?.emeter?.get_realtime;
+    if (!e || e.err_code) return undefined;
+    if (typeof e.voltage_mv === 'number') {
+        return {
+            voltageV: e.voltage_mv / 1000,
+            currentA: (e.current_ma ?? 0) / 1000,
+            powerW: (e.power_mw ?? 0) / 1000,
+            totalWh: e.total_wh ?? 0,
+        };
+    }
+    if (typeof e.voltage === 'number') {
+        return {
+            voltageV: e.voltage,
+            currentA: e.current ?? 0,
+            powerW: e.power ?? 0,
+            totalWh: (e.total ?? 0) * 1000,
+        };
+    }
+    return undefined;
+}

package/src/main.ts

@@ -1206,7 +1206,13 @@ class KasaPlugin
     }
 
     async adoptDevice(adopt: AdoptDevice): Promise<string> {
-        const entry = this.discoveredDevices.get(adopt.nativeId);
+        // ScryptedNativeId is `string | undefined`; the AdoptDevice flow always passes
+        // a real id (it came from a DiscoveredDevice we ourselves emitted), but TS6
+        // tightened the inference and won't narrow it for us.
+        const nativeId = adopt.nativeId;
+        if (!nativeId) throw new Error('adoptDevice called without a nativeId');
+
+        const entry = this.discoveredDevices.get(nativeId);
         if (!entry) throw new Error('kasa device not found in discovered set; rescan and try again');
 
         const { device } = entry;
@@ -1217,32 +1223,33 @@ class KasaPlugin
         const room = adopt.settings.room?.toString() || undefined;
 
         let id: string;
-        if (cls === 'camera') id = await this.adoptCamera(adopt, device, name, room);
-        else id = await this.adoptIotDevice(adopt, device, cls, name, room);
+        if (cls === 'camera') id = await this.adoptCamera(adopt, nativeId, device, name, room);
+        else id = await this.adoptIotDevice(adopt, nativeId, device, cls, name, room);
 
         clearTimeout(entry.timeout);
-        this.discoveredDevices.delete(adopt.nativeId);
+        this.discoveredDevices.delete(nativeId);
         void this.onDeviceEvent(ScryptedInterface.DeviceDiscovery, undefined);
         return id;
     }
 
     private async adoptCamera(
         adopt: AdoptDevice,
+        nativeId: string,
         device: KasaDiscoveredDevice,
         name: string,
         room?: string,
     ): Promise<string> {
         // deviceId is the Kasa-issued 40-char hex per-unit identifier — treat it as the
         // serial number, which is what HomeKit and the UI expect under that label.
-        await this.registerCamera(adopt.nativeId, name, room, {
+        await this.registerCamera(nativeId, name, room, {
             model: device.model,
             mac: device.mac,
             ip: device.address,
             serialNumber: device.deviceId,
             firmware: typeof device.sysinfo?.sw_ver === 'string' ? device.sysinfo.sw_ver : undefined,
         });
-        deviceManager.getDeviceStorage(adopt.nativeId).setItem('kasaClass', 'camera');
-        const camera = (await this.getDevice(adopt.nativeId)) as KasaCamera;
+        deviceManager.getDeviceStorage(nativeId).setItem('kasaClass', 'camera');
+        const camera = (await this.getDevice(nativeId)) as KasaCamera;
 
         camera.storageSettings.values.ip = device.address;
         camera.storageSettings.values.port = KASA_DEFAULT_PORT;
@@ -1257,6 +1264,7 @@ class KasaPlugin
 
     private async adoptIotDevice(
         adopt: AdoptDevice,
+        nativeId: string,
         device: KasaDiscoveredDevice,
         cls: KasaDeviceClass,
         name: string,
@@ -1289,7 +1297,7 @@ class KasaPlugin
 
         const sw_ver = typeof device.sysinfo?.sw_ver === 'string' ? device.sysinfo.sw_ver : undefined;
         await deviceManager.onDeviceDiscovered({
-            nativeId: adopt.nativeId,
+            nativeId,
             name,
             type,
             interfaces,
@@ -1307,9 +1315,9 @@ class KasaPlugin
         // Persist the class marker so getDevice routes to the right implementation —
         // multiple device classes share the same Scrypted device type (true bulbs and
         // dimmers both register as Light).
-        deviceManager.getDeviceStorage(adopt.nativeId).setItem('kasaClass', storedClass);
+        deviceManager.getDeviceStorage(nativeId).setItem('kasaClass', storedClass);
 
-        const dev = await this.getDevice(adopt.nativeId);
+        const dev = await this.getDevice(nativeId);
         dev.storageSettings.values.ip = device.address;
         dev.storageSettings.values.port = KASA_IOT_PORT;
         if (cls === 'bulb' && dev instanceof KasaBulb) {
@@ -1324,7 +1332,10 @@ class KasaPlugin
     // Routes a nativeId to the right device class. Adoption persists a `kasaClass` storage
     // marker (camera/plug/switch/bulb) which is the source of truth here — the Scrypted
     // device type alone is ambiguous (e.g. both true bulbs and dimmer plugs are `Light`).
-    async getDevice(nativeId: string): Promise<any> {
+    async getDevice(nativeId: ScryptedNativeId): Promise<any> {
+        // The DeviceProvider contract types nativeId as nullable; the plugin device itself
+        // (no nativeId) routes here too and we have nothing to instantiate for it.
+        if (!nativeId) return undefined;
         let dev = this.devices.get(nativeId);
         if (!dev) {
             dev = this.instantiateDevice(nativeId);

package/tsconfig.json

@@ -1,5 +1,6 @@
 {
     "compilerOptions": {
+        "rootDir": "src",
         "outDir": "build",
         "module": "Node16",
         "target": "ES2021",