DOCSEARCHbyAlgolia
Submit Docs

python-yeelight

repository·master·Indexed 42 days ago

https://github.com/skorokithakis/python-yeelight

A Python library for controlling YeeLight WiFi RGB LED bulbs over a local area network (LAN). It provides the Bulb class for managing power, brightness, and color, as well as Flow objects for creating sequences of transitions using HSVTransition, RGBTransition, and TemperatureTransition. Features include device discovery via discover_bulbs(), music mode for high-frequency updates, and support for various bulb types including White, Color, and WhiteTemp.

Tokens
3.6K
Snippets
16
Records
23
Agent score
52%

What's inside python-yeelight

  1. Use effects for smooth transitions

    master

    Effects control whether a bulb changes state immediately or gradually. There are two effect types:

    1. "sudden": Changes state immediately (ignores the duration parameter).
    2. "smooth": Changes state gradually over a specified time.

    Requirement: The effect and duration parameters must be passed as keyword arguments.

    from yeelight import Bulb

# Set default effect for the instance
bulb = Bulb("192.168.0.19", effect="smooth", duration=1000)

# Override effect for a specific call
bulb.turn_on(effect="sudden")

# Change the default effect for future calls
bulb.effect = "sudden"

  2. How Flow works in Yeelight

    master

    A Flow is a special mode that allows a bulb to perform a sequence of transitions in succession. You define a Flow by specifying how many times the sequence should loop, what the bulb should do once the flow completes, and the list of transitions to execute.

    Key Parameters of Flow

    • count: The number of loops to perform.
      • 1: Loop the sequence exactly once.
      • 0: Loop the sequence infinitely.
      • Note: This differs from the original protocol where count referred to individual transitions; in this library, it refers to full cycles of the transitions list.
    • action: Determines the bulb's state after the flow ends (either via completion or by calling stop_flow()):
      • Flow.actions.recover: Returns the bulb to its original state before the flow started.
      • Flow.actions.stay: Keeps the bulb at the last state reached in the flow.
      • Flow.actions.off: Turns the bulb off after the flow.
    • transitions: A list of transition instances (e.g., TemperatureTransition, RGBTransition).

    Important Limitation: Bulbs are generally limited to approximately nine transitions per flow. Providing more may result in an "invalid command" error.

    from yeelight import Flow, TemperatureTransition

transitions = [TemperatureTransition(1700, duration=1000)]
flow = Flow(count=2, action=Flow.actions.recover, transitions=transitions)
bulb.start_flow(flow)

  3. Manage lighting transitions with Flow objects

    master

    The yeelight.Flow class and its subclasses are used to create smooth transitions between lighting states. Instead of immediate changes, you can use these objects to define how a bulb moves from one state to another over time.

    Available transition types include:

    • yeelight.HSVTransition: Transitions based on Hue, Saturation, and Value.
    • yeelight.RGBTransition: Transitions based on Red, Green, and Blue color values.
    • yeelight.TemperatureTransition: Transitions based on color temperature.
    • yeelight.SleepTransition: Specialized transitions for sleep modes.

  6. Use transition presets with Flow

    master

    The yeelight.transitions module provides preset functions that return a list of transitions. Because these are functions (and some accept parameters), you must call them to pass the resulting list into the Flow object.

    from yeelight.transitions import *
from yeelight import Flow

flow = Flow(
    count=10,
    transitions=disco(),  # Call the preset function to get the transitions
)

bulb.start_flow(flow)

  7. Control a YeeLight bulb

    master

    To control a bulb, instantiate the Bulb class with the device's IP address. Once instantiated, you can call various methods to control power, brightness, color, and temperature.

    Important Notes:

    • Power State: By default, yeelight will refuse to make changes (like setting brightness) if the bulb is currently off. This will raise an AssertionError.
    • Auto-On: To ensure commands work even when the bulb is off, set auto_on=True during instantiation or set the bulb.auto_on property to True. This will automatically turn the bulb on before executing commands.
    • Rate Limiting: YeeLight connections are rate-limited to 60 commands per minute. Using auto_on=True increases the message count per command and may hit this limit faster.
    • Connection Errors: The library uses a single TCP connection for efficiency. If an error occurs, a socket.error might be raised and the command should be retried.
    from yeelight import Bulb

# Instantiate the bulb
bulb = Bulb("192.168.0.19")

# Basic power controls
bulb.turn_on()
bulb.turn_off()
bulb.toggle()

# Brightness and Color
bulb.set_brightness(50)          # Set brightness to 50%
bulb.set_rgb(255, 0, 0)         # Set RGB value
bulb.set_hsv(320, 100, 50)       # Set HSV (Hue, Saturation, Value)
bulb.set_hsv(320, 100)           # Set Hue and Saturation, keep brightness same
bulb.set_color_temp(4700)        # Set color temperature

# Persistence
bulb.set_default()               # Save current settings as default

  8. Bulb types and capabilities

    master

    The bulb_type property returns a BulbType enum indicating the hardware capabilities of the device. This is determined by inspecting the properties (specifically ct and rgb).

    BulbType values:

    • Unknown: Properties have not been fetched yet.
    • White: Monochrome bulbs.
    • Color: Color bulbs.
    • WhiteTemp: White bulbs with configurable color temperature.
    • WhiteTempMood: White bulbs with mood lighting (e.g., Galaxy LED ceiling light).

  9. How Music Mode works and how to use it

    master

    Music mode upgrades the connection to a reverse one where the bulb connects to the library. This removes rate-limiting and allows for high-frequency updates.

    Workflow:

    1. Call start_music(port=...). This starts a listening socket on your machine and tells the bulb to connect to it.
    2. The library switches the internal socket to the connection established by the bulb.
    3. To exit, call stop_music().

    Warning: If the bulb cannot connect to the host machine, it may cause library freezes.

    # Start music mode on a specific port
bulb.start_music(port=8888)

# ... perform high-frequency updates ...

bulb.stop_music()

  11. Create a quick pulse notification effect

    master

    You can use list comprehensions to generate a sequence of transitions for effects like a notification pulse. For example, cycling through different hues using HSVTransition can create a colorful flash.

    from yeelight import *

transitions = [HSVTransition(hue, 100, duration=500)
               for hue in range(0, 359, 40)]

flow = Flow(
    count=2,
    transitions=transitions
)

bulb.start_flow(flow)

  12. Create an infinite color cycle with Flow

    master

    To create a continuous loop of colors, instantiate a Flow with count=0. To stop an infinite flow and return the bulb to its previous state, call bulb.stop_flow(). Note that Flow.actions.recover is the default action, so the bulb will revert to its original state when stopped.

    from yeelight import *

transitions = [
    RGBTransition(255, 0, 255, duration=1000)
]

flow = Flow(
    count=0,  # Cycle forever.
    transitions=transitions
)

bulb.start_flow(flow)

# Later, to stop the flow and return to the previous state:
bulb.stop_flow()