From c50ae33346a333331eb74d47af41a6e74f74fed3 Mon Sep 17 00:00:00 2001 From: Teemu R Date: Fri, 21 Jun 2024 20:37:46 +0200 Subject: [PATCH] Update README to be more approachable for new users (#994) UX first approach for both cli & library users, to get you directly started with the basics. Co-authored-by: Steven B. <51370195+sdb9696@users.noreply.github.com> --- README.md | 208 +++++++++++++++++++++++++++--------------------------- 1 file changed, 105 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 1ef24953..36efa8fc 100644 --- a/README.md +++ b/README.md @@ -20,21 +20,6 @@ You can install the most recent release using pip: pip install python-kasa ``` -For enhanced cli tool support (coloring, embedded shell) install with `[shell]`: -``` -pip install python-kasa[shell] -``` - -If you are using cpython, it is recommended to install with `[speedups]` to enable orjson (faster json support): -``` -pip install python-kasa[speedups] -``` -or for both: -``` -pip install python-kasa[speedups, shell] -``` -With `[speedups]`, the protocol overhead is roughly an order of magnitude lower (benchmarks available in devtools). - Alternatively, you can clone this repository and use poetry to install the development version: ``` git clone https://github.com/python-kasa/python-kasa.git @@ -47,7 +32,11 @@ 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 system has multiple network interfaces, you can specify the broadcast address using the `--target` option. +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: @@ -55,121 +44,134 @@ The `discover` command will automatically execute the `state` command on all the $ kasa discover Discovering devices on 255.255.255.255 for 3 seconds -== Bulb McBulby - KL130(EU) == - Host: 192.168.xx.xx - Port: 9999 - Device state: True +== Bulb McBulby - L530 == + Host: 192.0.2.123 + Port: 80 + Device state: False == Generic information == - Time: 2023-12-05 14:33:23 (tz: {'index': 6, 'err_code': 0} - Hardware: 1.0 - Software: 1.8.8 Build 190613 Rel.123436 - MAC (rssi): 1c:3b:f3:xx:xx:xx (-56) - Location: {'latitude': None, 'longitude': None} + 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} - == Device specific information == - Brightness: 16 - Is dimmable: True - Color temperature: 2500 - Valid temperature range: ColorTempRange(min=2500, max=9000) - HSV: HSV(hue=0, saturation=0, value=16) - Presets: - index=0 brightness=50 hue=0 saturation=0 color_temp=2500 custom=None id=None mode=None - index=1 brightness=100 hue=299 saturation=95 color_temp=0 custom=None id=None mode=None - index=2 brightness=100 hue=120 saturation=75 color_temp=0 custom=None id=None mode=None - index=3 brightness=100 hue=240 saturation=75 color_temp=0 custom=None id=None mode=None + == 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 - == Current State == - + == 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 == - + - + - + - + - + - - - + + + + + + + + + + + + + + + + + + + + + + + ``` -If your device requires authentication to control it, -you need to pass the credentials using `--username` and `--password` options. -## Basic functionalities +## Command line usage -All devices support a variety of common commands, including: +All devices support a variety of common commands (like `on`, `off`, and `state`). +The syntax to control device is `kasa --host `: -* `state` which returns state information -* `on` and `off` for turning the device on or off -* `emeter` (where applicable) to return energy consumption information -* `sysinfo` to return raw system information +``` +$ kasa --host 192.0.2.123 on +``` -The syntax to control device is `kasa --host `. 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`), defining timeouts (`--timeout` and `--discovery-timeout`). +Refer [the documentation](https://python-kasa.readthedocs.io/en/latest/cli.html) for more details. -Each individual command may also have additional options, which are shown when called with the `--help` option. -For example, `--transition` on bulbs requests a smooth state change, while `--name` and `--index` are used on power strips to select the socket to act on: +> [!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 on --help +$ kasa --host 192.0.2.123 feature +No --type or --device-family and --encrypt-type defined, discovering for 5 seconds.. -Usage: kasa on [OPTIONS] +== Features == - Turn the device on. - -Options: - --index INTEGER - --name TEXT - --transition INTEGER - --help Show this message and exit. +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 ``` - -### Bulbs - -Common commands for bulbs and light strips include: - -* `brightness` to control the brightness -* `hsv` to control the colors -* `temperature` to control the color temperatures - -When executed without parameters, these commands will report the current state. - -Some devices support `--transition` option to perform a smooth state change. -For example, the following turns the light to 30% brightness over a period of five seconds: +Some features are changeable: ``` -$ kasa --host brightness --transition 5000 30 +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 ``` -See `--help` for additional options and [the documentation](https://python-kasa.readthedocs.io/en/latest/smartbulb.html) for more details about supported features and limitations. - -### Power strips - -Each individual socket can be controlled separately by passing `--index` or `--name` to the command. -If neither option is defined, the commands act on the whole power strip. - -For example: -``` -$ kasa --host off # turns off all sockets -$ kasa --host off --name 'Socket1' # turns off socket named 'Socket1' -``` - -See `--help` for additional options and [the documentation](https://python-kasa.readthedocs.io/en/latest/smartstrip.html) for more details about supported features and limitations. +> [!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` -## Energy meter - -Running `kasa emeter` command will return the current consumption. -Possible options include `--year` and `--month` for retrieving historical state, -and reseting the counters can be done with `--erase`. +## Library usage ``` -$ kasa emeter -== Emeter == -Current state: {'total': 133.105, 'power': 108.223577, 'current': 0.54463, 'voltage': 225.296283} -``` +import asyncio +from kasa import Discover -# Library usage +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](https://python-kasa.readthedocs.io/en/latest/tutorial.html).