yeelight package

This is the autogenerated API documentation. Use it as a reference to the public API of the project.

yeelight module

yeelight.discover_bulbs(timeout=2, interface=False)[source]

Discover all the bulbs in the local network.

Parameters:

timeout (int) – How many seconds to wait for replies. Discovery will always take exactly this long to run, as it can’t know when all the bulbs have finished responding.
interface (string) – The interface that should be used for multicast packets. Note: it has to have a valid IPv4 address. IPv6-only interfaces are not supported (at the moment). The default one will be used if this is not specified.

Returns:

A list of dictionaries, containing the ip, port and capabilities of each of the bulbs in the network.

class yeelight.Bulb(ip, port=55443, effect='smooth', duration=300, auto_on=False, power_mode=PowerMode.LAST, model=None)[source]

The main controller class of a physical YeeLight bulb.

Parameters:

ip (str) – The IP of the bulb.
port (int) – The port to connect to on the bulb.
effect (str) – The type of effect. Can be “smooth” or “sudden”.
duration (int) – The duration of the effect, in milliseconds. The minimum is 30. This is ignored for sudden effects.
auto_on (bool) – Whether to call ensure_on() to turn the bulb on automatically before each operation, if it is off. This renews the properties of the bulb before each message, costing you one extra message per command. Turn this off and do your own checking with get_properties() or run ensure_on() yourself if you’re worried about rate-limiting.
power_mode (yeelight.PowerMode) – The mode for the light set when powering on.
model (str) – The model name of the yeelight (e.g. “color”, “mono”, etc). The setting is used to enable model specific features (e.g. a particular color temperature range).

property bulb_type

The type of bulb we’re communicating with.

Returns a BulbType describing the bulb type.

When trying to access before properties are known, the bulb type is unknown.

Return type:: yeelight.BulbType
Returns:: The bulb’s type.

property capabilities

Capabilities obtained via SSDP Discovery.

They will be empty, unless updated via: get_capabilities.

Returns:: Capabilities dict returned by get_capabilities().

cron_add(event_type, value, **kwargs)[source]

Add an event to cron.

Example:

>>> bulb.cron_add(CronType.off, 10)

Parameters:: event_type (yeelight.CronType) – The type of event. Currently, only CronType.off.

cron_del(event_type, **kwargs)[source]

Remove an event from cron.

Parameters:: event_type (yeelight.CronType) – The type of event. Currently, only CronType.off.

cron_get(event_type, **kwargs)[source]

Retrieve an event from cron.

Parameters:: event_type (yeelight.CronType) – The type of event. Currently, only CronType.off.

dev_toggle(**kwargs)[source]: Toggle the main light and the ambient on or off.

ensure_on()[source]: Turn the bulb on if it is off.

get_capabilities(timeout=2)[source]

Get the bulb’s capabilities using the discovery protocol.

Parameters:: timeout (int) – How many seconds to wait for replies. Discovery will always take exactly this long to run, as it can’t know when all the bulbs have finished responding.
Returns:: Dictionary, containing the ip, port and capabilities. For example: { ‘id’: ‘0x0000000002eb9f61’, ‘model’: ‘ceiling3’, ‘fw_ver’: ‘43’, ‘support’: ‘get_prop set_default set_power toggle set_bright set_scene cron_add cron_get cron_del start_cf stop_cf set_ct_abx set_name set_adjust adjust_bright adjust_ct’, ‘power’: ‘on’, ‘bright’: ‘99’, ‘color_mode’: ‘2’, ‘ct’: ‘3802’, ‘rgb’: ‘0’, ‘hue’: ‘0’, ‘sat’: ‘0’, ‘name’: ‘’ }

get_model_specs(**kwargs)[source]: Return the specifications (e.g. color temperature min/max) of the bulb.

get_properties(requested_properties=['power', 'bright', 'ct', 'rgb', 'hue', 'sat', 'color_mode', 'flowing', 'delayoff', 'music_on', 'name', 'bg_power', 'bg_flowing', 'bg_ct', 'bg_bright', 'bg_hue', 'bg_sat', 'bg_rgb', 'nl_br', 'active_mode'], ssdp_fallback=False)[source]

Retrieve and return the properties of the bulb.

This method also updates last_properties when it is called.

The current_brightness property is calculated by the library (i.e. not returned by the bulb), and indicates the current brightness of the lamp, aware of night light mode. It is 0 if the lamp is off, and None if it is unknown.

Parameters:

