homebridge-kasa-pro

A high-performance Homebridge plugin for TP-Link Kasa Wi-Fi devices — covering both the legacy XOR/9999 protocol and the newer KLAP/SMART protocol that newer firmware (KS240, HS200 v5+, HS220 v5+, KS200M, etc.) requires. Built for large households where the stock plugin gets sluggish or misses devices.

Highlights

• Both protocols, one plugin. Legacy Kasa (UDP/9999, XOR-encrypted) and modern SMART/KLAP (HTTP/KLAP v2, RSA + AES-CBC) discovered and polled side by side.
• Adaptive polling. Recently-used devices poll at 5 s, idle at 20 s, devices that time out back off exponentially instead of hammering the LAN.
• Per-IP serial command queue. Kasa firmware gets confused when concurrent connections overlap — every device gets a single-flight client with a configurable minimum gap between writes.
• Debounced, coalesced writes. A flurry of HomeKit Hue/Sat/Brightness updates collapses into one packet, so you don't saturate the bulb mid-slider-drag.
• Pending-state guard. After a write, HomeKit is shown the target value for a short window — no more sliders snapping back while the bulb catches up, no more on→off→on flickers when a stale poll lands during the write.
• Multi-outlet plug support. EP40, KP200, HS300, and similar power-strip-style devices expose one HomeKit Switch per outlet.
• Multi-VLAN discovery. discovery.broadcastAddress accepts an array — useful when Kasa devices live on a different subnet from Homebridge and your router forwards directed broadcasts.
• KL400 / L5 strip color-temp tuning. Inverted range and per-model warm bias so the strip's idea of "warm white" matches HomeKit's.
• Auto-recovering discovery sockets (UDP/9999 and UDP/20002).
• Built-in status server at http://<host>:51888/ for live device state and metrics.

Why this and not homebridge-tplink-smarthome?

homebridge-tplink-smarthome is excellent for the legacy Kasa protocol, but doesn't speak KLAP — so newer hardware (KS240 fan/dimmer combos, HS200 hardware revision 5+, HS220 v5+, KS200M, KS205, KP125M, etc.) is invisible to it. If your home is a mix of old and new Kasa hardware, homebridge-kasa-pro covers both in one plugin. If your home is purely legacy Kasa devices, either plugin will work.

Other things this plugin adds beyond the older one:

• KLAP v2 handshake (the only flavor newer SMART firmware accepts).
• Adaptive per-device timeout/backoff that learns from observed latency.
• Multi-VLAN discovery (broadcast to several subnets).
• Built-in HTTP status page for diagnostics.
• Multi-outlet legacy plug support (EP40, KP200, HS300).

Requirements

• Node.js 20, 22, or 24 (LTS)
• Homebridge 1.7+ (or 2.x)
• TP-Link Kasa devices reachable on the same broadcast domain as Homebridge (or a subnet your router forwards directed broadcasts to)
• For SMART/KLAP devices only: a TP-Link cloud account that owns those devices (the same email/password you use to log in to the Kasa app)

Installation

npm install -g homebridge-kasa-pro

Then in the Homebridge UI go to Plugins → KasaPro → Settings, or add to config.json directly:

{
  "platforms": [
    {
      "platform": "KasaPro",
      "name": "KasaPro"
    }
  ]
}

That's it for legacy devices. They'll be auto-discovered via UDP broadcast within seconds.

For SMART/KLAP devices (KS240, HS200 v5+, HS220 v5+, KS200M, etc.) add credentials:

{
  "platforms": [
    {
      "platform": "KasaPro",
      "name": "KasaPro",
      "credentials": {
        "username": "[email protected]",
        "password": "your-kasa-password"
      }
    }
  ]
}

The password is stored in plaintext in config.json — consider a dedicated TP-Link account for Homebridge if that bothers you.

Configuration

All keys are optional. The Homebridge UI exposes only the user-meaningful ones (the full schema lives in config.schema.json).

