scrypted-kasa 1.0.1 → 1.2.2

package/.github/workflows/ci.yml

@@ -11,13 +11,18 @@ 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
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
           cache: 'npm'

package/.github/workflows/publish.yml

@@ -15,9 +15,9 @@ jobs:
       # via the GitHub OIDC token so consumers can verify it was built by this workflow.
       id-token: write
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version-file: '.nvmrc'
           cache: 'npm'

package/.nvmrc

@@ -1 +1 @@
-v24
+v25

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/scrypted-kasa.svg)](https://www.npmjs.com/package/scrypted-kasa)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-Adds support for the TP-Link Kasa device family to Scrypted: cameras, plugs/outlets,
+Adds support for the TP-Link Kasa device family to [Scrypted](https://www.scrypted.app): cameras, plugs/outlets,
 switches/dimmers, and bulbs. Discovery is unified — one UDP/9999 sweep finds everything
 and the plugin routes each device to the right Scrypted interfaces.
 

package/package.json

@@ -1,6 +1,6 @@
 {
    "name": "scrypted-kasa",
-   "version": "1.0.1",
+   "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",
@@ -58,7 +58,9 @@
          "ScryptedDeviceCreator",
          "DeviceProvider",
          "DeviceCreator",
-         "DeviceDiscovery"
+         "DeviceDiscovery",
+         "Readme",
+         "Settings"
       ],
       "pluginDependencies": [
          "@scrypted/prebuffer-mixin"
@@ -67,9 +69,15 @@
    "devDependencies": {
       "@eslint/js": "^10.0.1",
       "@scrypted/sdk": "^0.5.59",
-      "@types/node": "^24.12.2",
+      "@types/node": "^25.6.0",
       "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/api.ts

@@ -14,11 +14,26 @@ export const KASA_STREAM_PATH = '/https/stream/mixed';
 // retaining memory.
 const MAX_HEADER_BYTES = 32 * 1024;
 
-// Socket idle timeout. Doubles as a connect timeout (a camera that's reachable on TCP but
-// never finishes TLS / never sends headers will hit this) AND as a stream-stall timeout
-// (real cameras stream continuously; a 10 s silence means the camera or network is dead).
-// Without this, a hung camera causes getVideoStream to block indefinitely.
-const KASA_STREAM_IDLE_TIMEOUT_MS = 10000;
+// Connect-phase idle timeout: while establishing the HTTPS request and waiting for response
+// headers, fires only if the socket is idle for this long. Covers TLS handshake hangs and
+// unresponsive-but-routable cameras — but it's not a strict wall-clock deadline if there
+// is intermittent socket activity without headers arriving. Once headers arrive we clear
+// the socket timeout because kasa cameras on marginal Wi-Fi can go briefly silent (channel
+// scan, AP roam, transient congestion) and recover; killing the stream on every such gap
+// causes more harm than good. Half-open TCP detection is delegated to OS keepalive (see
+// setKeepAlive below) so a Wi-Fi drop without a clean FIN still gets cleaned up.
+const KASA_STREAM_CONNECT_TIMEOUT_MS = 10000;
+
+// Initial idle before the OS sends the first TCP keepalive probe on the streaming socket.
+// During normal streaming, frame-level data activity resets this timer so probes never
+// fire. If the connection dies (Wi-Fi drop, NAT timeout, switch reset), keepalive probes
+// eventually cause the OS to close the socket and our `body.on('close')` triggers teardown.
+// Note: `socket.setKeepAlive(true, initialDelay)` controls only this initial idle period
+// (TCP_KEEPIDLE); total detection/teardown time still depends on OS-level keepalive
+// interval (TCP_KEEPINTVL) and probe count (TCP_KEEPCNT). Linux defaults are often too
+// slow for a live video stream (TCP_KEEPIDLE may default to 7200 s), so 30 s here just
+// starts probing sooner after the stream goes idle.
+const KASA_STREAM_KEEPALIVE_INITIAL_DELAY_MS = 30000;
 
 export const KasaMimeVideo = 'video/x-h264';
 export const KasaMimeG711U = 'audio/g711u';
@@ -99,9 +114,6 @@ export class KasaClient {
 
         // Cameras present a self-signed cert. The body is consumed as a long-lived stream
         // rather than buffered to completion, so we don't read the response body here.
-        // The setTimeout below covers both the initial connect/handshake and ongoing stream
-        // idleness — Node's socket idle timeout resets on activity, so a continuously
-        // streaming camera never trips it; only stalls or unanswered handshakes do.
         const response = await new Promise<IncomingMessage>((resolve, reject) => {
             const req = https.request(
                 {
@@ -116,10 +128,23 @@ export class KasaClient {
                         Connection: 'keep-alive',
                     },
                 },
-                resolve,
+                response => {
+                    // Headers in — clear the connect-phase idle timeout so it doesn't
+                    // keep firing during normal streaming gaps. setTimeout(0) on the
+                    // underlying socket disables Node's idle-timeout machinery.
+                    response.socket?.setTimeout(0);
+                    // Enable OS-level TCP keepalive as a safety net for half-open
+                    // detection. During normal streaming the data flow keeps this from
+                    // firing, but if Wi-Fi drops / NAT times out without a clean FIN,
+                    // keepalive probes will eventually fail and the kernel will close
+                    // the socket — without keepalive we'd block forever in readPart()
+                    // waiting for a multipart header that never arrives.
+                    response.socket?.setKeepAlive(true, KASA_STREAM_KEEPALIVE_INITIAL_DELAY_MS);
+                    resolve(response);
+                },
             );
-            req.setTimeout(KASA_STREAM_IDLE_TIMEOUT_MS, () => {
-                req.destroy(new Error(`kasa stream socket idle timeout after ${KASA_STREAM_IDLE_TIMEOUT_MS}ms`));
+            req.setTimeout(KASA_STREAM_CONNECT_TIMEOUT_MS, () => {
+                req.destroy(new Error(`kasa stream connect timeout after ${KASA_STREAM_CONNECT_TIMEOUT_MS}ms`));
             });
             req.on('error', reject);
             req.end();

package/src/camera/rtsp.ts

@@ -153,7 +153,7 @@ export function handleRtspClient(client: net.Socket, opts: RtspHandlerOptions):
     };
 
     const HEADER_TERMINATOR = Buffer.from('\r\n\r\n');
-    client.on('data', chunk => {
+    client.on('data', (chunk: Buffer) => {
         buffered = buffered.length === 0 ? chunk : Buffer.concat([buffered, chunk]);
         // Parse messages until we run out of complete ones in the buffer.
         while (buffered.length > 0) {
@@ -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/camera/stream.ts

@@ -49,6 +49,17 @@ export interface KasaStreamOptions {
     kasa: KasaClient;
     ffmpegPath: string;
     console: Console;
+    // Optional cached SPS/PPS from a previous session. When present we skip the
+    // preScanSpsPps wait (which holds getVideoStream up to ~2s on KC420WS waiting for the
+    // next IDR) and start streaming live parts immediately. Cached values come from this
+    // camera's own previous bitstream so they're correct unless the encoder profile
+    // changed (resolution / bitrate setting); even when stale, the in-band SPS/PPS that
+    // arrive with the next IDR will replace them at the consumer's decoder.
+    cachedSps?: Buffer;
+    cachedPps?: Buffer;
+    // Called when we successfully scanned fresh SPS/PPS from the live bitstream. The
+    // caller persists these so subsequent sessions can use the cached path.
+    onFreshSpsPps?: (sps: Buffer, pps: Buffer) => void;
 }
 
 export interface KasaStreamHandle {
@@ -233,9 +244,50 @@ async function pumpKasa(
 // Returns a handle whose `kill()` tears down everything (kasa, ffmpeg, UDP sockets, TCP
 // server, active client) and whose `exited` promise resolves once that teardown is done.
 export async function spawnKasaStream(opts: KasaStreamOptions): Promise<KasaStreamHandle> {
-    const { kasa, ffmpegPath, console } = opts;
+    const { kasa, ffmpegPath, console, cachedSps, cachedPps, onFreshSpsPps } = opts;
+
+    // Fast path: caller supplied cached SPS/PPS from a previous session. Skip the scan and
+    // start streaming live parts immediately — saves the ~1-2s preScanSpsPps wait on cold
+    // starts, which dominates HomeKit's perceived stream-open latency.
+    // Validate cached buffers before trusting them. Storage corruption / schema drift /
+    // mistakenly-stored garbage would otherwise produce an SDP with an invalid
+    // profile-level-id (derived from sps[1..4]) or sprop-parameter-sets, and consumers
+    // would fail SETUP rather than recovering from in-band SPS/PPS.
+    // H.264 NAL header byte: low 5 bits = nal_unit_type. SPS = 7, PPS = 8.
+    // SPS minimum length = 4 (NAL header byte + 3 profile bytes used in the SDP).
+    const cacheValid =
+        !!cachedSps &&
+        !!cachedPps &&
+        cachedSps.length >= 4 &&
+        cachedPps.length >= 1 &&
+        (cachedSps[0] & 0x1f) === 7 &&
+        (cachedPps[0] & 0x1f) === 8;
+    if ((cachedSps || cachedPps) && !cacheValid) {
+        // Caller will overwrite the bad cache via onFreshSpsPps below once the slow path
+        // produces fresh values; nothing to do here beyond logging and falling through.
+        console.warn('[kasa-stream] cached SPS/PPS failed validation; falling back to in-band scan');
+    }
 
-    const { sps, pps, buffered } = await preScanSpsPps(kasa);
+    let sps: Buffer;
+    let pps: Buffer;
+    let buffered: KasaPart[];
+    if (cacheValid) {
+        sps = cachedSps!;
+        pps = cachedPps!;
+        buffered = [];
+    } else {
+        const scanned = await preScanSpsPps(kasa);
+        sps = scanned.sps;
+        pps = scanned.pps;
+        buffered = scanned.buffered;
+        // Persist for next time. Pass the original error object (not just .message) so
+        // stack/context survive — non-Error throws would lose everything otherwise.
+        try {
+            onFreshSpsPps?.(sps, pps);
+        } catch (e) {
+            console.warn('[kasa-stream] onFreshSpsPps callback threw', e);
+        }
+    }
     const sdp = buildSdp(sps, pps);
 
     const videoUdp = await bindUdpPair();

package/src/iot/bulb.ts

@@ -4,12 +4,14 @@ import {
     ColorSettingHsv,
     ColorSettingTemperature,
     OnOff,
+    Readme,
     ScryptedDeviceBase,
     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';
 
 const STATE_POLL_INTERVAL_MS = 30000;
@@ -26,7 +28,7 @@ const STATE_POLL_INTERVAL_MS = 30000;
 // in `getTemperatureMinK`/`getTemperatureMaxK` and fall back to a safe pair otherwise.
 export class KasaBulb
     extends ScryptedDeviceBase
-    implements OnOff, Brightness, ColorSettingHsv, ColorSettingTemperature, Settings
+    implements OnOff, Brightness, ColorSettingHsv, ColorSettingTemperature, Settings, Readme
 {
     storageSettings = new StorageSettings(this, {
         ip: {
@@ -86,6 +88,49 @@ export class KasaBulb
         return this.storageSettings.putSetting(key, value);
     }
 
+    // Per-device Readme tab. Bulbs don't share KasaIotDevice's base implementation
+    // (different inheritance chain because of the color/brightness mixins), so the
+    // structure is duplicated here on purpose. Adds the static capability list (color /
+    // color-temp range) since those depend on per-model sysinfo flags. Live state is not
+    // duplicated here — the device page already shows it.
+    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;
+        const { isColor, isVariableColorTemp, colorTemperatureMinK, colorTemperatureMaxK } =
+            this.storageSettings.values;
+
+        const capabilities: string[] = ['Brightness'];
+        if (isColor) capabilities.push('Color (HSV)');
+        if (isVariableColorTemp)
+            capabilities.push(`Color temperature (${colorTemperatureMinK}–${colorTemperatureMaxK} K)`);
+
+        return [
+            `# ${this.name || 'Kasa Bulb'}`,
+            '',
+            '## Device',
+            '',
+            '```',
+            renderKv([
+                ['Model', info.model || '?'],
+                ['Firmware', info.firmware || '?'],
+                ['MAC', formatKasaMac(info.mac)],
+                ['IP', ip],
+                ['Port', String(port)],
+            ]),
+            '```',
+            '',
+            '## Capabilities',
+            '',
+            ...capabilities.map(c => `- ${c}`),
+            '',
+            '## Protocol',
+            '',
+            `Local TCP/${port} — Kasa's legacy "smarthome" wire format. All bulb state changes`,
+            'are issued via `smartlife.iot.smartbulb.lightingservice.transition_light_state`.',
+        ].join('\n');
+    }
+
     async turnOn(): Promise<void> {
         await this.lightState({ on_off: 1 });
         this.on = true;

package/src/iot/device.ts

@@ -1,6 +1,7 @@
-import { OnOff, 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 { KASA_IOT_PORT, getSysInfo, kasaIotCall } from './protocol';
+import { formatKasaMac, renderKv } from '../shared/readme';
+import { EmeterReading, KASA_IOT_PORT, getEmeterRealtime, getSysInfo, kasaIotCall } from './protocol';
 
 const STATE_POLL_INTERVAL_MS = 30000;
 
@@ -13,7 +14,7 @@ const STATE_POLL_INTERVAL_MS = 30000;
 //   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 {
+export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff, Settings, Readme {
     storageSettings = new StorageSettings(this, {
         ip: {
             title: 'IP Address',
@@ -24,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;
@@ -47,14 +56,145 @@ 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;
+        const lines: string[] = [
+            `# ${this.name || 'Kasa Device'}`,
+            '',
+            '## Device',
+            '',
+            '```',
+            renderKv([
+                ['Model', info.model || '?'],
+                ['Firmware', info.firmware || '?'],
+                ['MAC', formatKasaMac(info.mac)],
+                ['IP', ip],
+                ['Port', String(port)],
+            ]),
+            '```',
+            '',
+        ];
+
+        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.',
+        );
+        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> {
         await this.callIot({ system: { set_relay_state: { state: 1 } } });
         this.on = true;
@@ -78,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

@@ -90,7 +90,7 @@ export async function kasaIotCall(options: KasaIotOptions, command: Record<strin
             return out;
         };
 
-        socket.on('data', chunk => {
+        socket.on('data', (chunk: Buffer) => {
             chunks.push(chunk);
             queuedBytes += chunk.length;
             if (expected < 0) {
@@ -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

@@ -10,6 +10,7 @@ import sdk, {
     Intercom,
     MediaObject,
     OnOff,
+    Readme,
     RequestMediaStreamOptions,
     ResponseMediaStreamOptions,
     ScryptedDeviceBase,
@@ -35,6 +36,7 @@ import { KasaPlug } from './iot/plug';
 import { KASA_IOT_PORT } from './iot/protocol';
 import { KasaSwitch } from './iot/switch';
 import { discoverKasa, KasaDiscoveredDevice } from './shared/discovery';
+import { formatKasaMac, renderKv } from './shared/readme';
 
 // G.711 µ-law packetization: 8000 samples/sec * 1 byte/sample = 160 bytes/20ms.
 // 20 ms is the standard RTP packetization for PCMU and matches what the Kasa app appears
@@ -182,7 +184,7 @@ class KasaCameraSiren extends ScryptedDeviceBase implements OnOff {
     }
 }
 
-class KasaCamera extends ScryptedDeviceBase implements VideoCamera, Settings, Intercom, DeviceProvider, OnOff {
+class KasaCamera extends ScryptedDeviceBase implements VideoCamera, Settings, Intercom, DeviceProvider, OnOff, Readme {
     private intercomSession?: KasaTalkSession;
     private intercomFfmpeg?: ChildProcess;
     private spotlight?: KasaCameraSpotlight;
@@ -318,6 +320,47 @@ class KasaCamera extends ScryptedDeviceBase implements VideoCamera, Settings, In
         return this.storageSettings.getSettings();
     }
 
+    // Per-camera Readme tab. Surfaces what the user can't easily see otherwise: the
+    // firmware/serial the adopted device reports and which HTTPS ports the plugin is
+    // talking to (stream / talk / control). Live state (LED on/off, spotlight on/off,
+    // motion, ...) is not duplicated here — the device page already shows it live.
+    async getReadmeMarkdown(): Promise<string> {
+        const info = this.info || {};
+        const { ip, port } = this.storageSettings.values;
+        const ipLine = ip || info.ip || '?';
+        const streamPort = port || KASA_DEFAULT_PORT;
+        return [
+            `# ${this.name || 'Kasa Camera'}`,
+            '',
+            '## Device',
+            '',
+            '```',
+            renderKv([
+                ['Model', info.model || '?'],
+                ['Firmware', info.firmware || '?'],
+                ['Serial', info.serialNumber || '?'],
+                ['MAC', formatKasaMac(info.mac)],
+                ['IP', ipLine],
+                ['Stream port', String(streamPort)],
+            ]),
+            '```',
+            '',
+            '## Endpoints',
+            '',
+            'The plugin talks to the camera over three separate HTTPS endpoints. The talk and',
+            'control endpoints are fixed in the camera firmware; the stream port can be edited',
+            "in the camera's Settings tab if needed:",
+            '',
+            '```',
+            renderKv([
+                ['Stream', `https://${ipLine}:${streamPort}/https/stream/mixed`],
+                ['Talk', `https://${ipLine}:${KASA_TALK_PORT}/https/speaker/audio/g711block`],
+                ['Control', `https://${ipLine}:10443/data/LINKIE2.json`],
+            ]),
+            '```',
+        ].join('\n');
+    }
+
     async putSetting(key: string, value: SettingValue): Promise<void> {
         await this.storageSettings.putSetting(key, value);
         if (key === 'ip' || key === 'port' || key === 'username' || key === 'password') {
@@ -389,9 +432,29 @@ class KasaCamera extends ScryptedDeviceBase implements VideoCamera, Settings, In
         kasa.body.on('error', () => kill.resolve());
 
         const ffmpegPath = await mediaManager.getFFmpegPath();
+        // Read cached SPS/PPS from per-device storage. Lets spawnKasaStream skip the
+        // ~1-2s preScanSpsPps wait on cold starts (HomeKit's perceived latency dominates
+        // here). Cache survives plugin restarts. Stale-cache risk is bounded — in-band
+        // SPS/PPS in the live bitstream supersede whatever we put in the SDP.
+        const storage = deviceManager.getDeviceStorage(this.nativeId);
+        const cachedSpsB64 = storage?.getItem('cachedSps') || undefined;
+        const cachedPpsB64 = storage?.getItem('cachedPps') || undefined;
+        const cachedSps = cachedSpsB64 ? Buffer.from(cachedSpsB64, 'base64') : undefined;
+        const cachedPps = cachedPpsB64 ? Buffer.from(cachedPpsB64, 'base64') : undefined;
+
         let stream: KasaStreamHandle;
         try {
-            stream = await spawnKasaStream({ kasa, ffmpegPath, console: this.console });
+            stream = await spawnKasaStream({
+                kasa,
+                ffmpegPath,
+                console: this.console,
+                cachedSps,
+                cachedPps,
+                onFreshSpsPps: (sps, pps) => {
+                    storage?.setItem('cachedSps', sps.toString('base64'));
+                    storage?.setItem('cachedPps', pps.toString('base64'));
+                },
+            });
         } catch (e) {
             kasa.destroy();
             throw e;
@@ -562,7 +625,21 @@ interface KasaDiscoveryEntry {
     timeout: NodeJS.Timeout;
 }
 
-class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCreator, DeviceDiscovery {
+interface InventoryEntry {
+    name: string;
+    model: string;
+    firmware: string;
+    ip: string;
+    mac: string;
+}
+
+const INVENTORY_GROUPS = ['Cameras', 'Bulbs / Dimmers', 'Plugs', 'Switches'] as const;
+type InventoryGroup = (typeof INVENTORY_GROUPS)[number];
+
+class KasaPlugin
+    extends ScryptedDeviceBase
+    implements DeviceProvider, DeviceCreator, DeviceDiscovery, Readme, Settings
+{
     devices = new Map<string, KasaCamera | KasaPlug | KasaSwitch | KasaDimmer | KasaBulb>();
     discoveredDevices = new Map<string, KasaDiscoveryEntry>();
     // In-flight scan so concurrent scan=true calls share one network round-trip instead of
@@ -578,8 +655,250 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
         super(nativeId);
         this.systemDevice = {
             deviceCreator: 'Device',
-            deviceDiscovery: 'Kasa Devices',
+            // Singular noun — Scrypted's UI auto-pluralizes the label, so 'Kasa Devices'
+            // would render as "Kasa Devicess".
+            deviceDiscovery: 'Kasa Device',
+        };
+        // Devices adopted before Readme was added need their interface lists topped up so
+        // the Readme tab actually shows on the device page. Defer to next tick so the SDK
+        // is fully wired before we walk the device manager.
+        process.nextTick(() => this.migrateAddReadme().catch(e => this.console.warn('migrateAddReadme failed', e)));
+    }
+
+    // Plugin Settings tab — single button that re-runs UDP discovery and refreshes the
+    // model / firmware / IP / MAC reported on every adopted device. Useful after a
+    // firmware update, a device rename in the Kasa app, or a DHCP-rotated IP.
+    async getSettings(): Promise<Setting[]> {
+        return [
+            {
+                key: 'refresh',
+                title: 'Refresh devices',
+                description:
+                    'Re-run UDP discovery and update model, firmware, IP, and MAC for every adopted ' +
+                    'Kasa device. Devices not currently reachable on the LAN are skipped.',
+                type: 'button',
+            },
+        ];
+    }
+
+    async putSetting(key: string, _value: SettingValue): Promise<void> {
+        if (key === 'refresh') await this.refreshAllDevices();
+    }
+
+    // Shared in-flight promise so two clicks of the Refresh button don't kick off two
+    // overlapping discovery sweeps. Same pattern as scanInFlight in discoverDevices.
+    private refreshInFlight?: Promise<void>;
+
+    // Re-run UDP discovery and update each adopted device's `info` (model, firmware, IP,
+    // MAC) from the fresh sysinfo response. Devices that don't respond to the sweep
+    // (powered off, on a different subnet) are left alone — we don't want to clobber
+    // good cached data with a one-shot network blip.
+    private async refreshAllDevices(): Promise<void> {
+        if (this.refreshInFlight) return this.refreshInFlight;
+        this.refreshInFlight = this.refreshAllDevicesInternal().finally(() => {
+            this.refreshInFlight = undefined;
+        });
+        return this.refreshInFlight;
+    }
+
+    private async refreshAllDevicesInternal(): Promise<void> {
+        this.console.log('refresh: running UDP discovery sweep');
+        const responses = await discoverKasa(2500, this.console).catch(e => {
+            this.console.error('refresh: discovery failed', e);
+            return [] as KasaDiscoveredDevice[];
+        });
+
+        // Auto-discovered devices use the Kasa deviceId as their nativeId, but
+        // manually-created ones (createDevice) get a random nativeId — those would
+        // never match here. Build a MAC index too so we can fall back to matching by
+        // the MAC the device's `info` was stamped with.
+        const normalizeMac = (mac: string | undefined): string => (mac ? mac.replace(/[:-]/g, '').toLowerCase() : '');
+        const byDeviceId = new Map(responses.map(r => [r.deviceId, r]));
+        const byMac = new Map<string, KasaDiscoveredDevice>();
+        for (const r of responses) {
+            const k = normalizeMac(r.mac);
+            if (k) byMac.set(k, r);
+        }
+
+        // Prefer the freshly-observed string when it's non-empty, otherwise keep the
+        // existing value. Discovery responses occasionally surface empty fields (and
+        // sw_ver may be missing entirely), and we don't want a refresh to clobber
+        // good cached data with an undefined.
+        const preferStr = (fresh: string | undefined, existing: string | undefined): string | undefined =>
+            fresh && fresh.trim() ? fresh : existing;
+
+        let updated = 0;
+        const missing: string[] = [];
+        for (const nativeId of deviceManager.getNativeIds()) {
+            if (!nativeId) continue;
+            // Spotlight / siren children share the parent camera's sysinfo and are
+            // already maintained by KasaCamera.refreshChildDevices.
+            if (nativeId.endsWith('-spotlight') || nativeId.endsWith('-siren')) continue;
+            const state = deviceManager.getDeviceState(nativeId);
+            if (!state) continue;
+
+            // Try deviceId match first (auto-discovered), then MAC match (covers
+            // manually-created devices and any deviceId mismatches).
+            let fresh = byDeviceId.get(nativeId);
+            if (!fresh) {
+                const macKey = normalizeMac(state.info?.mac);
+                if (macKey) fresh = byMac.get(macKey);
+            }
+            if (!fresh) {
+                missing.push(state.name || nativeId);
+                continue;
+            }
+
+            const existing = state.info || {};
+            const sw_ver = typeof fresh.sysinfo?.sw_ver === 'string' ? fresh.sysinfo.sw_ver : undefined;
+            const newInfo = {
+                ...existing,
+                manufacturer: 'TP-Link Kasa',
+                model: preferStr(fresh.model, existing.model),
+                mac: preferStr(fresh.mac, existing.mac),
+                // IP always takes the freshly-observed value — capturing a DHCP-rotated
+                // address is the whole point of the refresh.
+                ip: fresh.address,
+                firmware: preferStr(sw_ver, existing.firmware),
+            };
+
+            // Re-publish without touching providedInterfaces — refreshing metadata, not
+            // capabilities. Mixin-provided interfaces (HomeKit, etc.) live in `interfaces`
+            // and would be incorrectly re-claimed if we passed those back.
+            await deviceManager.onDeviceDiscovered({
+                nativeId,
+                name: state.name || nativeId,
+                type: (state.type || ScryptedDeviceType.Unknown) as ScryptedDeviceType,
+                interfaces: state.providedInterfaces || [],
+                info: newInfo,
+                room: state.room || undefined,
+            });
+
+            // Keep per-device storage in sync — that's what the device classes actually
+            // use to connect. Update the in-memory storageSettings too if the device is
+            // already instantiated, otherwise it would keep using the stale IP until
+            // restarted.
+            const storage = deviceManager.getDeviceStorage(nativeId);
+            storage?.setItem('ip', fresh.address);
+            const dev = this.devices.get(nativeId);
+            if (dev?.storageSettings) dev.storageSettings.values.ip = fresh.address;
+
+            updated++;
+        }
+
+        const summary = `refresh: ${updated} updated, ${missing.length} not found on LAN`;
+        this.console.log(missing.length ? `${summary} (${missing.join(', ')})` : summary);
+    }
+
+    // One-time interface migration for devices adopted before this plugin exposed Readme.
+    // Walks every nativeId and re-publishes the device with Readme appended to its
+    // providedInterfaces. No-ops once every device already advertises Readme, so it's safe
+    // to leave running on every plugin start.
+    private async migrateAddReadme(): Promise<void> {
+        for (const nativeId of deviceManager.getNativeIds()) {
+            if (!nativeId) continue;
+            // Spotlight / siren children only expose OnOff — no Readme to add. They're
+            // re-published by KasaCamera.refreshChildDevices anyway.
+            if (nativeId.endsWith('-spotlight') || nativeId.endsWith('-siren')) continue;
+            const state = deviceManager.getDeviceState(nativeId);
+            if (!state) continue;
+            // providedInterfaces is the list this plugin originally registered; the
+            // `interfaces` field also includes mixin-provided interfaces (HomeKit, etc.)
+            // which we must NOT re-claim ownership of by passing them back to
+            // onDeviceDiscovered.
+            const provided = state.providedInterfaces || [];
+            if (provided.includes(ScryptedInterface.Readme)) continue;
+            await deviceManager.onDeviceDiscovered({
+                nativeId,
+                name: state.name || nativeId,
+                type: (state.type || ScryptedDeviceType.Unknown) as ScryptedDeviceType,
+                interfaces: [...provided, ScryptedInterface.Readme],
+                info: state.info,
+                room: state.room || undefined,
+            });
+        }
+    }
+
+    // Walks every adopted device and groups by Scrypted device type for the Readme
+    // inventory. Child devices (spotlight / siren under each camera) are filtered out —
+    // they share the parent camera's firmware so listing them separately is just noise.
+    //
+    // IP comes from per-device storage (the value the plugin actually uses to connect)
+    // rather than `state.info.ip` (only set at adoption, doesn't reflect a manual edit
+    // in per-device Settings or a DHCP-rotated update). Falls back to info.ip if the
+    // storage value is missing — defends against legacy adoption paths that didn't
+    // initialize the storage.
+    private inventory(): Record<InventoryGroup, InventoryEntry[]> {
+        const groups: Record<InventoryGroup, InventoryEntry[]> = {
+            Cameras: [],
+            'Bulbs / Dimmers': [],
+            Plugs: [],
+            Switches: [],
         };
+
+        for (const nativeId of deviceManager.getNativeIds()) {
+            if (!nativeId) continue;
+            if (nativeId.endsWith('-spotlight') || nativeId.endsWith('-siren')) continue;
+
+            const state = deviceManager.getDeviceState(nativeId);
+            if (!state) continue;
+
+            const type = state.type as ScryptedDeviceType | undefined;
+            const info = (state.info || {}) as { model?: string; firmware?: string; ip?: string; mac?: string };
+            const storedIp = deviceManager.getDeviceStorage(nativeId)?.getItem('ip');
+            const entry: InventoryEntry = {
+                name: state.name || '<unknown>',
+                model: info.model || '?',
+                firmware: info.firmware || '?',
+                ip: storedIp || info.ip || '?',
+                mac: info.mac || '?',
+            };
+
+            if (type === ScryptedDeviceType.Camera) groups['Cameras'].push(entry);
+            else if (type === ScryptedDeviceType.Light) groups['Bulbs / Dimmers'].push(entry);
+            else if (type === ScryptedDeviceType.Outlet) groups['Plugs'].push(entry);
+            else if (type === ScryptedDeviceType.Switch) groups['Switches'].push(entry);
+        }
+
+        // Sort by name within each group for stable display order across renders.
+        for (const entries of Object.values(groups)) entries.sort((a, b) => a.name.localeCompare(b.name));
+        return groups;
+    }
+
+    // Plugin Readme tab — inventory data formatted as pre-aligned text inside fenced
+    // code blocks. We avoid GFM-style pipe tables because Scrypted's markdown renderer
+    // is plain CommonMark — it doesn't recognize them and collapses the pipe rows into
+    // a single paragraph. A fenced code block renders as monospace preformatted text in
+    // any CommonMark renderer and preserves alignment.
+    async getReadmeMarkdown(): Promise<string> {
+        const groups = this.inventory();
+        const lines: string[] = ['# Kasa Plugin', '', 'Adopted devices, grouped by type.', ''];
+
+        const headers = ['Name', 'Model', 'IP', 'MAC', 'Firmware'];
+        let total = 0;
+        for (const groupName of INVENTORY_GROUPS) {
+            const entries = groups[groupName];
+            if (!entries.length) continue;
+            total += entries.length;
+
+            const rows: string[][] = [
+                headers,
+                ...entries.map(e => [e.name, e.model, e.ip, formatKasaMac(e.mac), e.firmware]),
+            ];
+            // Compute per-column widths so columns line up cleanly inside the code block.
+            const widths = headers.map((_, col) => Math.max(...rows.map(r => r[col].length)));
+
+            lines.push(`## ${groupName} (${entries.length})`, '', '```');
+            for (const row of rows) {
+                // Two-space gutter between columns is enough to keep them visually distinct
+                // without making the block too wide for narrow detail panels.
+                lines.push(row.map((cell, col) => cell.padEnd(widths[col])).join('  '));
+            }
+            lines.push('```', '');
+        }
+
+        if (total === 0) lines.push('_No devices adopted yet._');
+        return lines.join('\n');
     }
 
     async getCreateDeviceSettings(): Promise<Setting[]> {
@@ -640,7 +959,7 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
         room: string | undefined,
         kasaClass: KasaDeviceClass,
     ): Promise<void> {
-        const interfaces = [ScryptedInterface.OnOff, ScryptedInterface.Settings];
+        const interfaces = [ScryptedInterface.OnOff, ScryptedInterface.Settings, ScryptedInterface.Readme];
         let type: ScryptedDeviceType;
         switch (kasaClass) {
             case 'plug':
@@ -694,6 +1013,7 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
                 // OnOff drives the camera's status LED — HomeKit binds its
                 // CameraOperatingModeIndicator characteristic to this.
                 ScryptedInterface.OnOff,
+                ScryptedInterface.Readme,
             ],
             info: {
                 manufacturer: 'TP-Link Kasa',
@@ -771,6 +1091,7 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
                     ScryptedInterface.Intercom,
                     ScryptedInterface.DeviceProvider,
                     ScryptedInterface.OnOff,
+                    ScryptedInterface.Readme,
                 ],
                 info,
                 // Cameras need the cloud account credentials too — auth on the stream/talk
@@ -789,7 +1110,7 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
         }
 
         // Plug, Switch, Bulb — all share the same simpler adoption form.
-        const interfaces = [ScryptedInterface.OnOff, ScryptedInterface.Settings];
+        const interfaces = [ScryptedInterface.OnOff, ScryptedInterface.Settings, ScryptedInterface.Readme];
         let type: ScryptedDeviceType;
         if (cls === 'bulb') {
             type = ScryptedDeviceType.Light;
@@ -885,7 +1206,13 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
     }
 
     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;
@@ -896,32 +1223,33 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
         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;
@@ -936,12 +1264,17 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
 
     private async adoptIotDevice(
         adopt: AdoptDevice,
+        nativeId: string,
         device: KasaDiscoveredDevice,
         cls: KasaDeviceClass,
         name: string,
         room?: string,
     ): Promise<string> {
-        const interfaces: ScryptedInterface[] = [ScryptedInterface.OnOff, ScryptedInterface.Settings];
+        const interfaces: ScryptedInterface[] = [
+            ScryptedInterface.OnOff,
+            ScryptedInterface.Settings,
+            ScryptedInterface.Readme,
+        ];
         let type: ScryptedDeviceType;
         const caps = bulbCapabilities(device);
         // The marker we persist for getDevice routing. 'plug'/'switch' for plain on/off
@@ -964,7 +1297,7 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
 
         const sw_ver = typeof device.sysinfo?.sw_ver === 'string' ? device.sysinfo.sw_ver : undefined;
         await deviceManager.onDeviceDiscovered({
-            nativeId: adopt.nativeId,
+            nativeId,
             name,
             type,
             interfaces,
@@ -982,9 +1315,9 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
         // 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) {
@@ -999,7 +1332,10 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
     // 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/src/shared/readme.ts

@@ -0,0 +1,20 @@
+// Shared formatting helpers for the per-device + plugin-level Readme tabs. Scrypted's
+// markdown renderer is plain CommonMark — it doesn't recognize GFM pipe tables, so we
+// render tabular data inside fenced code blocks with manual column padding.
+
+// Format a hex MAC (e.g. "F0090D49721F") with colon separators (e.g. "F0:09:0D:49:72:1F").
+// Returns the input unchanged if it isn't a 12-character hex string — Kasa devices
+// occasionally surface MACs in already-colon-formatted form, and we don't want to mangle
+// either case.
+export function formatKasaMac(mac: string | undefined): string {
+    if (!mac) return '?';
+    if (!/^[0-9A-Fa-f]{12}$/.test(mac)) return mac;
+    return mac.match(/.{2}/g)!.join(':').toUpperCase();
+}
+
+// Render a list of [label, value] pairs as a left-padded plain-text block. Caller is
+// expected to wrap the output in triple-backtick fences so monospace alignment renders.
+export function renderKv(rows: [string, string][]): string {
+    const labelWidth = Math.max(...rows.map(([k]) => k.length));
+    return rows.map(([k, v]) => `${k.padEnd(labelWidth)}  ${v}`).join('\n');
+}

package/tsconfig.json

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