requested_properties (list) – The list of properties to request from the bulb. By default, this does not include flow_params.
ssdp_fallback (bool) – Fallback to SSDP should get_prop fail, does not work in all network environment, default = False

Returns:

A dictionary of param: value items.

Return type:

dict

property last_properties

The last properties we’ve seen the bulb have.

This might potentially be out of date, as there’s no background listener for the bulb’s notifications. To update it, call get_properties.

listen(callback)[source]

Listen to state update notifications.

This function is blocking until a socket error occurred or being stopped by stop_listening. It should be run in a Thread or asyncio event loop.

The callback function should take one parameter, containing the new/updates properties. It will be called when last_properties is updated.

Parameters:: callback (callable) – A callback function to receive state update notification.

property model

Return declared model / model discovered via SSDP Discovery or None.

Returns:: Device model

property music_mode

Return whether the music mode is active.

Return type:: bool
Returns:: True if music mode is on, False otherwise.

property music_mode_state

Return whether the connection is music mode (aio only).

When using the sync module, this variable is ignored and not updated.

Return type:: bool
Returns:: True if music mode is connected, False otherwise.

send_command(method, params=None)[source]

Send a command to the bulb.

Parameters:

method (str) – The name of the method to send.
params (list) – The list of parameters for the method.

Raises:

BulbException – When the bulb indicates an error condition.

Returns:

The response from the bulb.

set_adjust(action, prop, **kwargs)[source]

Adjust a parameter.

I don’t know what this is good for. I don’t know how to use it, or why. I’m just including it here for completeness, and because it was easy, but it won’t get any particular love.

Parameters:

action (str) – The direction of adjustment. Can be “increase”, “decrease” or “circle”.
prop (str) – The property to adjust. Can be “bright” for brightness, “ct” for color temperature and “color” for color. The only action for “color” can be “circle”. Why? Who knows.

set_brightness(brightness, light_type=LightType.Main, **kwargs)[source]

Set the bulb’s brightness.

Parameters:

brightness (int) – The brightness value to set (1-100).
light_type (yeelight.LightType) – Light type to control.

set_capabilities(capabilities)[source]: Set capabilities from external discovery.

set_color_temp(degrees, light_type=LightType.Main, **kwargs)[source]

Set the bulb’s color temperature.

Parameters:

degrees (int) – The degrees to set the color temperature to (min/max are specified by the model’s capabilities, or 1700-6500).
light_type (yeelight.LightType) – Light type to control.

set_default(light_type=LightType.Main, **kwargs)[source]

Set the bulb’s current state as the default, which is what the bulb will be set to on power on.

If you get a “general error” setting this, yet the bulb reports as supporting set_default during discovery, disable “auto save settings” in the YeeLight app.

Parameters:: light_type (yeelight.LightType) – Light type to control.

set_hsv(hue, saturation, value=None, light_type=LightType.Main, **kwargs)[source]

Set the bulb’s HSV value.

Parameters:

hue (int) – The hue to set (0-359).
saturation (int) – The saturation to set (0-100).
value (int) – The value to set (0-100). If omitted, the bulb’s brightness will remain the same as before the change.
light_type (yeelight.LightType) – Light type to control.

set_name(name, **kwargs)[source]

Set the bulb’s name.

Parameters:: name (str) – The string you want to set as the bulb’s name.

set_power_mode(mode)[source]

Set the light power mode.

If the light is off it will be turned on.

Parameters:: mode (yeelight.PowerMode) – The mode to switch to.

set_rgb(red, green, blue, light_type=LightType.Main, **kwargs)[source]

Set the bulb’s RGB value.

Parameters:

red (int) – The red value to set (0-255).
green (int) – The green value to set (0-255).
blue (int) – The blue value to set (0-255).
light_type (yeelight.LightType) – Light type to control.

set_scene(scene_class, *args, light_type=LightType.Main, **kwargs)[source]

Set the light directly to the specified state.

If the light is off, it will first be turned on.

Parameters:: scene_class (yeelight.SceneClass) – The YeeLight scene class to use.

COLOR changes the light to the specified RGB color and brightness.

Arguments: * red (int) – The red value to set (0-255). * green (int) – The green value to set (0-255). * blue (int) – The blue value to set (0-255). * brightness (int) – The brightness value to set (1-100).
HSV changes the light to the specified HSV color and brightness.

Arguments: * hue (int) – The hue to set (0-359). * saturation (int) – The saturation to set (0-100). * brightness (int) – The brightness value to set (1-100).
CT changes the light to the specified color temperature.

