Lights in esphomelib are implemented like fans. Both the hardware and the MQTT frontend access a combined LightState object and use only that to set state and receive state updates.

Example Usage

// Binary
App.make_binary_light("Desk Lamp", App.make_gpio_output(15));
// Brightness-only
App.make_monochromatic_light("Kitchen Lights", App.make_ledc_output(16));
// RGB, see output for information how to setup individual channels.
App.make_rgb_light("RGB Lights", red, green, blue);
App.make_rgbw_light("RGBW Lights", red, green, blue, white);

See Application::make_binary_light(), Application::make_monochromatic_light(), Application::make_rgb_light(), Application::make_rgbw_light().

API Reference


class light::LightColorValues

This class represents the color state for a light object.

All values in this class are represented using floats in the range from 0.0 (off) to 1.0 (on). Not all values have to be populated though, for example a simple monochromatic light only needs to access the state and brightness attributes.

PLease note all float values are automatically clamped.

state - Whether the light should be on/off. Represented as a float for transitions. brightness - The brightness of the light. red, green, blue - RGB values. white - The white value for RGBW lights.

Public Functions


Construct the LightColorValues with all attributes enabled, but state set to 0.0.

light::LightColorValuesLightColorValues(float state, float brightness, float red, float green, float blue, float white)
void light::LightColorValuesload_from_preferences(const std::string &friendly_name)

Load the color values from the non-volatile storage container preferences into the this object.

  • friendly_name: The friendly name of the component that’s calling this.

void light::LightColorValuessave_to_preferences(const std::string &friendly_name) const

Store these LightColorValues in the preferences object.

  • friendly_name: The friendly name of the component that’s calling this.

void light::LightColorValuesparse_json(const JsonObject &root)

Parse a color from the provided JsonObject.

See Home Assistant MQTT JSON light.

  • root: The json root object.

void light::LightColorValuesdump_json(JsonObject &root, const LightTraits &traits) const

Dump this color into a JsonObject.

Only dumps values if the corresponding traits are marked supported by traits.

  • root: The json root object.
  • traits: The traits object used for determining whether to include certain attributes.

void light::LightColorValuesnormalize_color(const LightTraits &traits)

Normalize the color (RGB/W) component.

Divides all color attributes by the maximum attribute, so effectively set at least one attribute to 1. For example: r=0.3, g=0.5, b=0.4 => r=0.6, g=1.0, b=0.8

  • traits: Used for determining which attributes to consider.

void light::LightColorValuesas_binary(bool *binary) const
void light::LightColorValuesas_brightness(float *brightness) const
void light::LightColorValuesas_rgb(float *red, float *green, float *blue) const
void light::LightColorValuesas_rgbw(float *red, float *green, float *blue, float *white) const
bool light::LightColorValuesoperator==(const LightColorValues &rhs) const

Compare this LightColorValues to rhs, return true iff all attributes match.

bool light::LightColorValuesoperator!=(const LightColorValues &rhs) const
float light::LightColorValuesget_state() const
void light::LightColorValuesset_state(float state)
float light::LightColorValuesget_brightness() const
void light::LightColorValuesset_brightness(float brightness)
float light::LightColorValuesget_red() const
void light::LightColorValuesset_red(float red)
float light::LightColorValuesget_green() const
void light::LightColorValuesset_green(float green)
float light::LightColorValuesget_blue() const
void light::LightColorValuesset_blue(float blue)
float light::LightColorValuesget_white() const
void light::LightColorValuesset_white(float white)

Public Static Functions

LightColorValues light::LightColorValueslerp(const LightColorValues &start, const LightColorValues &end, float completion)

Linearly interpolate between the values in start to the values in end.

This function linearly interpolates the color value by just interpolating every attribute independently.

The linearly interpolated LightColorValues.
  • start: The interpolation start values.
  • end: The interpolation end values.
  • completion: The completion value. 0 -> start, 1 -> end.

Protected Attributes

float light::LightColorValuesstate_

ON / OFF, float for transition.

float light::LightColorValuesbrightness_
float light::LightColorValuesred_
float light::LightColorValuesgreen_
float light::LightColorValuesblue_
float light::LightColorValueswhite_


class light::LightEffect

Base-class for all light effects.

In order to create a custom effect, first create a subclass implementing apply_effect and optionally initialize which both can use the provided LightState to set light colors and/or start transitions. Next, override get_name() and return the name of your effect. Lastly, you need to register your effect in light_effect_entries using the LightEffect::Entry struct.

Subclassed by light::FastLEDRainbowLightEffect, light::NoneLightEffect, light::RandomLightEffect

Public Functions

