Kasa Collector is a set of scripts deployed with Docker that collects data from Kasa Smart Plugs. Once deployed, you can visualize that data using Grafana dashboards.
A live set of dashboards using this Collector are available for you to try out.
The project uses a Docker container that may be configured to accept different settings for how often you wish to poll your Kasa devices.
This project currently supports collecting data from the Kasa KP115 smart plug device and Kasa HS300 power strip. These are the two devices that I have - others may be supported based on the "energy" tag found during device disovery.
This project uses the python-kasa module to discover and connect to Kasa devices. More details on supported devices may be found on their project site.
Use the following Docker container:
lux4rd0/kasa-collector:2.0.06
lux4rd0/kasa-collector:latest
Kasa Collector requires some environmental variables for the container to function. It mainly needs details on your InfluxDB instance (Bucket, Org, Token, and URL).
You can start the container with something similar to the example docker-compose.yaml
file:
name: kasa-collector
services:
kasa-collector:
container_name: kasa-collector
environment:
KASA_COLLECTOR_INFLUXDB_BUCKET: kasa
KASA_COLLECTOR_INFLUXDB_ORG: Lux4rd0
KASA_COLLECTOR_INFLUXDB_TOKEN: TOKEN
KASA_COLLECTOR_INFLUXDB_URL: http://influxdb.lux4rd0.com:8086
TZ: America/Chicago
image: lux4rd0/kasa-collector:latest
network_mode: host
restart: always
Or use this example docker run command:
docker run -d \
--name=kasa-collector \
-e KASA_COLLECTOR_INFLUXDB_BUCKET=kasa \
-e KASA_COLLECTOR_INFLUXDB_ORG=Lux4rd0 \
-e KASA_COLLECTOR_INFLUXDB_TOKEN=TOKEN \
-e KASA_COLLECTOR_INFLUXDB_URL=http://influxdb.lux4rd0.com:8086 \
-e TZ=America/Chicago \
--restart always \
--network host \
lux4rd0/kasa-collector:latest
Be sure to change your InfluxDB details and timezone in the environmental variables.
Running docker-compose up -d
or the docker run
command will download and start up the kasa-collector container.
Kasa Collector may be configured with additional environment flags to control its behaviors. They are described below:
KASA_COLLECTOR_DATA_FETCH_INTERVAL
- OPTIONAL
How frequently does the Collector poll your devices to collect measurements in seconds? Defaults to 15 (seconds) if it's not set.
- integer (in seconds)
KASA_COLLECTOR_DEVICE_DISCOVERY_INTERVAL
- OPTIONAL
How frequently the Collector discovers devices in seconds. Defaults to 300 (seconds) if it's not set.
- integer (in seconds)
KASA_COLLECTOR_DISCOVERY_TIMEOUT
- OPTIONAL
Timeout for discovering devices in seconds. Defaults to 5 (seconds) if it's not set.
- integer (in seconds)
KASA_COLLECTOR_DISCOVERY_PACKETS
- OPTIONAL
Number of packets sent for device discovery. Defaults to 3 if it's not set.
- integer
KASA_COLLECTOR_FETCH_MAX_RETRIES
- OPTIONAL
Maximum number of retries for fetching data. Defaults to 3 if it's not set.
- integer
KASA_COLLECTOR_FETCH_RETRY_DELAY
- OPTIONAL
The delay between retries for fetching data in seconds. If it's not set, it defaults to 1 (second).
- integer (in seconds)
KASA_COLLECTOR_SYSINFO_FETCH_INTERVAL
- OPTIONAL
How frequently the Collector gathers system information in seconds. Defaults to 60 (seconds) if it's not set.
- integer (in seconds)
KASA_COLLECTOR_WRITE_TO_FILE
- OPTIONAL
Indicates whether to write data to JSON files. Defaults to False.
- true
- false
KASA_COLLECTOR_KEEP_MISSING_DEVICES
- OPTIONAL
Indicates whether to keep missing devices in the collection. Defaults to True.
- true
- false
KASA_COLLECTOR_INFLUXDB_URL
- REQUIRED
The URL of the InfluxDB instance.
KASA_COLLECTOR_INFLUXDB_TOKEN
- REQUIRED
The token for the InfluxDB instance.
KASA_COLLECTOR_INFLUXDB_ORG
- REQUIRED
The organization for the InfluxDB instance.
KASA_COLLECTOR_INFLUXDB_BUCKET
- REQUIRED
The bucket for the InfluxDB instance.
KASA_COLLECTOR_LOG_LEVEL_KASA_API
- OPTIONAL
Log level for Kasa API. Defaults to "INFO".
- DEBUG
- INFO
- WARNING
- ERROR
- CRITICAL
KASA_COLLECTOR_LOG_LEVEL_INFLUXDB_STORAGE
- OPTIONAL
Log level for InfluxDB Storage. Defaults to "INFO".
- DEBUG
- INFO
- WARNING
- ERROR
- CRITICAL
KASA_COLLECTOR_LOG_LEVEL_KASA_COLLECTOR
- OPTIONAL
Log level for Kasa Collector. Defaults to "INFO".
- DEBUG
- INFO
- WARNING
- ERROR
- CRITICAL
Kasa Collector is the primary data collector and is responsible for gathering details per Kasa device for the following:
- Current (milliamps)
- Voltage (millivolts)
- Power (milliwatts)
- Total Watt Hours
Additional details like Wifi RSSI signal strength, device and plug names, and device details are also collected.
Collecting data is only half the fun. Now it's time to provision some Grafana Dashboards to visualize your essential Kasa data. You'll find a folder of dashboards with collectors and backends split out. You can also use the links/numbers next to each dashboard title to load the dashboards directly from Grafana.
Each dashboard has dropdowns at the top that allow you to filter measurements based on devices and plugs. The dropdowns default to "All," but you can select and save preferences.
Interval: A dropdown that provides different smoothing levels helps manage how the graphs look based on the interval of data collected by the Kasa Collector. Think of this as a level of "smoothing" based on your chosen time frame and the polling time you're collecting data. Be sure to set these to a time frame higher than your poll rate.
Time Range: This defaults to "Today so far" but can be updated to any other Relative or Absolute time range. To smooth out any data, change the "Interval" dropdown for longer time ranges.
Dashboard Refresh: Each dashboard is set to refresh every sixty seconds, but this can be changed or disabled.
Kasa Collector - Energy (By Measurement) - 14762
Kasa Collector - Energy (By Device) - 14772
The Energy dashboard provides panels representing Power, Watt-Hours, Current, and Voltage. Measurements are at the top for total combined information (and voltage average) and rows for both devices and plugs (as part of power strips). You can use the device and plug dropdown menus at the top of the dashboard to filter on each. If you choose a single device that happens to be a power strip, only the plugs for that power strip will be shown in the Plugs dropdown.
This collector uses InfluxQL, and for the dashboards to function, you need to create a data source in Grafana using the credentials you set in InfluxDB V2. More details can be found on the InfluxDB V2 Web site:
https://docs.influxdata.com/influxdb/v2/tools/grafana/?t=InfluxQL#configure-your-influxdb-connection
The biggest change here is:
-
Configure InfluxDB authentication:
Token authentication Under Custom HTTP Headers, select Add Header. Provide your InfluxDB API token:
Header: Enter
Authorization
Value: Use the
Token
schema and provide your InfluxDB API token. For example:Token y0uR5uP3rSecr3tT0k3n
Error Messages
Sometimes, you'll see the following error message from the Kasa Collector:
kasa_request_info: malformed JSON, retrying
This is because some devices that respond to the collector might be malformed data. The collector will try again until a good response is received.
See the open issues for a list of proposed features (and known issues).
Dave Schmid: @lux4rd0 - [email protected]
Project Link: https://github.com/lux4rd0/kasa-collector
- Grafana Labs - https://grafana.com/
- Grafana - https://grafana.com/oss/grafana/
- Grafana Dashboard Community - https://grafana.com/grafana/dashboards/