Arguments: * degrees (int) – The degrees to set the color temperature to (min/max are specified by the model’s capabilities, or 1700-6500). * brightness (int) – The brightness value to set (1-100).
CF starts a color flow.

Arguments: * flow (yeelight.Flow) – The Flow instance to start.
AUTO_DELAY_OFF turns the light on to the specified brightness and sets a timer to turn it back off after the given number of minutes.

Arguments: * brightness (int) – The brightness value to set (1-100). * minutes (int) – The minutes to wait before automatically turning the light off.

Parameters:: light_type (yeelight.LightType) – Light type to control.

start_flow(flow, light_type=LightType.Main, **kwargs)[source]

Start a flow.

Parameters:: flow (yeelight.Flow) – The Flow instance to start.

start_music(port=0, ip=None)[source]

Start music mode.

Music mode essentially upgrades the existing connection to a reverse one (the bulb connects to the library), removing all limits and allowing you to send commands without being rate-limited.

Starting music mode will start a new listening socket, tell the bulb to connect to that, and then close the old connection. If the bulb cannot connect to the host machine for any reason, bad things will happen (such as library freezes).

Parameters:

port (int) – The port to listen on. If none is specified, a random port will be chosen.
ip (str) – The IP address of the host this library is running on. Will be discovered automatically if not provided.

stop_flow(light_type=LightType.Main, **kwargs)[source]

Stop a flow.

Parameters:: light_type (yeelight.LightType) – Light type to control.

stop_listening()[source]: Stop listening to notifications.

stop_music(**kwargs)[source]

Stop music mode.

Stopping music mode will close the previous connection. Calling stop_music more than once, or while not in music mode, is safe.

toggle(light_type=LightType.Main, **kwargs)[source]

Toggle the bulb on or off.

Parameters:: light_type (yeelight.LightType) – Light type to control.

turn_off(light_type=LightType.Main, **kwargs)[source]

Turn the bulb off.

Parameters:: light_type (yeelight.LightType) – Light type to control.

turn_on(light_type=LightType.Main, **kwargs)[source]

Turn the bulb on.

Parameters:: light_type (yeelight.LightType) – Light type to control.

class yeelight.BulbException[source]

A generic yeelight exception.

This exception is raised when bulb informs about errors, e.g., when trying to issue unsupported commands to the bulb.

Flow objects

class yeelight.Flow(count=0, action=Action.recover, transitions=None)[source]

A complete flow, consisting of one or multiple transitions.

Example: >>> transitions = [RGBTransition(255, 0, 0), SleepTransition(400)] >>> Flow(3, Flow.actions.recover, transitions)

Parameters:

count (int) – The number of times to run this flow (0 to run forever).
action (action) – The action to take after the flow stops. Can be Flow.actions.recover to go back to the state before the flow, Flow.actions.stay to stay at the last state, and Flow.actions.off to turn off.
transitions (list) – A list of FlowTransition instances that describe the flow transitions to perform.

actions: alias of Action

property as_start_flow_params

Return a YeeLight start_cf compatible params.

Return type:: list

property expression

Return a YeeLight-compatible expression that implements this flow.

Return type:: list

class yeelight.HSVTransition(hue, saturation, duration=300, brightness=100)[source]

An HSV transition.

Parameters:

hue (int) – The color hue to transition to (0-359).
saturation (int) – The color saturation to transition to (0-100).
duration (int) – The duration of the effect, in milliseconds. The minimum is 50.
brightness (int) – The brightness value to transition to (1-100).

class yeelight.RGBTransition(red, green, blue, duration=300, brightness=100)[source]

An RGB transition.

Parameters:

red (int) – The value of red (0-255).
green (int) – The value of green (0-255).
blue (int) – The value of blue (0-255).
duration (int) – The duration of the effect, in milliseconds. The minimum is 50.
brightness (int) – The brightness value to transition to (1-100).

class yeelight.TemperatureTransition(degrees, duration=300, brightness=100)[source]

A Color Temperature transition.

Parameters:

degrees (int) – The degrees to set the color temperature to (1700-6500).
duration (int) – The duration of the effect, in milliseconds. The minimum is 50.
brightness (int) – The brightness value to transition to (1-100).

class yeelight.SleepTransition(duration=300)[source]

A Sleep transition.

Parameters:: duration (int) – The duration of the effect, in milliseconds. The minimum is 50.

Transition presets

Pre-made transitions, for your strobing pleasure.

yeelight.transitions.alarm(duration=250)[source]

