python-kasa

python-kasa is a Python library to control TPLink's smart home devices (plugs, wall switches, power strips, and bulbs).

This is a voluntary, community-driven effort and is not affiliated, sponsored, or endorsed by TPLink.

Contributions in any form (adding missing features, reporting issues, fixing or triaging existing ones, improving the documentation, or device donations) are more than welcome!

---

Getting started

You can install the most recent release using pip:

pip install python-kasa

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

If you have not yet provisioned your device, you can do so using the cli tool.

Discovering devices

Running kasa discover will send discovery packets to the default broadcast address (255.255.255.255) to discover supported devices. If your device requires authentication to control it, you need to pass the credentials using --username and --password options or define KASA_USERNAME and KASA_PASSWORD environment variables.

Note

If your system has multiple network interfaces, you can specify the broadcast address using the --target option.

The discover command will automatically execute the state command on all the discovered devices:

$ kasa discover
Discovering devices on 255.255.255.255 for 3 seconds

== Bulb McBulby - L530 ==
        Host: 192.0.2.123
        Port: 80
        Device state: False
        == Generic information ==
        Time:         2024-06-21 15:09:35+02:00 (tz: {'timezone': 'CEST'}
        Hardware:     3.0
        Software:     1.1.6 Build 240130 Rel.173828
        MAC (rssi):   5C:E9:31:aa:bb:cc (-50)
        Location:     {'latitude': -1, 'longitude': -1}

        == Primary features ==
        State (state): False
        Brightness (brightness): 11 (range: 0-100)
        Color temperature (color_temperature): 0 (range: 2500-6500)
        Light effect (light_effect): *Off* Party Relax

        == Information ==
        Signal Level (signal_level): 2
        Overheated (overheated): False
        Cloud connection (cloud_connection): False
        Update available (update_available): None

        == Configuration ==
        HSV (hsv): HSV(hue=35, saturation=70, value=11)
        Auto update enabled (auto_update_enabled): False
        Light preset (light_preset): *Not set* Light preset 1 Light preset 2 Light preset 3 Light preset 4 Light preset 5 Light preset 6 Light preset 7
        Smooth transition on (smooth_transition_on): 2 (range: 0-60)
        Smooth transition off (smooth_transition_off): 20 (range: 0-60)

        == Debug ==
        Device ID (device_id): someuniqueidentifier
        RSSI (rssi): -50
        SSID (ssid): SecretNetwork
        Current firmware version (current_firmware_version): 1.1.6 Build 240130 Rel.173828
        Available firmware version (available_firmware_version): None
        Time (time): 2024-06-21 15:09:35+02:00

        == Modules ==
        + <Module Brightness (brightness) for 192.0.2.123>
        + <Module Cloud (cloud_connect) for 192.0.2.123>
        + <Module Color (color) for 192.0.2.123>
        + <Module ColorTemperature (color_temperature) for 192.0.2.123>
        + <Module DeviceModule (device) for 192.0.2.123>
        + <Module Firmware (firmware) for 192.0.2.123>
        + <Module LightEffect (light_effect) for 192.0.2.123>
        + <Module LightPreset (preset) for 192.0.2.123>
        + <Module LightTransition (on_off_gradually) for 192.0.2.123>
        + <Module Time (time) for 192.0.2.123>
        + <Module Light (light) for 192.0.2.123>

Command line usage

All devices support a variety of common commands (like on, off, and state). The syntax to control device is kasa --host <host> <command>:

$ kasa --host 192.0.2.123 on

Use kasa --help (or consult the documentation) to get a list of all available commands and options. Some examples of available options include JSON output (--json), defining timeouts (--timeout and --discovery-timeout). Refer the documentation for more details.

Note

Each individual command may also have additional options, which are shown when called with the --help option.

Feature interface

All devices are also controllable through a generic feature-based interface. The available features differ from device to device

$ kasa --host 192.0.2.123 feature
No --type or --device-family and --encrypt-type defined, discovering for 5 seconds..

== Features ==

Device ID (device_id): someuniqueidentifier
State (state): False
Signal Level (signal_level): 3
RSSI (rssi): -49
SSID (ssid): SecretNetwork
Overheated (overheated): False
Brightness (brightness): 11 (range: 0-100)
Cloud connection (cloud_connection): False
HSV (hsv): HSV(hue=35, saturation=70, value=11)
Color temperature (color_temperature): 0 (range: 2500-6500)
Auto update enabled (auto_update_enabled): False
Update available (update_available): None
Current firmware version (current_firmware_version): 1.1.6 Build 240130 Rel.173828
Available firmware version (available_firmware_version): None
Light effect (light_effect): *Off* Party Relax
Light preset (light_preset): *Not set* Light preset 1 Light preset 2 Light preset 3 Light preset 4 Light preset 5 Light preset 6 Light preset 7
Smooth transition on (smooth_transition_on): 2 (range: 0-60)
Smooth transition off (smooth_transition_off): 20 (range: 0-60)
Device time (device_time): 2024-06-21 15:36:32+02:00

Some features are changeable:

kasa --host 192.0.2.123 feature color_temperature 2500
No --type or --device-family and --encrypt-type defined, discovering for 5 seconds..
Changing color_temperature from 0 to 2500
New state: 2500

Note

When controlling hub-connected devices, you need to pass the device ID of the connected device as an option: kasa --host 192.0.2.200 feature --child someuniqueidentifier target_temperature 21

Library usage

import asyncio
from kasa import Discover

async def main():
    dev = await Discover.discover_single("192.0.2.123", username="un@example.com", password="pw")
    await dev.turn_on()
    await dev.update()

if __name__ == "__main__":
    asyncio.run(main())

If you want to use this library in your own project, a good starting point is the tutorial in the documentation.

You can find several code examples in the API documentation How to guides.

Information about the library design and the way the devices work can be found in the topics section.

Contributing

Contributions are very welcome! The easiest way to contribute is by creating a fixture file for the automated test suite if your device hardware and firmware version is not currently listed as supported. Please refer to our contributing guidelines.

Supported devices

The following devices have been tested and confirmed as working. If your device is unlisted but working, please consider contributing a fixture file.

Supported Kasa devices

• Plugs: EP10, EP25^*, HS100^**, HS103, HS105, HS110, KP100, KP105, KP115, KP125, KP125M^*, KP401
• Power Strips: EP40, HS107, HS300, KP200, KP303, KP400
• Wall Switches: ES20M, HS200, HS210, HS220, KP405, KS200M, KS205^*, KS220M, KS225^*, KS230, KS240^*
• Bulbs: KL110, KL120, KL125, KL130, KL135, KL50, KL60, LB110
• Light Strips: KL400L5, KL420L5, KL430
• Hubs: KH100^*
• Hub-Connected Devices^***: KE100^*

Supported Tapo^* devices

• Plugs: P100, P110, P115, P125M, P135, TP15
• Power Strips: P300, TP25
• Wall Switches: S500D, S505, S505D
• Bulbs: L510B, L510E, L530E
• Light Strips: L900-10, L900-5, L920-5, L930-5
• Hubs: H100
• Hub-Connected Devices^***: T110, T300, T310, T315

^*   Model requires authentication
^**  Newer versions require authentication
^*** Devices may work across TAPO/KASA branded hubs

See supported devices in our documentation for more detailed information about tested hardware and software versions.

Resources

Developer Resources

• softScheck's github contains lot of information and wireshark dissector
• TP-Link Smart Home Device Simulator
• Unofficial API documentation
• Another unofficial API documentation
• pyHS100 provides synchronous interface and is the unmaintained predecessor of this library.

Library Users

• Home Assistant
• MQTT access to TP-Link devices, using python-kasa

TP-Link Tapo support

This library has recently added a limited supported for devices that carry Tapo branding. That support is currently limited to the cli. The package kasa.smart is in flux and if you use it directly you should expect it could break in future releases until this statement is removed.

Other TAPO libraries are:

• PyTapo - Python library for communication with Tapo Cameras
• Tapo P100 (Tapo plugs, Tapo bulbs)
  • Home Assistant integration
• plugp100, another tapo library
  • Home Assistant integration
• rust and python implementation