virtual std::string light::LightEffectget_name() const = 0

Return the name of this effect.

void light::LightEffectinitialize(LightState *state)

Initialize this LightEffect. Will be called once after creation.

void light::LightEffectstop(LightState *state)

Called when this effect is about to be removed.

virtual void light::LightEffectapply_effect(LightState *state) = 0

Apply this effect. Use the provided state for starting transitions, …

struct light::LightEffectEntry

Internal struct for light_effect_entries.

Public Members

std::string light::LightEffect::Entryname

The name of your effect.

LightTraits light::LightEffect::Entryrequirements

Which traits the light needs to have for this effect.

std::function<std::unique_ptr<LightEffect>)> light::LightEffect::Entry::constructor

A function creating a your light effect.

class light::NoneLightEffect

Default effect for all lights. Does nothing.

Inherits from light::LightEffect

Public Functions

std::string light::NoneLightEffectget_name() const

Return the name of this effect.

void light::NoneLightEffectapply_effect(LightState *state)

Apply this effect. Use the provided state for starting transitions, …

Public Static Functions

std::unique_ptr<LightEffect> light::NoneLightEffectcreate()
class light::RandomLightEffect

Random effect. Sets random colors every 10 seconds and slowly transitions between them.

Inherits from light::LightEffect

Public Functions

std::string light::RandomLightEffectget_name() const

Return the name of this effect.

void light::RandomLightEffectapply_effect(LightState *state)

Apply this effect. Use the provided state for starting transitions, …

Public Static Functions

std::unique_ptr<LightEffect> light::RandomLightEffectcreate()

Protected Attributes

uint32_t light::RandomLightEffectlast_color_change_
class light::FastLEDRainbowLightEffect

Rainbow effect for FastLED.

Inherits from light::LightEffect

Public Functions

std::string light::FastLEDRainbowLightEffectget_name() const

Return the name of this effect.

void light::FastLEDRainbowLightEffectapply_effect(light::LightState *state)

Apply this effect. Use the provided state for starting transitions, …

void light::FastLEDRainbowLightEffectinitialize(light::LightState *state)

Initialize this LightEffect. Will be called once after creation.

void light::FastLEDRainbowLightEffectstop(light::LightState *state)

Called when this effect is about to be removed.

Public Static Functions

