Python Kasa

https://python-kasa.readthedocs.io/en/stable
Admin
Python Kasa is a Python library designed to control TP-Link's Kasa and Tapo smart home devices...
Tokens:103,211
Snippets:919
Trust Score:8.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install development version of python-kasa

Source: https://python-kasa.readthedocs.io/en/stable/index.html

Clone the repository and install the development version using uv.

```bash
git clone https://github.com/python-kasa/python-kasa.git
cd python-kasa/
uv sync --all-extras
uv run kasa

```

--------------------------------

### Initialize hub for child setup

Source: https://python-kasa.readthedocs.io/en/stable/guides/strip.html

Discover a hub device to access the ChildSetup module.

```python
from kasa import Discover, Module, LightState

dev = await Discover.discover_single(
    "127.0.0.6",
    username="user@example.com",
    password="great_password"
)
await dev.update()
print(dev.alias)
```

--------------------------------

### Install python-kasa using pip

Source: https://python-kasa.readthedocs.io/en/stable/index.html

Install the most recent release of the python-kasa library using pip.

```bash
pip install python-kasa

```

--------------------------------

### Discover and access device

Source: https://python-kasa.readthedocs.io/en/stable/guides/module.html

Example of discovering a device and printing its alias.

```python
from kasa import Discover, Module

dev = await Discover.discover_single(
    "127.0.0.3",
    username="user@example.com",
    password="great_password"
)
await dev.update()
print(dev.alias)
```

--------------------------------

### Start Discovery Task

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/discover.html

Initiates the asynchronous discovery process by creating a task for `do_discover` and setting a started event.

```python
self.discover_task = asyncio.create_task(self.do_discover())
self._started_event.set()
```

--------------------------------

### Connect to device in async function

Source: https://python-kasa.readthedocs.io/en/stable/guides/connect.html

Example of connecting to a device, turning it on, and updating its state within an async function.

```python
import asyncio
from kasa import Discover

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

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

--------------------------------

### Interact with Light Effects

Source: https://python-kasa.readthedocs.io/en/stable/guides/light.html

Initial setup for interacting with light effects.

```python
from kasa import Discover, Module, LightState

dev = await Discover.discover_single(
    "127.0.0.3",
    username="user@example.com",
    password="great_password"
)
await dev.update()
print(dev.alias)
```

--------------------------------

### Start asyncio REPL

Source: https://python-kasa.readthedocs.io/en/stable/guides/connect.html

Command to launch the Python asyncio REPL for testing library methods.

```bash
$ python -m asyncio
```

--------------------------------

### Command-line usage for SmartStrip

Source: https://python-kasa.readthedocs.io/en/stable/smartstrip.html

Examples of how to control individual sockets on a SmartStrip using the kasa CLI tool.

```APIDOC
## Command-line usage

### Description
Control individual sockets on a smart strip by specifying the index or name. If no index or name is provided, commands apply to the entire strip.

### Examples

Turn on the first socket (index 0):
`kasa --type strip --host <host> on --index 0`

Turn off a socket by name:
`kasa --type strip --host <host> off --name "Maybe Kitchen"`
```

--------------------------------

### Accessing Device Features

Source: https://python-kasa.readthedocs.io/en/stable/tutorial.html

Device features provide direct access to specific functionalities. This example demonstrates getting and setting the `auto_update_enabled` feature and iterating through all available features.

```python
print(auto_update.value)
if auto_update:
    await auto_update.set_value(True)
    await dev.update()
    print(auto_update.value)
for feat in dev.features.values():
    print(f"{feat.name}: {feat.value}")

```

--------------------------------

### Clone Repository and Sync Dependencies

Source: https://python-kasa.readthedocs.io/en/stable/_sources/contribute.md.txt

Clone the python-kasa repository and install all necessary packages and development extras using uv.

```bash
git clone https://github.com/python-kasa/python-kasa.git
cd python-kasa
uv sync --all-extras
```

--------------------------------

### Basic Async Device Control

Source: https://python-kasa.readthedocs.io/en/stable/tutorial.html

This example demonstrates how to discover a single device by IP address, turn it on, and update its state within an async function. All async operations must run within the same event loop.

```python
import asyncio
from kasa import Discover

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

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

```

--------------------------------

### Basic SmartDevice Functionality Example

Source: https://python-kasa.readthedocs.io/en/stable/_sources/smartdevice.rst.txt

Demonstrates basic SmartDevice operations like updating, printing alias and emeter, and turning off the device. Ensure the device is accessible and the correct event loop is used for asynchronous operations.

```python
import asyncio
from kasa import SmartPlug

async def main():
    p = SmartPlug("127.0.0.1")

    await p.update()  # Request the update
    print(p.alias)  # Print out the alias
    print(p.emeter_realtime)  # Print out current emeter status

    await p.turn_off()  # Turn the device off

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

--------------------------------

### Get Kasa CLI Help

Source: https://python-kasa.readthedocs.io/en/stable/_sources/cli.rst.txt

Displays detailed usage information for the Kasa CLI tool. Use this to understand all available commands and options.

```bash
kasa --help
```

--------------------------------

### Discovering Multiple Devices

