Python Library to control TPLink smart plugs/switches and smart bulbs.
Supported devices
- Plugs
- HS100
- HS105
- HS110
- Wall switches
- HS200
- HS210
- Bulbs
- LB100
- LB110
- LB120
- LB130
The package is shipped with a console tool named pyhs100, please refer to pyhs100 --help for detailed usage.
The device to which the commands are sent is chosen by PYHS100_HOST environment variable or passing --host <address> 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. pyhs100 emeter --help or pyhs100 hsv --help.
If no command is given, the state command will be executed to query the device state.
The devices can be discovered either by using pyhs100 discover or by calling pyhs100 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.
$ pyhs100
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}
All devices support a variety of common commands, including:
statewhich returns state informationonandofffor turning the device on or offemeter(where applicable) to return energy consumption informationsysinfoto return raw system information which is used by e.g.state, useful for debugging and when adding support for new device types
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.
$ pyhs100 emeter
== Emeter ==
Current state: {'total': 133.105, 'power': 108.223577, 'current': 0.54463, 'voltage': 225.296283}
At the moment only switching the state of the LED is implemented. Feel free to submit patches as pull requests for further features!
led command can be used to control whether the LED light on front of the plug is on or off.
$ pyhs100 --plug led
LED state: False
$ pyhs100 --plug led 1
Turning led to True
At the moment setting brightness, color temperature and color (in HSV) is supported.
The commands are straightforward, so feel free to check --help for instructions how to use them.
Feel free to submit patches as pull requests to add more functionality (e.g. scenes)!
The public API is well documented, but here are some examples to get you started.
For all available API functions run help(SmartPlug) or help(SmartBulb).
Discover class' discover() can be used to discover supported devices,
which returns a dictionary keyed with the IP address whose value hold a ready-to-use instance of the detected device type.
Example:
from pyHS100 import Discover
for dev in Discover.discover().values():
print(dev)$ python3 example.py
<SmartPlug at 192.168.XXX.XXX (My Smart Plug), is_on: True - dev specific: {'LED state': True, 'On since': datetime.datetime(2017, 3, 26, 18, 29, 17, 52073)}>
Please note that most property getters do I/O (e.g. fetching the system information) on each call.
If you want to avoid unnecessary communication with the device please use get_sysinfo and handle parsing of information by yourself.
from pyHS100 import SmartPlug, SmartBulb
from pprint import pformat as pf
plug = SmartPlug("192.168.XXX.XXX")
print("Hardware: %s" % pf(plug.hw_info))
print("Full sysinfo: %s" % pf(plug.get_sysinfo())) # this prints lots of information about the deviceDevices can be turned on and off by either calling appropriate methods on the device object,
or by assigning a new state to state property.
print("Current state: %s" % plug.state)
plug.turn_off()
plug.turn_on()plug.state = "ON"
plug.state = "OFF"print("Current time: %s" % plug.time)
print("Timezone: %s" % plug.timezone)print("Alias: %s" % plug.alias)
plug.alias = "My New Smartplug"print("Current consumption: %s" % plug.get_emeter_realtime())
print("Per day: %s" % plug.get_emeter_daily(year=2016, month=12))
print("Per month: %s" % plug.get_emeter_monthly(year=2016))print("Current LED state: %s" % plug.led)
plug.led = False # turn off led
print("New LED state: %s" % plug.led)The bulb API is likewise straightforward, so please refer to its API documentation.
Information about supported features can be queried by using properties prefixed with is_, e.g. is_dimmable.
The brightness property works in percentages.
print(bulb.brightness)
if bulb.is_dimmable:
bulb.brightness = 100print(bulb.color_temp)
if bulb.is_variable_color_temp:
bulb.color_temp = 3000Hue is given in degrees (0-360) and saturation and value in percentage.
print(bulb.hsv)
if bulb.is_color:
bulb.hsv = (180, 100, 100) # set to cyanThe following assumes you have a working installation of Docker.
Set up the environment and run the tests on demand.
docker build . -t pyhs100 && docker run -v $(PWD)/pyHS100/tests:/opt/pyHS100/pyHS100/tests pyhs100 pytest