Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/python-kasa/python-kasa

🏠🤖 Python API for TP-Link smarthome products
https://github.com/python-kasa/python-kasa

asyncio kasa python smarthome tapo tplink

Last synced: 10 days ago
JSON representation

🏠🤖 Python API for TP-Link smarthome products

Host: GitHub
URL: https://github.com/python-kasa/python-kasa
Owner: python-kasa
License: other
Created: 2019-11-13T23:34:19.000Z (almost 5 years ago)
Default Branch: master
Last Pushed: 2024-10-29T09:40:14.000Z (11 days ago)
Last Synced: 2024-10-29T09:42:58.370Z (11 days ago)
Topics: asyncio, kasa, python, smarthome, tapo, tplink
Language: Python
Homepage: https://python-kasa.readthedocs.io/en/stable/
Size: 3.3 MB
Stars: 1,227
Watchers: 31
Forks: 201
Open Issues: 58
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Support: SUPPORTED.md

Awesome Lists containing this project

awesome-starred - python-kasa/python-kasa - 🏠🤖 Python API for TP-Link Kasa Smarthome products (hacktoberfest)

README

        # python-kasa

[![PyPI version](https://badge.fury.io/py/python-kasa.svg)](https://badge.fury.io/py/python-kasa)

[![Build Status](https://github.com/python-kasa/python-kasa/actions/workflows/ci.yml/badge.svg)](https://github.com/python-kasa/python-kasa/actions/workflows/ci.yml)

[![codecov](https://codecov.io/gh/python-kasa/python-kasa/branch/master/graph/badge.svg?token=5K7rtN5OmS)](https://codecov.io/gh/python-kasa/python-kasa)

[![Documentation Status](https://readthedocs.org/projects/python-kasa/badge/?version=latest)](https://python-kasa.readthedocs.io/en/latest/?badge=latest)

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 `uv` to install the development version:

```

git clone https://github.com/python-kasa/python-kasa.git

cd python-kasa/

uv sync --all-extras

uv run kasa

```

If you have not yet provisioned your device, [you can do so using the cli tool](https://python-kasa.readthedocs.io/en/latest/cli.html#provisioning).

## 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

Time:         2024-06-22 15:42:15+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)

== 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

Device time (device_time): 2024-06-22 15:42:15+02:00

== 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): soneuniqueidentifier

RSSI (rssi): -50 dBm

SSID (ssid): HomeNet

Current firmware version (current_firmware_version): 1.1.6 Build 240130 Rel.173828

Available firmware version (available_firmware_version): None

```

## Command line usage

All devices support a variety of common commands (like `on`, `off`, and `state`).

The syntax to control device is `kasa --host  `:

```

$ kasa --host 192.0.2.123 on

```

Use `kasa --help` ([or consult the documentation](https://python-kasa.readthedocs.io/en/latest/cli.html#kasa-help)) to get a list of all available commands and options.

Some examples of available options include JSON output (`--json`), more verbose output (`--verbose`), and defining timeouts (`--timeout` and `--discovery-timeout`).

Refer [the documentation](https://python-kasa.readthedocs.io/en/latest/cli.html) 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 and are accessible using `kasa feature` command:

```

$ kasa --host 192.0.2.123 feature

== 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

Device time (device_time): 2024-06-22 15:39:44+02:00

== 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): soneuniqueidentifier

RSSI (rssi): -50 dBm

SSID (ssid): HomeNet

Current firmware version (current_firmware_version): 1.1.6 Build 240130 Rel.173828

Available firmware version (available_firmware_version): None

```

Some features present configuration that can be changed:

```

kasa --host 192.0.2.123 feature color_temperature 2500

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="[email protected]", 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](https://python-kasa.readthedocs.io/en/latest/tutorial.html).

You can find several code examples in the API documentation [How to guides](https://python-kasa.readthedocs.io/en/latest/guides.html).

Information about the library design and the way the devices work can be found in the [topics section](https://python-kasa.readthedocs.io/en/latest/topics.html).

## Contributing

Contributions are very welcome! The easiest way to contribute is by [creating a fixture file](https://python-kasa.readthedocs.io/en/latest/contribute.html#contributing-fixture-files) for the automated test suite if your device hardware and firmware version is not currently listed as supported.

Please refer to [our contributing guidelines](https://python-kasa.readthedocs.io/en/latest/contribute.html).

## 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](https://python-kasa.readthedocs.io/en/latest/contribute.html#contributing-fixture-files).

> [!NOTE]

> The hub attached Tapo buttons S200B and S200D do not currently support alerting when the button is pressed.

### 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, P304M, 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^\*\*\***: S200B, S200D, T100, 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](SUPPORTED.md) for more detailed information about tested hardware and software versions.

## Resources

### Developer Resources

* [softScheck's github contains lot of information and wireshark dissector](https://github.com/softScheck/tplink-smartplug#wireshark-dissector)

* [TP-Link Smart Home Device Simulator](https://github.com/plasticrake/tplink-smarthome-simulator)

* [Unofficial API documentation](https://github.com/plasticrake/tplink-smarthome-api)

* [Another unofficial API documentation](https://github.com/whitslack/kasa)

* [pyHS100](https://github.com/GadgetReactor/pyHS100) provides synchronous interface and is the unmaintained predecessor of this library.

### Library Users

* [Home Assistant](https://www.home-assistant.io/integrations/tplink/)

* [MQTT access to TP-Link devices, using python-kasa](https://github.com/flavio-fernandes/mqtt2kasa)

### Other related projects

* [PyTapo - Python library for communication with Tapo Cameras](https://github.com/JurajNyiri/pytapo)

* [Tapo P100 (Tapo plugs, Tapo bulbs)](https://github.com/fishbigger/TapoP100)

  * [Home Assistant integration](https://github.com/fishbigger/HomeAssistant-Tapo-P100-Control)

* [plugp100, another tapo library](https://github.com/petretiandrea/plugp100)

  * [Home Assistant integration](https://github.com/petretiandrea/home-assistant-tapo-p100)

* [rust and python implementation for tapo devices](https://github.com/mihai-dinculescu/tapo/)