Source: https://python-kasa.readthedocs.io/en/stable/tutorial.html

Use `Discover.discover()` to get a dictionary of all devices on your network. You can then iterate through the devices to update their states and print their hostnames.

```python
from kasa import Discover

devices = await Discover.discover(username="user@example.com", password="great_password")
for dev in devices.values():
    await dev.update()
    print(dev.host)

```

--------------------------------

### Interacting with Light Module

Source: https://python-kasa.readthedocs.io/en/stable/tutorial.html

Access device modules via the `modules` attribute. This example shows how to interact with the `Light` module, check for features like brightness and HSV, and set the brightness.

```python
from kasa import Module

print(Module.Light in dev.modules)
light = dev.modules[Module.Light]
print(light.brightness)
await light.set_brightness(50)
await dev.update()
print(light.brightness)
print(light.has_feature("hsv"))
if light.has_feature("hsv"):
    print(light.hsv)

```

--------------------------------

### View Preset States

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/lightpreset.html

Get the detailed light states for all available presets.

```APIDOC
## Get Preset States List

### Description
Retrieves a list of `LightState` objects, each representing the configuration of a specific preset.

### Method
GET

### Endpoint
`/preset_states_list` (Internal representation, accessed via `light_preset.preset_states_list`)

### Response
#### Success Response (200)
- **preset_states_list** (Sequence[LightState]) - A sequence of `LightState` objects.

### Response Example
```json
{
  "preset_states_list": [
    {
      "light_on": true,
      "brightness": 50,
      "hue": 0,
      "saturation": 100,
      "color_temp": 2700,
      "transition": null
    }
  ]
}
```
```

--------------------------------

### Access Device Modules

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Iterate through the available modules for a device and access specific module functionalities. This example shows how to interact with the 'Led' module to control the device's LED status.

```python
>>> for module_name in dev.modules:
>>>     print(module_name)
Energy
schedule
usage
anti_theft
Time
cloud
Led

>>> led_module = dev.modules["Led"]
>>> print(led_module.led)
False
>>> await led_module.set_led(True)
>>> await dev.update()
>>> print(led_module.led)
True
```

--------------------------------

### Get Device Instance from Discovery

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/discover.html

Constructs a SmartDevice instance from a device's discovery information. Handles parsing, decryption, and connection parameter determination.

```python
def _get_device_instance(
        info: dict,
        config: DeviceConfig,
    ) -> Device:
        """Get SmartDevice from the new 20002 response."""
        debug_enabled = _LOGGER.isEnabledFor(logging.DEBUG)

        try:
            discovery_result = DiscoveryResult.from_dict(info["result"])
        except Exception as ex:
            if debug_enabled:
                data = (
                    redact_data(info, NEW_DISCOVERY_REDACTORS)
                    if Discover._redact_data
                    else info
                )
                _LOGGER.debug(
                    "Unable to parse discovery from device %s: %s",
                    config.host,
                    pf(data),
                )
            raise UnsupportedDeviceError(
                f"Unable to parse discovery from device: {config.host}: {ex}",
                host=config.host,
            ) from ex

        # Decrypt the data
        if (
            encrypt_info := discovery_result.encrypt_info
        ) and encrypt_info.sym_schm == "AES":
            try:
                Discover._decrypt_discovery_data(discovery_result)
            except Exception:
                _LOGGER.exception(
                    "Unable to decrypt discovery data %s: %s",
                    config.host,
                    redact_data(info, NEW_DISCOVERY_REDACTORS),
                )
        type_ = discovery_result.device_type
        try:
            conn_params = Discover._get_connection_parameters(discovery_result)
            config.connection_type = conn_params
        except KasaException as ex:
            if isinstance(ex, UnsupportedDeviceError):
                raise
            raise UnsupportedDeviceError(
                f"Unsupported device {config.host} of type {type_} "
                + f"with encrypt_scheme {discovery_result.mgt_encrypt_schm}",
                discovery_result=discovery_result.to_dict(),
                host=config.host,
            ) from ex

        if (
            device_class := get_device_class_from_family(type_, https=conn_params.https)
        ) is None:
            _LOGGER.debug("Got unsupported device type: %s", type_)
            raise UnsupportedDeviceError(
                f"Unsupported device {config.host} of type {type_}: {info}",
                discovery_result=discovery_result.to_dict(),
                host=config.host,
            )

        if (protocol := get_protocol(config)) is None:
            _LOGGER.debug(
                "Got unsupported connection type: %s", config.connection_type.to_dict()
            )
            raise UnsupportedDeviceError(
                f"Unsupported encryption scheme {config.host} of "
                + f"type {config.connection_type.to_dict()}: {info}",
```

--------------------------------

### Get Light Module and Check Features

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/light.html

Access the specific light module from the device and check for supported features like brightness, HSV, and color temperature.

```python
light = dev.modules[Module.Light]

light.has_feature("brightness")
light.has_feature("hsv")
light.has_feature("color_temp")
```

--------------------------------

### Install Pre-commit Hooks

Source: https://python-kasa.readthedocs.io/en/stable/_sources/contribute.md.txt

Activate pre-commit hooks to automatically check code formatting and style before each commit. This ensures consistency and adherence to project standards.

