scrypted-kasa 1.0.0 → 1.1.0

package/.github/workflows/ci.yml

@@ -15,9 +15,9 @@ 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.0",
+   "version": "1.1.0",
    "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,7 +69,7 @@
    "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"

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) {

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();
@@ -278,6 +330,19 @@ export async function spawnKasaStream(opts: KasaStreamOptions): Promise<KasaStre
     const videoPipe = cp.stdio[3] as Writable;
     const audioPipe = cp.stdio[4] as Writable;
 
+    // Attach 'error' listeners on both pipes IMMEDIATELY. When cleanupAll calls cp.kill,
+    // ffmpeg's stdio FDs close forcibly and any in-flight pump write throws ECONNRESET /
+    // EPIPE on the writable side. Without listeners, Node turns those into
+    // uncaughtException and crashes the whole plugin worker (taking down every camera).
+    // The `_e` arg is intentional — we just want the stream to be informed there's a
+    // listener.
+    videoPipe.on('error', _e => {
+        /* tear down via the kasa pump's own try/finally */
+    });
+    audioPipe.on('error', _e => {
+        /* tear down via the kasa pump's own try/finally */
+    });
+
     let resolveExited!: () => void;
     const exited = new Promise<void>(r => {
         resolveExited = r;

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,5 +1,6 @@
-import { OnOff, ScryptedDeviceBase, Setting, Settings, SettingValue } from '@scrypted/sdk';
+import { 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;
@@ -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',
@@ -55,6 +56,34 @@ export abstract class KasaIotDevice extends ScryptedDeviceBase implements OnOff,
         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.
+    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 [
+            `# ${this.name || 'Kasa Device'}`,
+            '',
+            '## Device',
+            '',
+            '```',
+            renderKv([
+                ['Model', info.model || '?'],
+                ['Firmware', info.firmware || '?'],
+                ['MAC', formatKasaMac(info.mac)],
+                ['IP', ip],
+                ['Port', String(port)],
+            ]),
+            '```',
+            '',
+            '## 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');
+    }
+
     async turnOn(): Promise<void> {
         await this.callIot({ system: { set_relay_state: { state: 1 } } });
         this.on = true;

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) {

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;
@@ -941,7 +1262,11 @@ class KasaPlugin extends ScryptedDeviceBase implements DeviceProvider, DeviceCre
         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

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');
+}