Interact with lights

Note

The library is fully async and methods that perform IO need to be run inside an async coroutine. Code examples assume you are following them inside asyncio REPL:

    $ python -m asyncio

Or the code is running inside an async function:

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

All of your code needs to run inside the same event loop so only call asyncio.run once.

The main entry point for the API is discover() and discover_single() which return Device objects. Most newer devices require your TP-Link cloud username and password, but this can be omitted for older devices.

Interact with a TPLink Light.

>>> 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)
Living Room Bulb

Lights, like any other supported devices, can be turned on and off:

>>> print(dev.is_on)
>>> await dev.turn_on()
>>> await dev.update()
>>> print(dev.is_on)
True

Get the light module to interact:

>>> light = dev.modules[Module.Light]

You can use the has_feature() method to check for supported features:

>>> light.has_feature("brightness")
True
>>> light.has_feature("hsv")
True
>>> light.has_feature("color_temp")
True

All known bulbs support changing the brightness:

>>> light.brightness
100
>>> await light.set_brightness(50)
>>> await dev.update()
>>> light.brightness
50

Bulbs supporting color temperature can be queried for the supported range:

>>> if color_temp_feature := light.get_feature("color_temp"):
>>>     print(f"{color_temp_feature.minimum_value}, {color_temp_feature.maximum_value}")
2500, 6500
>>> await light.set_color_temp(3000)
>>> await dev.update()
>>> light.color_temp
3000

Color bulbs can be adjusted by passing hue, saturation and value:

>>> await light.set_hsv(180, 100, 80)
>>> await dev.update()
>>> light.hsv
HSV(hue=180, saturation=100, value=80)

Presets

Interact with TPLink Light Presets.

>>> 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)
Living Room Bulb

Light presets are accessed via the LightPreset module. To list available presets

>>> 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']

To view the currently selected preset:

>>> light_preset.preset
Not set

To view the actual light state for the presets:

>>> len(light_preset.preset_states_list)
7

>>> light_preset.preset_states_list[0]
LightState(light_on=None, brightness=50, hue=0, saturation=100, color_temp=2700, transition=None)

To set a preset as active:

>>> dev.modules[Module.Light].state  # This is only needed to show the example working
LightState(light_on=True, brightness=100, hue=0, saturation=100, color_temp=2700, transition=None)
>>> await light_preset.set_preset("Light preset 1")
>>> await dev.update()
>>> light_preset.preset
Light preset 1
>>> dev.modules[Module.Light].state  # This is only needed to show the example working
LightState(light_on=True, brightness=50, hue=0, saturation=100, color_temp=2700, transition=None)

You can save a new preset state if the device supports it:

>>> 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
Not set
>>> light_preset.preset_states_list[0]
LightState(light_on=None, brightness=75, hue=0, saturation=100, color_temp=2700, transition=None)

If you manually set the light state to a preset state it will show that preset as active:

>>> await dev.modules[Module.Light].set_brightness(75)
>>> await dev.update()
>>> light_preset.preset
Light preset 1

Effects

Interact with a TPLink Light Effect.

>>> 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)
Living Room Bulb

Light effects are accessed via the LightPreset module. To list available presets

>>> light_effect = dev.modules[Module.LightEffect]
>>> light_effect.effect_list
['Off', 'Party', 'Relax']

To view the currently selected effect:

>>> light_effect.effect
Off

To activate a light effect:

>>> await light_effect.set_effect("Party")
>>> await dev.update()
>>> light_effect.effect
Party

If the device supports it you can set custom effects:

>>> if light_effect.has_custom_effects:
>>>     effect_list = { "brightness", 50 }
>>>     await light_effect.set_custom_effect(effect_list)
>>> light_effect.has_custom_effects  # The device in this examples does not support custom effects
False