```bash
pre-commit install
```

--------------------------------

### Get Device Features

Source: https://python-kasa.readthedocs.io/en/stable/index.html

Use the 'kasa feature' command to list all available features for a device, including their current states and ranges. This is useful for understanding a device's capabilities.

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

```

--------------------------------

### Initialize and Update IotBulb

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Demonstrates how to initialize an IotBulb instance and fetch its current state by awaiting the `update()` method. This is a prerequisite for accessing device properties.

```python
bulb = IotBulb("127.0.0.1")
asyncio.run(bulb.update())
```

--------------------------------

### Discover and Control Device with Python

Source: https://python-kasa.readthedocs.io/en/stable/index.html

This Python script demonstrates how to discover a single device by its IP address and credentials, then turn it on and update its state. Ensure you have 'asyncio' imported.

```python
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())

```

--------------------------------

### Handle Device Error for Get Requests

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/protocols/smartcamprotocol.html

Raises a DeviceError if a 'get' request returns no results or an empty dictionary for the section. This indicates that the requested data was not found on the device.

```python
if single_request.method_type == "get" and (
            not (section := next(iter(response_data))) or response_data[section] == {}
        ):
            raise DeviceError(
                f"No results for get request {single_request.method_name}"
            )
```

--------------------------------

### Get Device Type

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the type of the Kasa device.

```python
dev_type = my_device.device_type
```

--------------------------------

### Define FeatureAttribute property

Source: https://python-kasa.readthedocs.io/en/stable/guides/module.html

Example of annotating a property with FeatureAttribute.

```python
@property
def hsv(self) -> Annotated[HSV, FeatureAttribute()]:
    """Return the current HSV state of the bulb."""
```

--------------------------------

### Device Configuration Initialization

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/deviceconfig.html

Shows the default connection parameters for a smart plug switch if not explicitly provided.

```python
def __post_init__(self) -> None:
        if self.connection_type is None:
            self.connection_type = DeviceConnectionParameters(
                DeviceFamily.IotSmartPlugSwitch, DeviceEncryptionType.Xor
            )
```

--------------------------------

### Get Device Model

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the model name or identifier of the device.

```python
model = my_device.model
```

--------------------------------

### Get Device Credentials

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the credentials used for device communication.

```python
creds = my_device.credentials
```

--------------------------------

### turn_on

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Asynchronously turns the device on. Accepts optional keyword arguments for specific behaviors.

```APIDOC
## turn_on

### Description
Turn on the device.

### Method
`async def turn_on(self, **kwargs) -> dict`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **kwargs**: Arbitrary keyword arguments that might be passed to the underlying protocol for specific behaviors.

### Request Example
```python
# Assuming 'my_device' is an instance of a Kasa device
# await my_device.turn_on()
```

### Response
#### Success Response (dict)
- Returns a dictionary containing the result of the operation.
```

--------------------------------

### Get Device Hostname

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the hostname or IP address of the device.

```python
device_host = my_device.host
```

--------------------------------

### Get Device Timezone

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/time.html

Retrieves the current timezone setting of the device.

```APIDOC
## Get Device Timezone

### Description
Retrieves the current timezone setting of the device.