| Key | Default | Purpose | |---|---|---| | credentials.username / password | — | TP-Link cloud account, required for SMART/KLAP devices. | | discovery.broadcastAddress | 255.255.255.255 | String or array. Use directed broadcasts (e.g. 192.168.9.255) when devices live on a different subnet. | | smartDiscovery.enabled | true | Toggle UDP/20002 SMART discovery. | | legacyDevices | [] | Static IPs for legacy devices broadcast can't reach. | | smartDevices | [] | Static IPs for SMART devices auto-discovery can't reach (rare). | | deviceOverrides | [] | Per-IP timeout / interval overrides. | | invertColorTempForStrips | true | KL400 strips report color_temp inverted vs. HomeKit. | | stripWarmBias | [] | Per-model kelvin offset for strip white tuning. | | statusServer.port | 51888 | Port for the local status page. | | debugIp | — | Verbose logs for one specific device. |

Per-device overrides

For a slow or finicky device, override just its settings:

{
  "deviceOverrides": [
    {
      "ip": "192.168.1.42",
      "timeoutMs": 4000,
      "minIntervalMs": 300,
      "idleIntervalSeconds": 60
    }
  ]
}

Supported devices

Routed by device profile, so other models in the same families generally work too.

Legacy (XOR/9999)

• Bulbs: KL110, KL120, KL125, KL130, KL135, LB100, LB120, LB130
• Light strips: KL400L5 (all revisions), KL420L5, KL430
• Single-outlet plugs: HS100, HS103, HS105, HS110, KP100, KP105, KP115, KP125, KP200 (single), KP401
• Multi-outlet plugs: KP200 (2-outlet), EP40 (2-outlet outdoor), HS300 (6-outlet) — each outlet appears as its own HomeKit Switch
• Switches / dimmers (legacy hardware revisions): HS200, HS210, HS220, KS220, KS230, ES20M

SMART / KLAP (UDP/20002 + KLAP v2)

• Multi-function switches: KS240 (fan + light)
• Switches: HS200 v5+, KS200M, KS205, KP303 (SMART firmware)
• Dimmers: HS220 v5+, KS230 (SMART firmware), KP405
• Plugs: KP125M

If your device speaks KLAP and isn't in this list, it'll likely be auto-discovered but may need a model-specific handler. Open an issue with the model and the line from the log saying SMART device ... model ... has no accessory handler yet.

Status endpoint

While Homebridge is running, http://<host>:51888/ returns a live HTML table of device state, per-device polling intervals, and command/error metrics. Handy for diagnosing a flaky device without grepping logs.

Troubleshooting

A device shows up in the log but not in HomeKit. Check the status page — does it have a recent "Last Poll" timestamp? If yes, the device is reachable but the model dispatcher doesn't have a handler yet (open an issue). If "Last Poll" is empty or hours old, the plugin can't reach it on the network.

"credentials do not match" for KLAP devices. The TP-Link cloud account in credentials doesn't own that device. In the Kasa app on your phone, confirm the device is in your device list under that account. Some devices were paired with a different account (spouse, prior owner) and need to be re-paired or deleted from one account first.

Cross-subnet devices time out. UDP broadcasts (255.255.255.255) are link-local and won't cross subnets. Either move Kasa devices onto the same VLAN as Homebridge, or set discovery.broadcastAddress: ["255.255.255.255", "192.168.x.255", "192.168.y.255"] and configure your router/L3 switch to forward directed broadcasts. (Most home routers don't, by default.)

HomeKit briefly flickers a switch off→on→off after a tap. You're probably on a version older than 0.2.0. Update.

Security note

The legacy Kasa protocol uses a trivial XOR autokey "cipher" (seed byte 0xAB) on the wire — no confidentiality. KLAP v2 (newer SMART devices) uses real AES-128-CBC with a session key derived from your TP-Link cloud credentials, so it actually is encrypted in transit. Either way, keep IoT devices on a trusted VLAN.

Development

npm test          # smoke tests for command payloads, ciphers, registry, KLAP round-trip
npm run kasa:test # ad-hoc device probe (see scripts/)

CI runs the smoke tests on Node 20, 22, and 24 for every push and pull request. No external runtime dependencies.

Contributing

Issues and PRs welcome at https://github.com/mcneyens/homebridge-kasa-pro.

License

MIT — see LICENSE.