scrypted-kasa 1.0.0

package/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    groups:
+      ci:
+        patterns:
+          - "*"

package/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+# Cancel in-progress runs for the same PR/branch when a new commit is pushed.
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Prettier check
+        run: npm run fmt:check
+
+      - name: ESLint
+        run: npm run lint
+
+      - name: Build (scrypted-webpack)
+        run: npm run build

package/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish
+
+on:
+  push:
+    # Trigger on semver tags like v1.0.7. Push the tag with `git tag v1.0.7 && git push --tags`
+    # after bumping the version in package.json.
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      # id-token is required for npm publish provenance — provenance signs the package
+      # 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/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+          # Configures npm with the registry URL so NODE_AUTH_TOKEN is honored at publish.
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Verify package.json version matches git tag
+        run: |
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          TAG_VERSION="${GITHUB_REF#refs/tags/v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::package.json version ($PKG_VERSION) does not match git tag ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "Publishing scrypted-kasa@$PKG_VERSION"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Prettier check
+        run: npm run fmt:check
+
+      - name: ESLint
+        run: npm run lint
+
+      - name: Build (scrypted-webpack)
+        run: npm run build
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.nvmrc

@@ -0,0 +1 @@
+v24

package/.prettierignore

@@ -0,0 +1,6 @@
+node_modules/
+out/
+build/
+dist/
+*.log
+package-lock.json

package/.prettierrc.json