### Method
GET (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
None

### Response
#### Success Response
- **timezone** (tzinfo) - Current timezone.
```

--------------------------------

### Basic SmartPlug functionality

Source: https://python-kasa.readthedocs.io/en/stable/smartdevice.html

Demonstrates initializing a SmartPlug, updating its state, accessing properties, and performing a state change.

```python
import asyncio
from kasa import SmartPlug

async def main():
    p = SmartPlug("127.0.0.1")

    await p.update()  # Request the update
    print(p.alias)  # Print out the alias
    print(p.emeter_realtime)  # Print out current emeter status

    await p.turn_off()  # Turn the device off

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

--------------------------------

### Get Device Time

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/time.html

Retrieves the current timezone-aware time from the device.

```APIDOC
## Get Device Time

### Description
Retrieves the current timezone-aware time from the device.

### Method
GET (conceptual)

### Endpoint
N/A (SDK method)

### Parameters
None

### Response
#### Success Response
- **time** (datetime) - Timezone aware current device time.
```

--------------------------------

### Instantiate Legacy Device from Discovery Info

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/discover.html

Creates an IotDevice instance from legacy discovery information. Updates the device configuration and protocol based on the parsed system information.

```python
def _get_device_instance_legacy(info: dict, config: DeviceConfig) -> Device:
        """Get IotDevice from legacy 9999 response."""
        if _LOGGER.isEnabledFor(logging.DEBUG):
            data = redact_data(info, IOT_REDACTORS) if Discover._redact_data else info
            _LOGGER.debug("[DISCOVERY] %s << %s", config.host, pf(data))

        device_class = cast(type[IotDevice], Discover._get_device_class(info))
        device = device_class(config.host, config=config)
        sys_info = _extract_sys_info(info)
        device_type = sys_info.get("mic_type", sys_info.get("type"))
        login_version = (
            sys_info.get("stream_version") if device_type == "IOT.IPCAMERA" else None
        )
        config.connection_type = DeviceConnectionParameters.from_values(
            device_family=device_type,
            encryption_type=DeviceEncryptionType.Xor.value,
            https=device_type == "IOT.IPCAMERA",
            login_version=login_version,
        )
        device.protocol = get_protocol(config)  # type: ignore[assignment]
        device.update_from_discover_info(info)
        return device
```

--------------------------------

### Get Device Region

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the geographical region associated with the device, if available.

```python
region = my_device.region
```

--------------------------------

### Turn Device On

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Asynchronously turns the device on. Accepts optional keyword arguments for specific settings.

```python
await my_device.turn_on()
```

--------------------------------

### Get Device Port

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the network port the device is using for communication.

```python
device_port = my_device.port
```

--------------------------------

### View Current Preset

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/lightpreset.html

Get the name of the currently active light preset.

```APIDOC
## Get Current Preset

### Description
Retrieves the name of the currently active light preset.

### Method
GET

### Endpoint
`/preset` (Internal representation, accessed via `light_preset.preset`)

### Response
#### Success Response (200)
- **preset** (str) - The name of the current preset.

### Response Example
```json
{
  "preset": "Light preset 1"
}
```
```

--------------------------------

### Connect to Device with Protocol and Config

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/discover.html

Iterates through potential device configurations and protocols to establish a connection. Logs connection attempts and returns the connected device or None if unsuccessful. Ensures protocol closure in all cases.

```python
for key, val in candidates.items():
            try:
                prot, config = val
                _LOGGER.debug("Trying to connect with %s", prot.__class__.__name__)
                dev = await _connect(config, prot)
            except Exception as ex:
                _LOGGER.debug(
                    "Unable to connect with %s: %s",
                    prot.__class__.__name__,
                    ex,
                )
                if on_attempt:
                    ca = tuple.__new__(ConnectAttempt, key)
                    on_attempt(ca, False)
            else:
                if on_attempt:
                    ca = tuple.__new__(ConnectAttempt, key)
                    on_attempt(ca, True)
                _LOGGER.debug("Found working protocol %s", prot.__class__.__name__)
                return dev
            finally:
                await prot.close()
        return None
```

--------------------------------

### Get Current Light Effect

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/lighteffect.html

Retrieve the name of the currently active light effect.

```python
>>> light_effect.effect
Off
```

--------------------------------

### Turn on a Smart Strip Socket by Index

Source: https://python-kasa.readthedocs.io/en/stable/_sources/smartstrip.rst.txt

Use this command to turn on a specific socket of a smart strip. Sockets are zero-indexed. Ensure you replace `<host>` with the actual IP address or hostname of your device.

```bash
$ kasa --type strip --host <host> on --index 0
```

--------------------------------

### Fan Speed Level

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/fan.html

Provides methods to get and set the fan speed level.

```APIDOC
## Fan Speed Level

### Description
Provides methods to get and set the fan speed level.

### Get Fan Speed Level

#### Method
GET (conceptual)

#### Endpoint
N/A (SDK method)

#### Returns
- **fan_speed_level** (int) - The current fan speed level.

### Set Fan Speed Level

#### Method
POST (conceptual)

#### Endpoint
N/A (SDK method)

#### Parameters
##### Request Body
- **level** (int) - Required - The desired fan speed level.

#### Returns
- **dict** - A dictionary containing the result of the operation.

```

--------------------------------

### Get Public Key in PEM Format

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/transports/aestransport.html

Returns the public key encoded in PEM format.

```python
return self.public_key.public_bytes(
    encoding=serialization.Encoding.PEM,
    format=serialization.PublicFormat.SubjectPublicKeyInfo,
)
```

--------------------------------

### set_turn_on_behavior

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Sets the behavior for when the bulb is turned on. Use `get_turn_on_behavior` to get current settings if needed.

```APIDOC
## set_turn_on_behavior

### Description
Set the behavior for turning the bulb on.

### Method
POST (Implicit)

### Endpoint
(Internal method, not a direct HTTP endpoint)

### Parameters
#### Request Body
- **behavior** (TurnOnBehaviors) - Required - The desired turn-on behavior.

### Request Example
```json
{
  "behavior": {
    "state": "power_on"
  }
}
```

### Response
#### Success Response (200)
- **(dict)** - A dictionary confirming the operation.

### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Display Kasa CLI Help

Source: https://python-kasa.readthedocs.io/en/stable/cli.html

View the available options and subcommands for the kasa command-line tool.

```text
Usage: kasa [OPTIONS] COMMAND [ARGS]...

  A tool for controlling TP-Link smart home devices.

Options:
  --host TEXT                     The host name or IP address of the device to
                                  connect to.
  --port INTEGER                  The port of the device to connect to.
  --alias TEXT                    The device name, or alias, of the device to
                                  connect to.
  --target TEXT                   The broadcast address to be used for
                                  discovery.  [default: 255.255.255.255]
  -v, --verbose                   Be more verbose on output
  -d, --debug                     Print debug output
  --type [plug|switch|bulb|dimmer|strip|lightstrip|smart|camera]
                                  The device type in order to bypass
                                  discovery. Use `smart` for newer devices
  --json / --no-json              Output raw device response as JSON.
  -e, --encrypt-type [KLAP|AES|XOR]
  -df, --device-family TEXT       Device family type, e.g. `SMART.KASASWITCH`.
                                  Deprecated use `--type smart`
  -lv, --login-version INTEGER    The login version for device authentication.
                                  Defaults to 2
  --https / --no-https            Set flag if the device encryption uses
                                  https.
  --timeout INTEGER               Timeout for device communications.
                                  [default: 5]
  --discovery-timeout INTEGER     Timeout for discovery.  [default: 10]
  --username TEXT                 Username/email address to authenticate to
                                  device.
  --password TEXT                 Password to use to authenticate to device.
  --credentials-hash TEXT         Hashed credentials used to authenticate to
                                  the device.
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Subcommands:
  discover  Discover devices in the network.
  device    Commands to control basic device settings.
  feature   Access and modify features.
  light     Commands to control light settings.
  wifi      Commands to control wifi settings.
  time      Get and set time.
  schedule  Scheduling commands.
  usage     Query usage for historical consumption.

Common usage commands (also available under the `usage` subcommand):
  energy  Query energy module for historical...

Common device commands (also available under the `device` subcommand):
  state               Print out device state and versions.
  on                  Turn the device on.
  off                 Turn the device off.
  toggle              Toggle the device on/off.
  led                 Get or set (Plug's) led state.
  alias               Get or set the device (or plug) alias.
  reboot              Reboot the device.
  update_credentials  Update device credentials for...
  sysinfo             Print out full system information.

Common light commands (also available under the `light` subcommand):
  presets      List and modify bulb setting presets.
  brightness   Get or set brightness.
  hsv          Get or set color in HSV.
  temperature  Get or set color temperature.
  effect       Set an effect.

Common vacuum commands (also available under the `vacuum` subcommand):
  vacuum  Vacuum commands.

Common hub commands (also available under the `hub` subcommand):
  hub  Commands controlling hub child device...
```

--------------------------------

### Get Device Configuration

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves the device's configuration object, which includes connection parameters.

```python
config = my_device.config
```

--------------------------------

### Get Device Credentials Hash

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves a protocol-specific hash of the credentials the device is currently using.

```python
creds_hash = my_device.credentials_hash
```

--------------------------------

### ChildSetup Interface

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/childsetup.html

The ChildSetup class provides an interface for managing child devices on hubs. It allows users to check supported device categories, pair new devices, and unpair existing ones.

```APIDOC
## ChildSetup

### Description
Interface for child setup on hubs.

### Properties
#### supported_categories
- **Type**: list[str]
- **Description**: Supported child device categories.

### Methods
#### pair
- **Description**: Scan for new devices and pair them.
- **Parameters**:
  - **timeout** (int) - Optional - Timeout in seconds for the pairing process. Defaults to 10.
- **Returns**: list[dict] - A list of dictionaries, where each dictionary contains information about a newly added child device.

#### unpair
- **Description**: Remove device from the hub.
- **Parameters**:
  - **device_id** (str) - Required - The unique identifier of the child device to unpair.
- **Returns**: dict - A dictionary containing the result of the unpairing operation.
```

--------------------------------

### Discover and Connect to a Single Device

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/deviceconfig.html

Use `Discover.discover_single` to connect to a specific device by IP address. The device configuration can then be converted to a dictionary using `to_dict()` and used later to connect to the device via `Device.connect()`.

```python
>>> from kasa import Discover, Device
>>> device = await Discover.discover_single(
>>>     "127.0.0.3",
>>>     username="user@example.com",
>>>     password="great_password",
>>> )
>>> print(device.alias)  # Alias is None because update() has not been called
None

>>> config_dict = device.config.to_dict()
>>> # DeviceConfig.to_dict() can be used to store for later
>>> print(config_dict)
{'host': '127.0.0.3', 'timeout': 5, 'credentials': {'username': 'user@example.com', 
'password': 'great_password'}, 'connection_type'
: {'device_family': 'SMART.TAPOBULB', 'encryption_type': 'KLAP', 'login_version': 2, 
'https': False, 'http_port': 80}}

>>> later_device = await Device.connect(config=Device.Config.from_dict(config_dict))
>>> print(later_device.alias)  # Alias is available as connect() calls update()
Living Room Bulb
```

--------------------------------

### Get Max Device Response Size

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Returns the maximum response size that the device can safely construct.

```python
@property
    def max_device_response_size(self) -> int:
        """Returns the maximum response size the device can safely construct."""
        return 4096
```

--------------------------------

### Discover and inspect a device

Source: https://python-kasa.readthedocs.io/en/stable/guides/strip.html

Connect to a device and retrieve its alias.

```python
from kasa import Discover

dev = await Discover.discover_single(
    "127.0.0.1",
    username="user@example.com",
    password="great_password"
)
await dev.update()
print(dev.alias)
```

--------------------------------

### Initialize LinkieTransportV2

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/transports/linkietransport.html

Initializes the LinkieTransportV2 with device configuration. It sets up an HTTP client and prepares the application URL and headers for communication.

```python
def __init__(self, *, config: DeviceConfig) -> None:
        super().__init__(config=config)
        self._http_client = HttpClient(config)
        self._ssl_context: ssl.SSLContext | None = None
        self._app_url = URL(f"https://{self._host}:{self._port}/data/LINKIE2.json")

        self._headers = {
            "Authorization": f"Basic {self.credentials_hash}",
            "Content-Type": "application/x-www-form-urlencoded",
        }
```

--------------------------------

### Annotating Feature Attributes

Source: https://python-kasa.readthedocs.io/en/stable/topics.html

Example of using the FeatureAttribute annotation to indicate that a property may not be supported by all devices.

```python
    @property
    def hsv(self) -> Annotated[HSV, FeatureAttribute()]:
        """Return the current HSV state of the bulb."""
```

--------------------------------

### Generate Fixture Files

Source: https://python-kasa.readthedocs.io/en/stable/_sources/contribute.md.txt

Generate fixture files by running the dump_devinfo.py script. This script queries a device and saves its responses, which are used for testing. Ensure you are in the main source directory and have activated the virtual environment.

```bash
git clone https://github.com/python-kasa/python-kasa.git
cd python-kasa
uv sync --all-extras
source .venv/bin/activate
python -m devtools.dump_devinfo --username <username> --password <password> --host 192.168.1.123
```

--------------------------------

### Get Plug by Name

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves a child device (plug) by its alias. This method is specific to devices that have child plugs.

```APIDOC
## get_plug_by_name

### Description
Return child device for the given name.

### Parameters
#### Path Parameters
- **name** (str) - Required - The alias of the plug to retrieve.

### Response
#### Success Response (Device)
- Returns the child `Device` object matching the provided name.

#### Error Response (KasaException)
- Raises `KasaException` if no child device with the specified name is found.
```

--------------------------------

### Get Device Info

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves detailed information about the device, including discovery information and last known state.

```python
info = my_device.device_info
```

--------------------------------

### Get Login Parameters

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/transports/aestransport.html

Generates login parameters based on the login version, hashing username and password accordingly.

```python
def _get_login_params(self, credentials: Credentials) -> dict[str, str]:
    """Get the login parameters based on the login_version."""
    un, pw = self.hash_credentials(self._login_version == 2, credentials)
    password_field_name = "password2" if self._login_version == 2 else "password"
    return {password_field_name: pw, "username": un}
```

--------------------------------

### Discover single device and access alias

Source: https://python-kasa.readthedocs.io/en/stable/guides/connect.html

Connects to a specific IP address using credentials and prints the device alias.

```python
from kasa import Discover, Device
device = await Discover.discover_single(
    "127.0.0.3",
    username="user@example.com",
    password="great_password",
)
print(device.alias)  # Alias is None because update() has not been called
```

--------------------------------

### Discover devices with Credentials object

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/discover.html

Discover devices using a `kasa.Credentials` object, which encapsulates username and password. This is an alternative way to provide authentication details.

```python
>>> creds = Credentials("user@example.com", "great_password")
>>> devices = await Discover.discover(credentials=creds)
>>> print(len(devices))
6
```

--------------------------------

### Thermostat State Management

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/thermostat.html

Provides methods to get and set the overall state of the thermostat, including enabling or disabling it.

```APIDOC
## Thermostat State

### Description
Provides methods to get and set the overall state of the thermostat, including enabling or disabling it.

### Methods
- `state()`: Returns the current state of the thermostat (e.g., Heating, Idle, Off).
- `set_state(enabled: bool)`: Sets the thermostat to be enabled or disabled.

### Properties
- `state` (bool): Returns `True` if the thermostat is enabled, `False` otherwise.

### Example
```python
# Assuming 'thermostat' is an instance of a Thermostat subclass
current_state = thermostat.state
await thermostat.set_state(True)
```
```

--------------------------------

### List Available Light Presets

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/lightpreset.html

Access the LightPreset module to retrieve a list of available preset names configured on the device.

```python
>>> light_preset = dev.modules[Module.LightPreset]
>>> light_preset.preset_list
['Not set', 'Light preset 1', 'Light preset 2', 'Light preset 3',
 'Light preset 4', 'Light preset 5', 'Light preset 6', 'Light preset 7']
```

--------------------------------

### IotBulb Class

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Represents a TP-Link Smart Bulb. Initialize by awaiting `update()`. All changes are done via awaitable methods. Errors are raised as KasaException.

```APIDOC
## IotBulb Class

### Description
Represents a TP-Link Smart Bulb. To initialize, you have to await :func:`update()` at least once. This will allow accessing the properties using the exposed properties. All changes to the device are done using awaitable methods, which will not change the cached values, so you must await :func:`update()` to fetch updates values from the device. Errors reported by the device are raised as :class:`KasaException <kasa.exceptions.KasaException>`, and should be handled by the user of the library.

### Methods
- `update()`: Awaits to fetch the latest state from the device.
- `turn_off()`: Turns the bulb off.
- `turn_on()`: Turns the bulb on.
- `set_brightness(brightness: int, transition: int | None = None)`: Sets the brightness of the bulb. Optionally accepts a transition time in milliseconds.
- `set_color_temp(color_temp: int, transition: int | None = None)`: Sets the color temperature of the bulb. Optionally accepts a transition time in milliseconds.
- `set_hsv(hue: int, saturation: int, value: int, transition: int | None = None)`: Sets the bulb's color using HSV values. Optionally accepts a transition time in milliseconds.

### Properties
- `alias`: The alias of the bulb.
- `is_on`: Boolean indicating if the bulb is currently on.
- `is_dimmable`: Boolean indicating if the bulb supports dimming.
- `is_color`: Boolean indicating if the bulb supports color.
- `is_variable_color_temp`: Boolean indicating if the bulb supports variable color temperature.
- `brightness`: The current brightness level of the bulb.
- `color_temp`: The current color temperature of the bulb.
- `hsv`: The current HSV color of the bulb.
- `valid_temperature_range`: The supported color temperature range for the bulb.
```

--------------------------------

### Get Bulb Brightness

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Retrieves the current brightness of the bulb in percentage. Handles cases where effects are active or the bulb is not dimmable.

```python
@property  # type: ignore
    @requires_update
    def _brightness(self) -> int:
        """Return the current brightness in percentage."""
        if not self._is_dimmable:  # pragma: no cover
            raise KasaException("Bulb is not dimmable.")

        # If the device supports effects and one is active, we get the brightness
        # from the effect. This is not required when setting the brightness as
        # the device handles it via set_light_state
        if (
            light_effect := self.modules.get(Module.IotLightEffect)
        ) is not None and light_effect.effect != light_effect.LIGHT_EFFECTS_OFF:
            return light_effect.brightness
        light_state = self.light_state
        return int(light_state["brightness"])
```

--------------------------------

### Get Real-time Energy Statistics

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/energy.html

Retrieve current energy usage statistics from the device. This method is part of the abstract interface.

```python
async def get_status(self) -> EmeterStatus:
    """Return real-time statistics."""
    pass
```

--------------------------------

### Access ChildSetup Module and Supported Categories

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/interfaces/childsetup.html

Access the ChildSetup module from a discovered device and retrieve the list of supported child device categories.

```python
>>> childsetup = dev.modules[Module.ChildSetup]
>>> childsetup.supported_categories
['camera', 'subg.trv', 'subg.trigger', 'subg.plugswitch']
```

--------------------------------

### Discovering a single device object

Source: https://python-kasa.readthedocs.io/en/stable/guides/discover.html

Initializing a single device and accessing its model property.

```python
device = await Discover.discover_single("127.0.0.1", credentials=creds)
device.model
'KP303'
```

--------------------------------

### Smart Protocol List Request Generation

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/protocols/smartprotocol.html

Generates a dictionary for requesting a list of items from a device, specifying the method and start index.

```python
    def _get_list_request(
        self,
        method: str,
        params: dict | None,
        start_index: int,
    ) -> dict:
        return {"method": method, "params": params, "start_index": start_index}
```

--------------------------------

### List device modules

Source: https://python-kasa.readthedocs.io/en/stable/guides/device.html

Iterate through available device modules.

```python
for module_name in dev.modules:
    print(module_name)
```

--------------------------------

### Get Light State - Kasa IoT Bulb

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Queries the current state of the light. Note: It is recommended to use `light.state` for this purpose.

```python
async def get_light_state(self) -> dict[str, dict]:
        """Query the light state."""
        # TODO: add warning and refer to use light.state?
        return await self._query_helper(self.LIGHT_SERVICE, "get_light_state")
```

--------------------------------

### Manage Light Presets

Source: https://python-kasa.readthedocs.io/en/stable/guides/light.html

Operations for listing, viewing, and saving light presets.

```python
from kasa import Discover, Module, LightState

dev = await Discover.discover_single(
    "127.0.0.3",
    username="user@example.com",
    password="great_password"
)
await dev.update()
print(dev.alias)
```

```python
light_preset = dev.modules[Module.LightPreset]
light_preset.preset_list
```

```python
light_preset.preset
```

```python
len(light_preset.preset_states_list)
```

```python
light_preset.preset_states_list[0]
```

```python
dev.modules[Module.Light].state  # This is only needed to show the example working
await light_preset.set_preset("Light preset 1")
await dev.update()
light_preset.preset
dev.modules[Module.Light].state  # This is only needed to show the example working
```

```python
if light_preset.has_save_preset:
    new_preset_state = LightState(light_on=True, brightness=75, hue=0, saturation=100, color_temp=2700, transition=None)
    await light_preset.save_preset("Light preset 1", new_preset_state)
await dev.update()
light_preset.preset  # Saving updates the preset state for the preset, it does not set the preset
light_preset.preset_states_list[0]
```

```python
await dev.modules[Module.Light].set_brightness(75)
await dev.update()
light_preset.preset
```

--------------------------------

### Get SSL Context (KlapTransport)

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/transports/klaptransport.html

Asynchronously retrieves or creates an SSL context. If the context does not exist, it is created using `_create_ssl_context` and cached.

```python
    async def _get_ssl_context(self) -> ssl.SSLContext:
        if not self._ssl_context:
            loop = asyncio.get_running_loop()
            self._ssl_context = await loop.run_in_executor(
                None, self._create_ssl_context
            )
        return self._ssl_context
```

--------------------------------

### Get Plug by Index

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves a child device (plug) by its index. Useful for accessing plugs when their aliases are not known or when dealing with a fixed order.

```APIDOC
## get_plug_by_index

### Description
Return child device for the given index.

### Parameters
#### Path Parameters
- **index** (int) - Required - The zero-based index of the plug to retrieve.

### Response
#### Success Response (Device)
- Returns the child `Device` object at the specified index.

#### Error Response (KasaException)
- Raises `KasaException` if the index is out of bounds for the available child devices.
```

--------------------------------

### Child Camera Protocol Wrapper Initialization

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/protocols/smartcamprotocol.html

Initializes the _ChildCameraProtocolWrapper with a device ID and the base SmartProtocol instance. It also sets up the transport layer from the base protocol.

```python
def __init__(self, device_id: str, base_protocol: SmartProtocol) -> None:
        self._device_id = device_id
        self._protocol = base_protocol
        self._transport = base_protocol._transport
```

--------------------------------

### Get Child Device

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/device.html

Retrieves a child device by its alias or device ID. This is useful for multi-plug devices where you need to access individual plugs.

```APIDOC
## get_child_device

### Description
Return child device by its device_id or alias.

### Parameters
#### Path Parameters
- **name_or_id** (str) - Required - The alias or device ID of the child device to retrieve.

### Response
#### Success Response (Device | None)
- Returns the child `Device` object if found, otherwise returns `None`.
```

--------------------------------

### Access Bulb Configuration Presets

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/iot/iotbulb.html

Retrieves all available configuration presets for the bulb and displays them as dictionaries.

```python
[ preset.to_dict() for preset in bulb.presets }]
```

--------------------------------

### Attempt Login with Provided Parameters

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/transports/ssltransport.html

Attempts to log in to the device using the provided login parameters. It constructs a JSON-RPC login request, sends it, and handles the response. Upon successful login, it updates the session token and sets the transport state to ESTABLISHED.

```python
async def try_login(self, login_params: dict[str, Any]) -> None:
        """Try to login with supplied login_params."""
        login_request = {
            "method": "login",
            "params": login_params,
        }
        request = json_dumps(login_request)
        _LOGGER.debug("Going to send login request")

        resp_dict = await self.send_request(request)
        await self._handle_response_error_code(resp_dict, "Error logging in")

        login_token = resp_dict["result"]["token"]
        self._app_url = self._app_url.with_query(f"token={login_token}")
        self._state = TransportState.ESTABLISHED
        self._session_expire_at = (
            time.time() + ONE_DAY_SECONDS - SESSION_EXPIRE_BUFFER_SECONDS
        )

```

--------------------------------

### Get Monthly and Daily Usage Statistics

Source: https://python-kasa.readthedocs.io/en/stable/_sources/guides/energy.md.txt

Retrieve the total minutes a device has been on this month and today. Ensure the device has the 'usage' module available.

```python
dev = SmartPlug("127.0.0.1")
usage = dev.modules["usage"]
print(f"Minutes on this month: {usage.usage_this_month}")
print(f"Minutes on today: {usage.usage_today}")
```

--------------------------------

### Initialize Deprecated TP-Link Smart Home Protocol

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/protocols/iotprotocol.html

Creates a protocol object for TP-Link Smart Home devices using XOR transport. Requires either a host or an existing transport object. If no transport is provided, a new XorTransport is created with default settings or provided port and timeout.

```python
class _deprecated_TPLinkSmartHomeProtocol(IotProtocol):
    def __init__(
        self,
        host: str | None = None,
        *,
        port: int | None = None,
        timeout: int | None = None,
        transport: BaseTransport | None = None,
    ) -> None:
        """Create a protocol object."""
        if not host and not transport:
            raise KasaException("host or transport must be supplied")
        if not transport:
            config = DeviceConfig(
                host=host,  # type: ignore[arg-type]
                port_override=port,
                timeout=timeout or XorTransport.DEFAULT_TIMEOUT,
            )
            transport = XorTransport(config=config)
        super().__init__(transport=transport)
```

--------------------------------

### Join a Wi-Fi Network with a Device

Source: https://python-kasa.readthedocs.io/en/stable/_sources/cli.rst.txt

Connects a Kasa device to a specified Wi-Fi network. This command is used during the device provisioning process.

```bash
kasa --host 192.168.0.1 wifi join <network to join>
```

--------------------------------

### Access Module by Index

Source: https://python-kasa.readthedocs.io/en/stable/_modules/kasa/module.html

Access a module directly by its name if its existence is expected. This is a more direct way to get a module compared to using .get().

```python
>>> light_preset = dev.modules["LightPreset"]
>>> print(light_preset.preset_list)
['Not set', 'Light preset 1', 'Light preset 2', 'Light preset 3',
 'Light preset 4', 'Light preset 5', 'Light preset 6', 'Light preset 7']
```

--------------------------------

### Run Library Tests

Source: https://python-kasa.readthedocs.io/en/stable/_sources/contribute.md.txt

Execute the test suite for the python-kasa library using pytest. This command runs tests against the contributed example responses.

```bash
uv run pytest kasa
```
Tokens:
Raw