2019-12-18 08:11:18 +00:00
# python-kasa
2017-03-25 22:04:32 +00:00
2019-12-18 08:11:18 +00:00
[](https://badge.fury.io/py/python-kasa)
2020-03-18 11:17:12 +00:00
[](https://dev.azure.com/python-kasa/python-kasa/_build/latest?definitionId=2& branchName=master)
2019-12-18 08:11:18 +00:00
[](https://coveralls.io/github/python-kasa/python-kasa?branch=master)
2017-10-07 15:51:10 +00:00
2020-05-12 10:11:47 +00:00
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.
2020-07-12 20:46:21 +00:00
## Getting started
2017-10-07 15:51:10 +00:00
2020-07-12 20:46:21 +00:00
You can install the most recent release using pip. Until
```
pip install python-kasa --pre
```
2020-05-12 10:11:47 +00:00
2020-07-12 20:46:21 +00:00
Alternatively, you can clone this repository and use poetry to install the development version:
```
git clone https://github.com/python-kasa/python-kasa.git
cd python-kasa/
poetry install
```
Read all data from the device, disable double-encoding, implement more APIs, refactor querying, update README (#11)
* Read from socket until no data available, disable double string encoding
HS110 sends sometimes datagrams in chunks especially for get_daystat,
this patch makes it to read until there is no more data to be read.
As json.dumps() does JSON encoding already, there's no need to str()
the year or month either.
* Add cli.py, a simple script to query devices for debugging purposes.
* allow easier importing with from pyHS100 import SmartPlug
* move cli.py to examples, add short usage into README.md
* Implement more available APIs, refactor querying code.
This commit adds access to new properties, both read & write, while keeping the old one (mostly) intact.
Querying is refactored to be done inside _query_helper() method,
which unwraps results automatically and rises SmartPlugException() in case of errors.
Errors are to be handled by clients.
New features:
* Setting device alias (plug.alias = "name")
* led read & write
* icon read (doesn't seem to return anything without cloud support at least), write API is not known, throws an exception currently
* time read (returns datetime), time write implemented, but not working even when no error is returned from the device
* timezone read
* mac read & write, writing is untested for now.
Properties for easier access:
* hw_info: return hw-specific elements from sysinfo
* on_since: pretty-printed from sysinfo
* location: latitude and longitued from sysinfo
* rssi: rssi from sysinfo
* Update README.md with examples of available features.
* Handle comments from mweinelt
* Refactor state handling, use booleans instead of strings
* Fix issues raised during the review.
Following issues are addressed by this commit:
* All API is more or less commented (including return types, exceptions, ..)
* Converted state to use
* Added properties is_on, is_off for those who don't want to check against strings.
* Handled most issues reported by pylint.
* Adjusted _query_helper() to strip off err_code from the result object.
* Fixed broken format() syntax for string formattings.
* Fix ci woes plus one typo.
* Do initialization after changing device properties, fix nits.
2016-12-12 09:13:45 +00:00
2017-10-07 15:51:10 +00:00
## Discovering devices
2017-03-25 22:04:32 +00:00
2020-07-12 20:46:21 +00:00
After installation, the devices can be discovered either by using `kasa discover` or by calling `kasa` without any parameters.
2017-10-07 15:51:10 +00:00
```
2019-12-18 08:11:18 +00:00
$ kasa
2017-10-07 15:51:10 +00:00
No --bulb nor --plug given, discovering..
Discovering devices for 3 seconds
2017-03-25 22:04:32 +00:00
== My Smart Plug - HS110(EU) ==
2017-10-07 15:51:10 +00:00
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
2017-03-25 22:04:32 +00:00
Hardware: 1.0
Software: 1.0.8 Build 151101 Rel.24452
2017-10-07 15:51:10 +00:00
MAC (rssi): 50:C7:BF:XX:XX:XX (-77)
Location: {'latitude': XXXX, 'longitude': XXXX}
2017-03-25 22:04:32 +00:00
== Emeter ==
2017-10-07 15:51:10 +00:00
Current state: {'total': 133.082, 'power': 100.418681, 'current': 0.510967, 'voltage': 225.600477}
2017-03-25 22:04:32 +00:00
```
2020-07-12 20:46:21 +00:00
Use `kasa --help` to get list of all available commands.
2017-10-07 15:51:10 +00:00
## 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
2020-05-12 10:11:47 +00:00
* `sysinfo` to return raw system information
2017-10-07 15:51:10 +00:00
## 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` .
```
2019-12-18 08:11:18 +00:00
$ kasa emeter
2017-10-07 15:51:10 +00:00
== Emeter ==
Current state: {'total': 133.105, 'power': 108.223577, 'current': 0.54463, 'voltage': 225.296283}
```
## Bulb-specific commands
2020-05-12 10:11:47 +00:00
At the moment setting brightness, color temperature and color (in HSV) are supported depending on the device.
2017-10-07 15:51:10 +00:00
The commands are straightforward, so feel free to check `--help` for instructions how to use them.
2017-03-25 22:04:32 +00:00
# Library usage
2020-06-30 00:29:52 +00:00
You can find several code examples in [the API documentation ](broken link ).
2017-10-13 21:27:05 +00:00
2020-05-12 10:11:47 +00:00
## Contributing
2017-10-13 21:27:05 +00:00
2020-05-12 10:11:47 +00:00
Contributions are very welcome! To simplify the process, we are leveraging automated checks and tests for contributions.
2017-10-13 21:27:05 +00:00
2020-05-12 10:11:47 +00:00
### Setting up development environment
2020-07-12 21:07:24 +00:00
To get started, simply clone this repository and initialize the development environment.
We are using [poetry ](https://python-poetry.org ) for dependency management, so after cloning the repository simply execute
`poetry install` which will install all necessary packages and create a virtual environment for you.
2020-05-12 10:11:47 +00:00
### Code-style checks
2020-07-12 21:07:24 +00:00
We use several tools to automatically check all contributions. The simplest way to verify that everything is formatted properly
before creating a pull request, consider activating the pre-commit hooks by executing `pre-commit install` .
This will make sure that the checks are passing when you do a commit.
You can also execute the checks by running either `tox -e lint` to only do the linting checks, or `tox` to also execute the tests.
### Analyzing network captures
The simplest way to add support for a new device or to improve existing ones is to capture traffic between the mobile app and the device.
After capturing the traffic, you can either use the [softScheck's wireshark dissector ](https://github.com/softScheck/tplink-smartplug#wireshark-dissector )
or the `parse_pcap.py` script contained inside the `devtools` directory.
2020-05-12 10:11:47 +00:00
2020-07-12 20:46:21 +00:00
## 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!**
2020-07-12 21:07:24 +00:00
### Resources
* [softScheck's github contains lot of information and wireshark dissector ](https://github.com/softScheck/tplink-smartplug#wireshark-dissector )
* [https://github.com/plasticrake/tplink-smarthome-simulator ](tplink-smarthome-simulator )
* [Unofficial API documentation ](https://github.com/plasticrake/tplink-smarthome-api/blob/master/API.md )