@@ -0,0 +1,11 @@
+{
+    "tabWidth": 4,
+    "useTabs": false,
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 120,
+    "arrowParens": "avoid",
+    "bracketSpacing": true,
+    "endOfLine": "lf"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergey Vilgelm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# scrypted-kasa
+
+[![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,
+switches/dimmers, and bulbs. Discovery is unified — one UDP/9999 sweep finds everything
+and the plugin routes each device to the right Scrypted interfaces.
+
+## Installation
+
+In Scrypted:
+
+1. Open the **Plugins** page.
+2. Choose **Install** and enter `scrypted-kasa`.
+3. The plugin appears as **Kasa Plugin** in the device list — see [Setup](#setup) below.
+
+## Cameras
+
+- Reads the camera's proprietary multipart stream (HTTPS port 19443, `/https/stream/mixed`)
+  and re-streams H.264 video + G.711 µ-law audio over local RTSP for Scrypted, HomeKit, the
+  NVR, etc.
+- Streams talk audio back to the camera's speaker via the camera's separate uplink endpoint
+  (HTTPS port 18443, `/https/speaker/audio/g711block`) — usable from HomeKit and any other
+  Scrypted client that supports two-way audio.
+- Exposes the camera's spotlight (when present, e.g. KC420WS) as an `OnOff` child light
+  device in the same room as the camera. Driven by the LINKIE2 control protocol on port
+  10443.
+- Exposes the camera's siren (when present) as an `OnOff` child switch device, also in
+  the camera's room. Triggering it turns the siren on; the camera auto-stops after the
+  duration configured in the Kasa app (default 30 s).
+- Exposes the camera's **status LED** as the camera's own `OnOff` interface, so HomeKit's
+  per-camera "Link Status Indicator" toggle drives the LED.
+
+## Plugs / Switches / Dimmers / Bulbs (legacy IOT protocol)
+
+Each device class is its own implementation, descended from a shared `KasaIotDevice`
+base that holds the relay protocol:
+
+- **`KasaPlug`** — plain plugs/outlets (HS100/HS103/HS105/HS107/HS110/KP100/...). `OnOff`,
+  `ScryptedDeviceType.Outlet`.
+- **`KasaSwitch`** — plain wall switches (HS200/HS210/KS200/...). `OnOff`,
+  `ScryptedDeviceType.Switch`.
+- **`KasaDimmer`** — dimmer plugs and switches (HS220 plug, KS230 3-way switch). `OnOff` +
+  `Brightness`, `ScryptedDeviceType.Light` (dimmable devices are exposed as lights since
+  they're almost always wired to a light fixture, matching the Kasa app's UX).
+- **`KasaBulb`** — smart bulbs (LB1xx, KL1xx). `OnOff` + `Brightness`, plus
+  `ColorSettingHsv` for color bulbs and `ColorSettingTemperature` for variable-temperature
+  bulbs.
+
+Multi-outlet plug strips (HS300, KP303) aren't modeled yet — discovery skips them.
+
+Stream protocol described in [go2rtc's `pkg/kasa`](https://github.com/AlexxIT/go2rtc/tree/master/pkg/kasa);
+camera control protocols (LINKIE2, talk endpoint, status LED) modeled after the official
+Kasa iOS app's network traffic. The plug/bulb/switch protocol is the well-documented
+legacy "smarthome" TCP/9999 wire format.
+
+Tested camera models: KD110, KC200, KC401, KC420WS, EC71.
+
+## Setup
+
+### Auto-discovery (recommended)
+
+1. Install the plugin.
+2. Open the plugin's page and click **Discover Devices**. Discovery runs only when you
+   click the button — there are no background scans.
+3. Every LAN-visible Kasa device appears in the list — cameras, plugs, switches, dimmers,
+   and bulbs are all discovered together.
+4. For each device you want to adopt, fill in the adoption form and click adopt:
+   - **Name** — pre-filled with the device's alias or model; edit to taste.
+   - **Room** — optional, picked from a dropdown of rooms already in use by other
+     Scrypted devices, or type a new one.
+   - **Username** / **Password** *(cameras only)* — your Kasa account email and password.
+     After the first camera is configured these are pre-populated from any other Kasa
+     camera in Scrypted.
+
+Adopted devices get their IP, port, name, model, MAC, serial number, and firmware version
+populated automatically. The manufacturer is reported as `TP-Link Kasa`.
+
+Discovery sends a single UDP/9999 burst on each connected /24:
+
+- A **broadcast** of the IOT.SMARTHOME `get_sysinfo` query.
+- A **paced unicast** of the same query at every IP on the subnet (~3 ms between sends).
+  Newer firmwares (e.g. KC420WS cameras) drop broadcast probes but still answer when the
+  packet is addressed directly. Pacing keeps the kernel/network from coalescing or
+  dropping the burst.
+
+If a device is on a different VLAN/broadcast domain or a non-/24 subnet, use the manual
+setup below.
+
+### Manual setup
+
+1. Install the plugin.
+2. Use **Add Device** to create a new device. The Add form takes:
+   - **Type** — Camera, Plug, Switch, Dimmer, or Bulb.
+   - **Name** — required.
+   - **Room** — optional, with the same dropdown of existing rooms as the discovery flow.
+3. After creation, open the device's settings and fill in:
+   - **IP Address** of the device on your LAN
+   - **Port** (default 19443 for cameras, 9999 for everything else)
+   - For cameras: **Username** + **Password** (your Kasa account email + password)
+
+## How it works
+
+### Receive (camera → Scrypted)
+
+- The plugin opens a single HTTPS connection to the camera on port 19443 and parses the
+  `multipart/x-mixed-replace` body, splitting it into video parts (`video/x-h264`,
+  annex-b) and audio parts (`audio/g711u`).
+- It scans the first H.264 frames for SPS (NAL 7) and PPS (NAL 8) and inlines them into
+  the locally served SDP as `sprop-parameter-sets` + `profile-level-id`. This lets short
+  -timeout consumers (HomeKit, browser players) pick up the codec immediately.
+- It then runs ffmpeg in codec-copy mode, re-packetizing the raw H.264 and G.711 µ-law
+  streams as RTP into a local RTSP server that Scrypted reads from.
+
+### Talk (Scrypted → camera speaker)
+
+- When a client engages two-way audio, the plugin opens a long-lived chunked POST to
+  `https://<ip>:18443/https/speaker/audio/g711block` and ffmpeg-transcodes the client's
+  audio to 8 kHz mono G.711 µ-law.
+- Each 20 ms (160 byte) audio block is wrapped in a `multipart/x-mixed-replace` part with
+  `Content-Type: audio/g711u` and streamed to the camera. Empty `audio/heartbeat` parts
+  are sent every 3 s during silence to keep the connection alive — same pattern the Kasa
+  app uses.
+
+### Spotlight / control plane
+
+- The Kasa app talks to the camera's "LINKIE2" RPC on port 10443 for non-streaming
+  features. Wire format: HTTPS POST `/data/LINKIE2.json`, body `application/x-www-form-
+  urlencoded` with a single `content=<base64(xor_ab(json))>` field. The XOR-AB autokey
+  cipher is the same one used by Kasa's UDP/9999 discovery protocol.
+- On adoption (and whenever credentials change) the plugin probes three LINKIE2 endpoints
+  serially:
+  - `smartlife.cam.ipcamera.dayNight.get_force_lamp_state` — if it returns `on`/`off`, a
+    child `OnOff` light device named "<camera> Spotlight" is registered in the camera's
+    room.
+  - `smartlife.cam.ipcamera.siren.get_state` — same pattern; produces a "<camera> Siren"
+    switch child device.
+  - `smartlife.cam.ipcamera.led.get_status` — drives the camera's own `OnOff` so HomeKit
+    can bind its `CameraOperatingModeIndicator` (a.k.a. "Status Light") characteristic to
+    it. Enable **Link Status Indicator** in the HomeKit plugin's per-camera settings to
+    activate the binding.
+- Toggling any of the three calls the matching `set_*` method with `{"value": "on"|"off"}`.
+
+## Notes / limitations
+
+- **Authentication** uses the cloud account password. All three endpoints take Basic auth
+  with the plain Kasa email as the username; the password format differs by endpoint —
+  receive uses base64(plaintext), talk and LINKIE2 use md5_hex(plaintext). The plugin
+  uses each in the right place.
+- LINKIE2 requests must include a `User-Agent: Kasa/...` header and the `Authorization`
+  header on the very first request — the camera silently drops requests that don't look
+  enough like the official app.
+- The camera presents a self-signed TLS certificate; certificate verification is disabled.
+- Auto-discovery sweeps the local /24 only. Larger subnets (e.g. /23) are skipped to
+  avoid flooding.
+
+## Development
+
+```bash
+git clone https://github.com/sv-tools/scrypted-kasa-plugin.git
+cd scrypted-kasa-plugin
+npm install
+```
+
+Common scripts:
+
+| Command | Purpose |
+|---|---|
+| `npm run build` | Webpack bundle into `out/main.nodejs.js` (+ `plugin.zip`) |
+| `npm run fmt` | Format `src/**/*.ts` with prettier |
+| `npm run fmt:check` | Verify formatting — what CI runs |
+| `npm run lint` | ESLint |
+| `npm run lint:fix` | ESLint with auto-fix |
+| `npm run scrypted-deploy <host>` | Build and deploy to a Scrypted server |
+
+CI on every PR runs `fmt:check`, `lint`, and `build`. Releases publish to npm
+automatically when a `v*` tag is pushed (e.g. `git tag v1.2.3 && git push --tags`).
+The publish workflow signs the package with [npm provenance](https://docs.npmjs.com/generating-provenance-statements)
+via GitHub OIDC.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/eslint.config.mjs

@@ -0,0 +1,33 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+// We deliberately don't use `eslint-config-prettier`: typescript-eslint's `recommended`
+// preset focuses on code-quality rules, not style. Prettier already owns formatting via
+// `npm run fmt` / `fmt:check`, and there's nothing in the rule set below that fights it.
+// Skipping the dep also sidesteps the known eslint-config-prettier supply-chain compromise.
+export default tseslint.config(
+    {
+        ignores: ['node_modules/', 'out/', 'build/', 'dist/'],
+    },
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        rules: {
+            // Allow `any` — used intentionally for kasa sysinfo (untyped JSON shape varies
+            // per device family) and for narrow casts where TypeScript can't see through
+            // the runtime tag (e.g. `kasaClass`).
+            '@typescript-eslint/no-explicit-any': 'off',
+
+            // Treat `_`-prefixed args/vars as intentionally unused (matches the convention
+            // we already use for ignored handler params like `_options`, `_id`, `_nativeId`).
+            '@typescript-eslint/no-unused-vars': [
+                'warn',
+                { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_' },
+            ],
+
+            // Empty catch blocks are a deliberate teardown idiom in this codebase: e.g.
+            // `try { socket.close(); } catch {}` — best-effort, ignore failure. Don't nag.
+            'no-empty': ['warn', { allowEmptyCatch: true }],
+        },
+    },
+);

package/package.json

@@ -0,0 +1,75 @@
+{
+   "name": "scrypted-kasa",
+   "version": "1.0.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",
+   "repository": {
+      "type": "git",
+      "url": "git+https://github.com/sv-tools/scrypted-kasa-plugin.git"
+   },
+   "bugs": {
+      "url": "https://github.com/sv-tools/scrypted-kasa-plugin/issues"
+   },
+   "homepage": "https://github.com/sv-tools/scrypted-kasa-plugin#readme",
+   "scripts": {
+      "scrypted-setup-project": "scrypted-setup-project",
+      "prescrypted-setup-project": "scrypted-package-json",
+      "build": "scrypted-webpack",
+      "prepublishOnly": "NODE_ENV=production scrypted-webpack",
+      "prescrypted-vscode-launch": "scrypted-webpack",
+      "scrypted-vscode-launch": "scrypted-deploy-debug",
+      "scrypted-deploy-debug": "scrypted-deploy-debug",
+      "scrypted-debug": "scrypted-debug",
+      "scrypted-deploy": "scrypted-deploy",
+      "scrypted-readme": "scrypted-readme",
+      "scrypted-package-json": "scrypted-package-json",
+      "fmt": "prettier --write \"src/**/*.ts\"",
+      "fmt:check": "prettier --check \"src/**/*.ts\"",
+      "lint": "eslint src",
+      "lint:fix": "eslint src --fix"
+   },
+   "keywords": [
+      "scrypted",
+      "scrypted-plugin",
+      "plugin",
+      "kasa",
+      "tp-link",
+      "tplink",
+      "smarthome",
+      "smart-home",
+      "homekit",
+      "camera",
+      "intercom",
+      "two-way-audio",
+      "switch",
+      "outlet",
+      "plug",
+      "dimmer",
+      "bulb",
+      "light",
+      "lightbulb"
+   ],
+   "scrypted": {
+      "name": "Kasa Plugin",
+      "type": "DeviceProvider",
+      "interfaces": [
+         "ScryptedSystemDevice",
+         "ScryptedDeviceCreator",
+         "DeviceProvider",
+         "DeviceCreator",
+         "DeviceDiscovery"
+      ],
+      "pluginDependencies": [
+         "@scrypted/prebuffer-mixin"
+      ]
+   },
+   "devDependencies": {
+      "@eslint/js": "^10.0.1",
+      "@scrypted/sdk": "^0.5.59",
+      "@types/node": "^24.12.2",
+      "eslint": "^10.2.1",
+      "prettier": "^3.8.3",
+      "typescript-eslint": "^8.59.1"
+   }
+}