Red alarm; flashing bright red to dark red.

Parameters:: duration (int) – The duration between hi/lo brightness,in milliseconds.
Returns:: A list of transitions.
Return type:: list

yeelight.transitions.christmas(duration=250, brightness=100, sleep=3000)[source]

Color changes from red to green, like christmas lights.

Parameters:

duration (int) – The duration between red and green, in milliseconds.
brightness (int) – The brightness of the transition.
sleep (int) – The time to sleep between colors, in milliseconds.

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.disco(bpm=120)[source]

Color changes to the beat.

Parameters:: bpm (int) – The beats per minute to pulse to.
Returns:: A list of transitions.
Return type:: list

yeelight.transitions.lsd(duration=3000, brightness=100)[source]

Gradual changes to a pleasing, trippy palette.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.police(duration=300, brightness=100)[source]

Color changes from red to blue, like police lights.

Parameters:

duration (int) – The duration between red and blue, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.police2(duration=250, brightness=100)[source]

Color flashes red and then blue, like urgent police lights.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.pulse(red, green, blue, duration=250, brightness=100)[source]

Pulse a single color once (mainly to be used for notifications).

Parameters:

red (int) – The red color component to pulse (0-255).
green (int) – The green color component to pulse (0-255).
blue (int) – The blue color component to pulse (0-255).
duration (int) – The duration to pulse for, in milliseconds.
brightness (int) – The brightness to pulse at (1-100).

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.random_loop(duration=750, brightness=100, count=9)[source]

Color changes between count randomly chosen colors.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.
count (int) – The number of random chosen colors in transition.

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.rgb(duration=250, brightness=100, sleep=3000)[source]

Color changes from red to green to blue.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.
sleep (int) – The time to sleep between colors, in milliseconds

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.slowdown(duration=2000, brightness=100, count=8)[source]

Change between count random chosen colors with increasing transition time.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.
count (int) – The number of random chosen colors in transition.

Returns:

A list of transitions.

Return type:

list

yeelight.transitions.strobe()[source]

Rapid flashing on and off.

Returns:: A list of transitions.
Return type:: list

yeelight.transitions.strobe_color(brightness=100)[source]

Rapid flashing colors.

Parameters:: brightness (int) – The brightness of the transition.
Returns:: A list of transitions.
Return type:: list

yeelight.transitions.temp()[source]

Slowly-changing color temperature.

Returns:: A list of transitions.
Return type:: list

Flow presets

Built-in flows which the vendor ships in their app and pre-made transitions, for your strobing pleasure.

yeelight.flows.alarm(duration=250)[source]

Red alarm; flashing bright red to dark red.

Parameters:: duration (int) – The duration between hi/lo brightness,in milliseconds.
Returns:: An infinite Flow consisting of 2 transitions.
Return type:: Flow

yeelight.flows.candle_flicker()[source]

Simulate candle flicker.

Returns:: An infinite Flow consisting of 9 transitions.
Return type:: Flow

yeelight.flows.christmas(duration=250, brightness=100, sleep=3000)[source]

Color changes from red to green, like christmas lights.

Parameters:

duration (int) – The duration between red and green, in milliseconds.
brightness (int) – The brightness of the transition.
sleep (int) – The time to sleep between colors, in milliseconds.

Returns:

An infinite Flow consisting of 4 transitions.

Return type:

Flow

yeelight.flows.date_night(duration=500, brightness=50)[source]

Dim the lights to a cozy orange.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 1 transition.

Return type:

Flow

yeelight.flows.disco(bpm=120)[source]

Color changes to the beat.

Parameters:: bpm (int) – The beats per minute to pulse to.
Returns:: An infinite Flow consisting of 8 transitions.
Return type:: Flow

yeelight.flows.happy_birthday()[source]

Happy Birthday lights.

Returns:: An infinite Flow consisting of 3 transitions.
Return type:: Flow

yeelight.flows.home(duration=500, brightness=80)[source]

Simulate daylight.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 1 transition.

Return type:

Flow

yeelight.flows.lsd(duration=3000, brightness=100)[source]

Gradual changes to a pleasing, trippy palette.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 5 transitions.

Return type:

Flow

yeelight.flows.movie(duration=500, brightness=50)[source]

Dim the lights to a comfy purple.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 1 transition.

Return type:

Flow

yeelight.flows.night_mode(duration=500, brightness=1)[source]

Dim the lights to a dark red, pleasant for the eyes at night.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 1 transition.

Return type:

Flow

