Skip to content

Update README to be more approachable for new users #994

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 21, 2024
Merged

Update README to be more approachable for new users #994

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
91d505f
Update README to be more approachable for new users
rytilahti Jun 21, 2024
7541b5c
Update README.md
rytilahti Jun 21, 2024
463128d
Apply suggestions from code review
rytilahti Jun 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 103 additions & 101 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -47,130 +32,147 @@ 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:

```
$ 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}

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

== Current State ==
<EmeterStatus power=2.4 voltage=None current=None total=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}

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

```
$ kasa on --help

Usage: kasa on [OPTIONS]
### Feature interface

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

Options:
--index INTEGER
--name TEXT
--transition INTEGER
--help Show this message and exit.
```
$ kasa --host 192.0.2.123 feature
No --type or --device-family and --encrypt-type defined, discovering for 5 seconds..

== Features ==

### 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.
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 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.
> [!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`

### 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.
## Library usage

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.

import asyncio
from kasa import Discover

## Energy meter
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()

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`.

```
$ kasa emeter
== Emeter ==
Current state: {'total': 133.105, 'power': 108.223577, 'current': 0.54463, 'voltage': 225.296283}
if __name__ == "__main__":
asyncio.run(main())
```

# Library usage

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).
Expand Down
Loading