# 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