# python-kasa [![PyPI version](https://badge.fury.io/py/python-kasa.svg)](https://badge.fury.io/py/python-kasa) [![Build Status](https://dev.azure.com/python-kasa/python-kasa/_apis/build/status/python-kasa.python-kasa?branchName=master)](https://dev.azure.com/python-kasa/python-kasa/_build/latest?definitionId=2&branchName=master) [![Coverage Status](https://coveralls.io/repos/github/python-kasa/python-kasa/badge.svg?branch=master)](https://coveralls.io/github/python-kasa/python-kasa?branch=master) python-kasa is a Python library to control TPLink smart home devices (plugs, wall switches, power strips, and bulbs) using asyncio. This project is a maintainer-made fork of [pyHS100](https://github.com/GadgetReactor/pyHS100) project. **Supported devices** * Plugs * HS100 * HS103 * HS105 * HS107 * HS110 * Power Strips * HS300 * KP303 * Wall switches * HS200 * HS210 * HS220 * Bulbs * LB100 * LB110 * LB120 * LB130 * LB230 * KL60 * KL110 * KL120 * KL130 **Contributions (be it adding missing features, fixing bugs or improving documentation) are more than welcome, feel free to submit pull requests! See below for instructions for setting up a development environment.** # Usage The package is shipped with a console tool named kasa, please refer to ```kasa --help``` for detailed usage. The device to which the commands are sent is chosen by `KASA_HOST` environment variable or passing `--host
` as an option. To see what is being sent to and received from the device, specify option `--debug`. To avoid discovering the devices when executing commands its type can be passed by specifying either `--plug` or `--bulb`, if no type is given its type will be discovered automatically with a small delay. Some commands (such as reading energy meter values and setting color of bulbs) additional parameters are required, which you can find by adding `--help` after the command, e.g. `kasa emeter --help` or `kasa hsv --help`. If no command is given, the `state` command will be executed to query the device state. ## Initial Setup You can provision your device without any extra apps by using the `kasa wifi` command: 1. If the device is unprovisioned, connect to its open network 2. Use `kasa discover` (or check the routes) to locate the IP address of the device (likely 192.168.0.1) 3. Scan for available networks using `kasa wifi scan` 4. Join/change the network using `kasa wifi join` command, see `--help` for details. ## Discovering devices The devices can be discovered either by using `kasa discover` or by calling `kasa` without any parameters. In both cases supported devices are discovered from the same broadcast domain, and their current state will be queried and printed out. ``` $ kasa No --bulb nor --plug given, discovering.. Discovering devices for 3 seconds == My Smart Plug - HS110(EU) == Device state: ON IP address: 192.168.x.x LED state: False On since: 2017-03-26 18:29:17.242219 == Generic information == Time: 1970-06-22 02:39:41 Hardware: 1.0 Software: 1.0.8 Build 151101 Rel.24452 MAC (rssi): 50:C7:BF:XX:XX:XX (-77) Location: {'latitude': XXXX, 'longitude': XXXX} == Emeter == Current state: {'total': 133.082, 'power': 100.418681, 'current': 0.510967, 'voltage': 225.600477} ``` ## Basic controls All devices support a variety of common commands, including: * `state` which returns state information * `on` and `off` for turning the device on or off * `emeter` (where applicable) to return energy consumption information * `sysinfo` to return raw system information ## Energy meter Passing no options to `emeter` command will return the current consumption. Possible options include `--year` and `--month` for retrieving historical state, and reseting the counters is done with `--erase`. ``` $ kasa emeter == Emeter == Current state: {'total': 133.105, 'power': 108.223577, 'current': 0.54463, 'voltage': 225.296283} ``` ## Bulb-specific commands At the moment setting brightness, color temperature and color (in HSV) are supported depending on the device. The commands are straightforward, so feel free to check `--help` for instructions how to use them. # Library usage The property accesses use the data obtained before by awaiting `update()`. The values are cached until the next update call. Each method changing the state of the device will automatically update the cached state. Errors are raised as `SmartDeviceException` instances for the user to handle. ## Discovering devices `Discover.discover()` can be used to discover supported devices in the local network. The return value is a dictionary keyed with the IP address and the value holds a ready-to-use instance of the detected device type. Example: ```python import asyncio from kasa import Discover devices = asyncio.run(Discover.discover()) for addr, dev in devices.items(): asyncio.run(dev.update()) print(f"{addr} >> {dev}") ``` ``` $ python example.py