std::unique_ptr<light::LightEffect> light::FastLEDRainbowLightEffectcreate()
std::vector<LightEffect::Entry> light::light_effect_entries = { LightEffect::Entry{ .name = "None", .requirements = LightTraits(), .constructor = NoneLightEffect::create }, LightEffect::Entry{ .name = "Random", .requirements = LightTraits(true, true, false), .constructor = RandomLightEffect::create }, #ifdef USE_FAST_LED_LIGHT LightEffect::Entry{ .name = "Rainbow Effect", .requirements = LightTraits(true, true, false, true), .constructor = FastLEDRainbowLightEffect::create }, #endif }


class light::LightOutput

Interface to write LightStates to hardware.

Subclassed by light::BinaryLightOutput, light::FastLEDLightOutputComponent, light::MonochromaticLightOutput, light::RGBLightOutput, light::RGBWLightOutput

Public Functions

virtual LightTraits light::LightOutputget_traits() = 0

Return the LightTraits of this LightOutput.

virtual void light::LightOutputwrite_state(LightState *state) = 0
class light::BinaryLightOutput

Inherits from light::LightOutput

Public Functions

light::BinaryLightOutputBinaryLightOutput(output::BinaryOutput *output)
LightTraits light::BinaryLightOutputget_traits()

Return the LightTraits of this LightOutput.

void light::BinaryLightOutputwrite_state(LightState *state)

Protected Attributes

output::BinaryOutput *light::BinaryLightOutputoutput_
class light::MonochromaticLightOutput

Inherits from light::LightOutput

Public Functions

light::MonochromaticLightOutputMonochromaticLightOutput(output::FloatOutput *output)
LightTraits light::MonochromaticLightOutputget_traits()

Return the LightTraits of this LightOutput.

void light::MonochromaticLightOutputwrite_state(LightState *state)

Protected Attributes

output::FloatOutput *light::MonochromaticLightOutputoutput_
class light::RGBLightOutput

Inherits from light::LightOutput

Public Functions

light::RGBLightOutputRGBLightOutput(output::FloatOutput *red, output::FloatOutput *green, output::FloatOutput *blue)
LightTraits light::RGBLightOutputget_traits()

Return the LightTraits of this LightOutput.

void light::RGBLightOutputwrite_state(LightState *state)

Protected Attributes

output::FloatOutput *light::RGBLightOutputred_
output::FloatOutput *light::RGBLightOutputgreen_
output::FloatOutput *light::RGBLightOutputblue_
class light::RGBWLightOutput

Inherits from light::LightOutput

Public Functions

light::RGBWLightOutputRGBWLightOutput(output::FloatOutput *red, output::FloatOutput *green, output::FloatOutput *blue, output::FloatOutput *white)
LightTraits light::RGBWLightOutputget_traits()

Return the LightTraits of this LightOutput.

void light::RGBWLightOutputwrite_state(LightState *state)

Protected Attributes

output::FloatOutput *light::RGBWLightOutputred_
output::FloatOutput *light::RGBWLightOutputgreen_
output::FloatOutput *light::RGBWLightOutputblue_
output::FloatOutput *light::RGBWLightOutputwhite_


class light::LightState

This class represents the communication layer between the front-end MQTT layer and the hardware output layer.

Inherits from Nameable, Component

Public Functions

light::LightStateLightState(const std::string &name, LightOutput *output)

Construct this LightState using the provided traits and name.

void light::LightStatestart_effect(const std::string &name)

Start an effect by name.

Uses light_effect_entries in light_effect.h for finding the correct effect.

  • name: The name of the effect, case insensitive.

void light::LightStatestop_effect()

Stop the current effect (if one is active).

void light::LightStatestart_transition(const LightColorValues &target, uint32_t length)

Start a linear transition to the provided target values for a specific amount of time.

If this light doesn’t support transition (see set_traits()), sets the target values immediately.

  • target: The target color.
  • length: The transition length in ms.

void light::LightStatestart_flash(const LightColorValues &target, uint32_t length)

Start a flash for the specified amount of time.

Resets to the values that were active when the flash was started after length ms.

  • target: The target flash color.
  • length: The flash length in ms.

void light::LightStateset_immediately(const LightColorValues &target)

Set the color values immediately.

void light::LightStateset_immediately_without_sending(const LightColorValues &target)

Set the color values immediately without sending the new state.

void light::LightStatestart_default_transition(const LightColorValues &target)
void light::LightStatecurrent_values_as_binary(bool *binary)
void light::LightStatecurrent_values_as_brightness(float *brightness)
void light::LightStatecurrent_values_as_rgb(float *red, float *green, float *blue)
void light::LightStatecurrent_values_as_rgbw(float *red, float *green, float *blue, float *white)
LightTraits light::LightStateget_traits()
template <typename T>
ToggleAction<T> *light::LightStatemake_toggle_action()
template <typename T>
TurnOffAction<T> *light::LightStatemake_turn_off_action()
template <typename T>
TurnOnAction<T> *light::LightStatemake_turn_on_action()
void light::LightStatesetup()

Load state from preferences.

void light::LightStateloop()

This method will be called repeatedly.

Analogous to Arduino’s loop(). setup() is guaranteed to be called before this. Defaults to doing nothing.

float light::LightStateget_setup_priority() const

Shortly after HARDWARE.

LightColorValues light::LightStateget_current_values()

Applies the effect, transformer and then returns the current values.

LightColorValues light::LightStateget_remote_values()

Return the values that should be reported to the remote.

void light::LightStatesend_values()

Causes the callback defined by add_send_callback() to trigger.

LightOutput *light::LightStateget_output() const
void light::LightStateset_transformer(std::unique_ptr<LightTransformer> transformer)

Manually set a transformer, it’s recommended to use start_flash and start_transition instead.

const LightColorValues &light::LightStateget_current_values_lazy()

Lazily get the last current values. Returns the values last returned by get_current_values().

std::string light::LightStateget_effect_name()

Return the name of the current effect, or if no effect is active “None”.

void light::LightStateadd_new_remote_values_callback(light_send_callback_t &&send_callback)

This lets front-end components subscribe to light change events.

This is different from add_new_current_values_callback in that it only sends events for start and end values. For example, with transitions it will only send a single callback whereas the callback passed in add_new_current_values_callback will be called every loop() cycle when a transition is active

Note the callback should get the output values through get_remote_values().

  • send_callback: The callback.

bool light::LightStatesupports_effects()

Return whether the light has any effects that meet the trait requirements.

void light::LightStateparse_json(const JsonObject &root)

Parse and apply the provided JSON payload.

void light::LightStatedump_json(JsonBuffer &buffer, JsonObject &root)

Dump the state of this light as JSON.

uint32_t light::LightStateget_default_transition_length() const

Defaults to 1 second (1000 ms).

void light::LightStateset_default_transition_length(uint32_t default_transition_length)

Set the default transition length, i.e. the transition length when no transition is provided.

float light::LightStateget_gamma_correct() const
void light::LightStateset_gamma_correct(float gamma_correct)

Set the gamma correction factor.

Protected Attributes

uint32_t light::LightStatedefault_transition_length_ = {1000}
std::unique_ptr<LightEffect> light::LightStateeffect_ = {nullptr}
std::unique_ptr<LightTransformer> light::LightStatetransformer_ = {nullptr}
LightColorValues light::LightStatevalues_ = {}
CallbackManager<void()> light::LightStateremote_values_callback_ = {}
LightOutput *light::LightStateoutput_

Store the output to allow effects to have more access.

bool light::LightStatenext_write_ = {true}
float light::LightStategamma_correct_ = {2.8f}


class light::LightTraits

This class is used to represent the capabilities of a light.

Public Functions

light::LightTraitsLightTraits(bool brightness, bool rgb, bool rgb_white_value, bool fast_led = false)
bool light::LightTraitssupports_traits(const LightTraits &rhs) const
bool light::LightTraitshas_brightness() const
bool light::LightTraitshas_rgb() const
bool light::LightTraitshas_rgb_white_value() const
bool light::LightTraitshas_fast_led() const

Hack to allow FastLED light effects without dynamic_cast.

Protected Attributes

bool light::LightTraitsbrightness_ = {false}
bool light::LightTraitsrgb_ = {false}
bool light::LightTraitsrgb_white_value_ = {false}
bool light::LightTraitsfast_led_ = {false}


class light::LightTransformer

Base-class for all light color transformers, such as transitions or flashes.

Subclassed by light::LightFlashTransformer, light::LightTransitionTransformer

Public Functions

light::LightTransformerLightTransformer(uint32_t start_time, uint32_t length, const LightColorValues &start_values, const LightColorValues &target_values)
bool light::LightTransformeris_finished()

Whether this transformation is finished.

virtual bool light::LightTransformeris_continuous() = 0

Whether the output needs to be written in every loop cycle.

virtual LightColorValues light::LightTransformerget_values() = 0

This will be called to get the current values for output.

LightColorValues light::LightTransformerget_remote_values()

The values that should be reported to the front-end.

LightColorValues light::LightTransformerget_end_values()

The values that should be set after this transformation is complete.

Protected Functions

float light::LightTransformerget_progress()

Get the completion of this transformer, 0 to 1.

const LightColorValues &light::LightTransformerget_start_values() const
const LightColorValues &light::LightTransformerget_target_values() const

Protected Attributes

uint32_t light::LightTransformerstart_time_
uint32_t light::LightTransformerlength_
LightColorValues light::LightTransformerstart_values_
LightColorValues light::LightTransformertarget_values_
class light::LightTransitionTransformer

Inherits from light::LightTransformer

Public Functions

light::LightTransitionTransformerLightTransitionTransformer(uint32_t start_time, uint32_t length, const LightColorValues &start_values, const LightColorValues &target_values)
LightColorValues light::LightTransitionTransformerget_values()

This will be called to get the current values for output.

bool light::LightTransitionTransformeris_continuous()

Whether the output needs to be written in every loop cycle.

class light::LightFlashTransformer

Inherits from light::LightTransformer

Public Functions

light::LightFlashTransformerLightFlashTransformer(uint32_t start_time, uint32_t length, const LightColorValues &start_values, const LightColorValues &target_values)
LightColorValues light::LightFlashTransformerget_values()

This will be called to get the current values for output.

LightColorValues light::LightFlashTransformerget_end_values()

The values that should be set after this transformation is complete.

bool light::LightFlashTransformeris_continuous()

Whether the output needs to be written in every loop cycle.


class light::MQTTJSONLightComponent

Inherits from mqtt::MQTTComponent

Public Functions

light::MQTTJSONLightComponentMQTTJSONLightComponent(LightState *state)
LightState *light::MQTTJSONLightComponentget_state() const
void light::MQTTJSONLightComponentsetup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing noting.

void light::MQTTJSONLightComponentsend_discovery(JsonBuffer &buffer, JsonObject &root, mqtt::SendDiscoveryConfig &config)

Send discovery info the Home Assistant, override this.

void light::MQTTJSONLightComponentsend_initial_state()
bool light::MQTTJSONLightComponentis_internal()

Protected Functions

std::string light::MQTTJSONLightComponentfriendly_name() const

Get the friendly name of this MQTT component.

std::string light::MQTTJSONLightComponentcomponent_type() const

Override this method to return the component type (e.g. “light”, “sensor”, …)

void light::MQTTJSONLightComponentpublish_state()

Protected Attributes

LightState *light::MQTTJSONLightComponentstate_