Working with Flow

“Flow” is a special mode the bulb can be set to, which is basically a list of transitions to perform in succession. For example, a flow can be a constant cycling of colors from one to the next, until it is stopped, or it can be a quick blink of a certain color.

Usage

To create a flow, we need to instantiate a Flow object and add some transitions to it. The Flow object accepts three parameters, a count, which is the number of loops to perform (NOT the number of transitions!), an action, which is what to do at the end of the flow, and transitions, a list of the transitions themselves.

In the original protocol spec, the count argument specifies the number of transitions to perform. For example, if you have 10 transitions, and count is 5, the bulb will stop transitioning in the middle of your flow and exit. This is rather counter-intuitive, so the yeelight library changes this to mean “number of loops”. If you want to loop once, no matter how long your transition list, just specify 1. 0 means “loop forever”.

action can be Flow.actions.recover to return to the original state after this flow is stopped (either through the stop_flow method or just because the loop has stopped), Flow.actions.stay to just stay at the last state of the flow, or Flow.actions.off to turn off afterwards.

transitions is a list of transition instances. There are various transition classes available, which are detailed in the API reference. The bulbs seem to be limited to around nine transitions (any more will produce an “invalid command” error).

Let’s see a few examples.

Simple example

A simple example is to cycle the color temperature from 1700 to 6500 twice, with a one-second delay in-between (the examples assume we have a Bulb instance in bulb), and then return to the previous state:

from yeelight import *
transitions = [
    TemperatureTransition(1700, duration=1000),
    SleepTransition(duration=1000),
    TemperatureTransition(6500, duration=1000)
]

flow = Flow(
    count=2,
    action=Flow.actions.recover,
    transitions=transitions
)

bulb.start_flow(flow)

Infinite color cycle

We can cycle between colors forever like so:

from yeelight import *
transitions = [
    RGBTransition(255, 0, 255, duration=1000)
]

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

bulb.start_flow(flow)

To stop the flow (and return to the previous state, because of the default Flow.actions.recover action, you can use stop_flow:

bulb.stop_flow()

Quick pulse

If you want to connect the bulb to a notification system, you can fire off a quick pulse. For example, to pulse the bulb green twice when there is a WhatsApp message and return, we can do:

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)

Pretty easy!

Transition presets

The library includes some preset transitions in the yeelight.transitions module, to make it easy for you to start.

You can use the transitions simply by calling the preset:

from yeelight.transitions import *
from yeelight import Flow

flow = Flow(
    count=10,
    transitions=disco(),  # Call the transition preset to get the
                          # transitions you like.
)

bulb.start_flow(flow)

Remember that the transition presets are functions, so you need to call them. That’s because some of them take parameters.

Flow presets

The library includes some flow transitions in the yeelight.flows module, to make it easy for you to start.

You can use the flows simply by calling the preset:

from yeelight.flows import *

christmas().start_flow(flow)