Skip to main content

TP-Link Kasa integration for Gladys Assistant

TP-Link Kasa integration for Gladys Assistant

Control your TP-Link Kasa smart plugs, switches and bulbs over your local network.

View on GitHubAll external integrations

Control your TP-Link Kasa smart plugs, switches and bulbs from Gladys, over your local network. The integration runs in its own container and talks to your devices using the classic Kasa LAN protocol.

Supported devices​

DeviceFeature
Plugs and switchesOn/Off (switch)
BulbsOn/Off (light)

Other TP-Link types are detected during a scan and reported in the logs, but they are not published because they have no controllable feature yet.

Multi-outlet strips are not supported. Kasa power strips (HS300, HS107, KP303, KP400) are detected and deliberately skipped: their outlets are controlled individually, which this integration cannot do yet. Publishing them would offer a single switch that turns the whole strip off at once.

Local-only, legacy protocol. This integration speaks the classic Kasa LAN protocol. Newer Kasa firmware that only exposes the encrypted KLAP protocol is not supported.

How discovery works​

Kasa devices only answer an active discovery probe, and the integration runs in a sandboxed container that cannot broadcast onto your LAN. So the scan is mediated by Gladys: the integration forges the encrypted Kasa discovery request, the Gladys core (which sits on your home network) broadcasts it, and relays the devices' replies back. You do not enter any IP address — the scan finds your devices, and the IP each one answered from is remembered to control it afterwards.

Give your Kasa devices a DHCP reservation on your router so their IP address stays stable; if it changes, a new scan picks up the new address automatically.

Configuration​

  1. Open the Configuration tab of the integration.

  2. Choose a Refresh interval — how often each device is polled to refresh its state (default: every minute). Save.

    This interval is stored on each device when it is discovered. Changing it later does not update the devices you already created: run a new scan to apply the new value.

  3. Open the Discovery tab and click scan: your Kasa devices appear.

  4. Click create on the ones you want. They land in the Devices tab with an On/Off control.

Run a scan again anytime you add a new device.

Troubleshooting​

  • A device does not appear on scan. Make sure it is powered on and on the same network/subnet as your Gladys host, then scan again. Only classic-protocol Kasa devices answer (see below).
  • A device appears but never changes state. Its firmware may only speak the newer KLAP protocol, which is not supported.
  • "Nothing happens" when I click scan. Gladys allows one scan every 10 seconds: wait a moment before scanning again. The error is shown in the integration banner.
  • A device is flagged "unreachable". It is off, unplugged, or its IP address changed. Check it is powered on, then run a new scan to pick up its new address.
  • "Another device now answers at this address". Your router reassigned that device's IP address to something else. Run a new scan: the integration deliberately refuses to control a device whose identity it could not verify, rather than acting on the wrong one.
  • Need more detail? The integration logs everything it does. Check the integration logs from the Gladys UI (or docker logs on the host) with LOG_LEVEL=debug for the full detail.

Configuration settings​

These are the settings TP-Link Kasa asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Refresh intervalselectNoHow often each device is polled to refresh its state.
  1. In Gladys, open Integrations: TP-Link Kasa appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/cicoub13/gladys-tp-link:1.2.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/cicoub13/gladys-tp-link.

TP-Link Kasa requires Gladys >=4.84.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

TP-Link Kasa is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by cicoub13, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on