yeelight.flows.police(duration=300, brightness=100)[source]

Color changes from red to blue, like police lights.

Parameters:

duration (int) – The duration between red and blue, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 2 transitions.

Return type:

Flow

yeelight.flows.police2(duration=250, brightness=100)[source]

Color flashes red and then blue, like urgent police lights.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 8 transitions.

Return type:

Flow

yeelight.flows.pulse(red, green, blue, duration=250, brightness=100, count=1)[source]

Pulse a single color once (mainly to be used for notifications).

Parameters:

red (int) – The red color component to pulse (0-255).
green (int) – The green color component to pulse (0-255).
blue (int) – The blue color component to pulse (0-255).
duration (int) – The duration to pulse for, in milliseconds.
brightness (int) – The brightness to pulse at (1-100).
count (int) – The number times to pulse.

Returns:

A Flow consisting of 2 transitions, after which the bulb returns to its previous state.

Return type:

Flow

yeelight.flows.random_loop(duration=750, brightness=100, count=9)[source]

Color changes between count randomly chosen colors.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.
count (int) – The number of random chosen colors in transition.

Returns:

An infinite Flow consisting of up to 9 transitions.

Return type:

Flow

yeelight.flows.rgb(duration=250, brightness=100, sleep=3000)[source]

Color changes from red to green to blue.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.
sleep (int) – The time to sleep between colors, in milliseconds

Returns:

An infinite Flow consisting of 6 transitions.

Return type:

Flow

yeelight.flows.romance()[source]

Romantic lights.

Returns:: An infinite Flow consisting of 2 transitions.
Return type:: Flow

yeelight.flows.slowdown(duration=2000, brightness=100, count=8)[source]

Changes between count random chosen colors with increasing transition time.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.
count (int) – The number of random chosen colors in transition.

Returns:

An infinite Flow consisting of up to 8 transitions.

Return type:

Flow

yeelight.flows.strobe()[source]

Rapid flashing on and off.

Returns:: An infinite Flow consisting of 2 transitions.
Return type:: Flow

yeelight.flows.strobe_color(brightness=100)[source]

Rapid flashing colors.

Parameters:: brightness (int) – The brightness of the transition.
Returns:: An infinite Flow consisting of 6 transitions.
Return type:: Flow

yeelight.flows.sunrise()[source]

Simulate a natural and gentle sunrise in 15 minutes.

Returns:: A Flow consisting of 3 transitions, after which the bulb stays on.
Return type:: Flow

yeelight.flows.sunset()[source]

Simulate a natural sunset and offering relaxing dimming to help you sleep in 10 minutes.

Returns:: A Flow consisting of 3 transitions, after which the bulb turns off.
Return type:: Flow

yeelight.flows.tea_time(duration=500, brightness=50)[source]

Warm, cozy light.

Parameters:

duration (int) – The duration to fade to next color, in milliseconds.
brightness (int) – The brightness of the transition.

Returns:

An infinite Flow consisting of 1 transition.

Return type:

Flow

yeelight.flows.temp()[source]

Slowly-changing color temperature.

Returns:: An infinite Flow consisting of 2 transitions.
Return type:: Flow

Enums

class yeelight.BulbType(value)[source]

The bulb’s type.

This is either White (for monochrome bulbs), Color (for color bulbs), WhiteTemp (for white bulbs with configurable color temperature), WhiteTempMood for white bulbs with mood lighting (like the JIAOYUE 650 LED ceiling light), or Unknown if the properties have not been fetched yet.

Color = 1

Unknown = -1

White = 0

WhiteTemp = 2

WhiteTempMood = 3

class yeelight.CronType(value)[source]

The type of event in cron.

off = 0

class yeelight.LightType(value)[source]

Type of light to control.

Ambient = 1

Main = 0

class yeelight.PowerMode(value)[source]

Power mode of the light.

COLOR_FLOW = 4

HSV = 3

LAST = 0

MOONLIGHT = 5

NORMAL = 1

RGB = 2

class yeelight.SceneClass(value)[source]

The scene class to use.

The scene class (as named in Yeelight docs) specifies how the Bulb.set_scene method should act.

COLOR changes the light to the specified RGB color and brightness.
HSV changes the light to the specified HSV color and brightness.
CT changes the light to the specified color temperature.
CF starts a color flow.
AUTO_DELAY_OFF turns the light on and sets a timer to turn it back off after the given number of minutes.

AUTO_DELAY_OFF = 4

CF = 3

COLOR = 0

CT = 2

HSV = 1