Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vrachieru/tplink-smartplug-api
TP-Link HS1xx smart plug API wrapper.
https://github.com/vrachieru/tplink-smartplug-api
api-wrapper home-automation kasa reverse-engineering smart-home smart-plug tplink
Last synced: 3 days ago
JSON representation
TP-Link HS1xx smart plug API wrapper.
- Host: GitHub
- URL: https://github.com/vrachieru/tplink-smartplug-api
- Owner: vrachieru
- License: mit
- Created: 2017-04-30T16:14:29.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2020-08-10T12:32:53.000Z (about 4 years ago)
- Last Synced: 2024-08-02T16:01:10.712Z (3 months ago)
- Topics: api-wrapper, home-automation, kasa, reverse-engineering, smart-home, smart-plug, tplink
- Language: Python
- Size: 11.7 KB
- Stars: 48
- Watchers: 4
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-starred - vrachieru/tplink-smartplug-api - TP-Link HS1xx smart plug API wrapper. (reverse-engineering)
README
TP-Link HS1xx smart plug API wrapper
## About TP-Link SmartPlug
* [TP-Link Smart Plugs](https://www.tp-link.com/us/home-networking/smart-home/smart-plugs) are power plugs that can be turned on and off remotely via an app
* Can be operated either via cloud or lan
* Offer energy monitoring and scheduling capabilities
## Features
* Configure device
* Query device information
* Change plug state
## Install
```bash
$ pip3 install git+https://github.com/vrachieru/tplink-smartplug-api.git
```
or
```bash
$ git clone https://github.com/vrachieru/tplink-smartplug-api.git
$ pip3 install ./tplink-smartplug-api
```
## Usage
### Reading device information
```python
from tplink_smartplug import SmartPlug
plug = SmartPlug('192.168.xxx.xxx')
print('Name: %s' % plug.name)
print('Model: %s' % plug.model)
print('Mac: %s' % plug.mac)
print('Time: %s' % plug.time)
print('Is on: %s' % plug.is_on)
print('Nightmode: %s' % (not plug.led))
print('RSSI: %s' % plug.rssi)
```
```bash
$ python3 example.py
Name: Livingroom Floor Lamps
Model: HS100(EU)
Mac: 50:C7:XX:XX:XX:XX
Time: 2018-11-06 14:14:00
Is on: True
Nightmode: False
RSSI: -59
```
### Change state
```python
from tplink_smartplug import SmartPlug
plug = SmartPlug('192.168.xxx.xxx')
if plug.is_on:
plug.turn_off()
print('Plug turned off')
else:
plug.turn_on()
print('Plug turned on')
```
```bash
$ python3 example.py
Plug turned off
$ python3 example.py
Plug turned on
```
## Protocol
A python client for the proprietary TP-Link Smart Home protocol to control TP-Link `HS100` and `HS110` WiFi Smart Plugs.
The SmartHome protocol runs on TCP port `9999` and uses a trivial `XOR` autokey encryption that provides no security.
The initial key (`initialization vector`) has a hardcoded value of `-85 (= 171)`.
The first byte of the plaintext is `XORed` with the key. The key is then set to the plaintext byte.
During the next iteration, the next plaintext byte is `XORed` with the previous plaintext byte.
Decryption works the same, with the keystream made out of cyphertext bytes.
This is known as an autokey cipher and while it has better statistical properties than simple `XOR` encryption with a repeating key, it can be easily broken by known plaintext attacks.
There is no authentication mechanism and commands are accepted independent of device state (configured/unconfigured).
Commands are formatted using JSON, for example:
```json
{
"system": {
"get_sysinfo": {}
}
}
```
Commands can be nested, for example:
```json
{
"system": {
"get_sysinfo": {}
},
"time": {
"get_time": {}
}
}
```
## Reference
[1] https://www.softscheck.com/en/reverse-engineering-tp-link-hs110/
## License
MIT