Kasa Collector is an async Python service that discovers TP-Link Kasa smart plugs and power strips on your network, polls their energy and system data, and writes it to InfluxDB for visualization in Grafana. It runs as a single Docker container, finds devices automatically, and ships with ready-made dashboards.
See it in action: a live set of dashboards powered by this collector is available to explore here.
License: AGPL-3.0-only.
Want to see it working first, with no hardware? Clone the repo and run the demo stack — it bundles a pre-provisioned InfluxDB and Grafana driven by fake Kasa devices, so the dashboards populate immediately:
git clone https://github.com/luxardolabs/kasa-collector.git
cd kasa-collector
make demo-up # then open http://localhost:3000 (admin/admin)Ready to plug into your own InfluxDB and Grafana? Point a single container at your existing stack. Host networking is required for broadcast discovery of devices on your LAN.
services:
kasa-collector:
image: ghcr.io/luxardolabs/kasa-collector:latest
container_name: kasa-collector
network_mode: host
restart: unless-stopped
environment:
# Required — InfluxDB 2.x
KASA_COLLECTOR_INFLUXDB_URL: http://influxdb:8086
KASA_COLLECTOR_INFLUXDB_TOKEN: your-token-here
KASA_COLLECTOR_INFLUXDB_ORG: your-org
KASA_COLLECTOR_INFLUXDB_BUCKET: kasa
# Optional — required only for newer SMART/KLAP devices
# KASA_COLLECTOR_TPLINK_USERNAME: your-email@example.com
# KASA_COLLECTOR_TPLINK_PASSWORD: your-passwordSee Getting Started for the full walkthrough and Configuration for every setting.
Everything is driven by make. Compose never builds — make builds the runtime image locally, so no registry is needed for any local stack.
| Stack | Command | What it does |
|---|---|---|
| demo | make demo-up |
Fake emulated devices + bundled InfluxDB + Grafana — watch it work, no hardware |
| dev | make dev-up |
Your real devices (host networking) + bundled InfluxDB + Grafana |
| collector-only | make up |
Just the collector, pointed at your own external InfluxDB + Grafana |
| test | make test-e2e |
Hardware-free end-to-end test — fakes → collector → ephemeral InfluxDB |
The demo and dev stacks serve Grafana at http://localhost:3000 (admin/admin). See Deployment for production.
- Automatic discovery — finds Kasa devices via network broadcast; manual/cross-subnet hosts supported too
- Per-outlet monitoring — individual emeter data for each outlet on HS300-style power strips
- Energy + system metrics — power, current, voltage, and cumulative consumption every 15s; system info every 60s
- Async InfluxDB writes — one awaited batch per poll cycle over aiohttp
- Authentication — works with newer SMART/KLAP devices requiring TP-Link account credentials
- Grafana dashboards — pre-built and auto-provisioned in the demo and dev stacks
- Docker healthcheck —
python -m app.health.check, no web server required - Graceful shutdown — comprehensive resource and transport cleanup for long-running deployments
- Multi-arch — published for amd64 and arm64
- Getting Started — the three ways to run it, from zero to dashboards
- Configuration — every environment variable and default
- Supported Devices — compatible plugs, strips, and protocols
- Grafana Dashboards — what ships and how to import it
- How It Works — architecture, polling model, and data flow
- Deployment — production Docker Compose, Kubernetes, and remote deploys
- Troubleshooting — discovery, auth, InfluxDB, and timezone fixes
- Testing — unit tests, lint, and the hardware-free e2e harness
Issues and pull requests are welcome. The full local check runs in Docker (no host Python required):
make check # lint + arch + audit + test + gitleaks secret scan
make hooks # install the git hooks that run the secret scan on commit/pushSee Testing for the individual targets.
Licensed under the AGPL-3.0-only license. See LICENSE.
Questions or bugs? Please open an issue.
This project is not affiliated with TP-Link or Kasa. It is an independent tool for monitoring the energy consumption of Kasa smart devices.