mirror of
https://github.com/python-kasa/python-kasa.git
synced 2024-12-22 19:23:34 +00:00
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>
This commit is contained in:
Teemu R
GitHub
parent
cee8b0fadc
commit
c50ae33346
208
README.md
208
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 ==
|
||||
<EmeterStatus power=2.4 voltage=None current=None total=None>
|
||||
== 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 Schedule (smartlife.iot.common.schedule) for 192.168.xx.xx>
|
||||
+ <Module Usage (smartlife.iot.common.schedule) for 192.168.xx.xx>
|
||||
+ <Module Antitheft (smartlife.iot.common.anti_theft) for 192.168.xx.xx>
|
||||
+ <Module Time (smartlife.iot.common.timesetting) for 192.168.xx.xx>
|
||||
+ <Module Emeter (smartlife.iot.common.emeter) for 192.168.xx.xx>
|
||||
- <Module Countdown (countdown) for 192.168.xx.xx>
|
||||
+ <Module Cloud (smartlife.iot.common.cloud) for 192.168.xx.xx>
|
||||
+ <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>
|
||||
```
|
||||
|
||||
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 <host> <command>`:
|
||||
|
||||
* `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 <ip address> <command>`.
|
||||
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 <addr> 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 <addr> off # turns off all sockets
|
||||
$ kasa --host <addr> 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).
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user