Light

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

LightColorValues

class 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

LightColorValues()

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

LightColorValues(float state, float brightness, float red, float green, float blue, float white, float color_temperature = 1.0f)
LightColorValues(bool state, float brightness, float red, float green, float blue, float white, float color_temperature = 1.0f)
void dump_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.

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

void normalize_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

Parameters
  • traits: Used for determining which attributes to consider.

void as_binary(bool *binary) const
void as_brightness(float *brightness) const
void as_rgb(float *red, float *green, float *blue) const
void as_rgbw(float *red, float *green, float *blue, float *white) const
void as_rgbww(float color_temperature_cw, float color_temperature_ww, float *red, float *green, float *blue, float *cold_white, float *warm_white) const
void as_cwww(float color_temperature_cw, float color_temperature_ww, float *cold_white, float *warm_white) const
bool operator==(const LightColorValues &rhs) const

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

bool operator!=(const LightColorValues &rhs) const
float get_state() const
void set_state(float state)
void set_state(bool state)
float get_brightness() const
void set_brightness(float brightness)
float get_red() const
void set_red(float red)
float get_green() const
void set_green(float green)
float get_blue() const
void set_blue(float blue)
float get_white() const
void set_white(float white)
float get_color_temperature() const
void set_color_temperature(float color_temperature)

Public Static Functions

LightColorValues from_binary(bool state)
LightColorValues from_monochromatic(float brightness)
LightColorValues from_rgb(float r, float g, float b)
LightColorValues from_rgbw(float r, float g, float b, float w)
LightColorValues lerp(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.

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

Protected Attributes

float state_

ON / OFF, float for transition.

float brightness_
float red_
float green_
float blue_
float white_
float color_temperature_

Color Temperature in Mired.

LightEffect

class LightEffect

Subclassed by light::BaseFastLEDLightEffect, light::FlickerLightEffect, light::LambdaLightEffect, light::RandomLightEffect, light::StrobeLightEffect

Public Functions

LightEffect(const std::string &name)
void start()

Initialize this LightEffect. Will be called once after creation.

void start_()
void stop()

Called when this effect is about to be removed.

virtual void apply() = 0

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

const std::string &get_name()
void init()

Internal method called by the LightState when this light effect is registered in it.

void init_(LightState *state)

Protected Attributes

LightState *state_ = {nullptr}
std::string name_
class RandomLightEffect : public light::LightEffect

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

Public Functions

RandomLightEffect(const std::string &name)
void apply()

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

void set_transition_length(uint32_t transition_length)
void set_update_interval(uint32_t update_interval)

Protected Attributes

uint32_t last_color_change_ = {0}
uint32_t transition_length_ = {7500}
uint32_t update_interval_ = {10000}
struct StrobeLightEffectColor

Public Members

LightColorValues color
uint32_t duration
class StrobeLightEffect : public light::LightEffect

Public Functions

StrobeLightEffect(const std::string &name)
void apply()

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

void set_colors(const std::vector<StrobeLightEffectColor> &colors)

Protected Attributes

std::vector<StrobeLightEffectColor> colors_
uint32_t last_switch_ = {0}
size_t at_color_ = {0}
class FlickerLightEffect : public light::LightEffect

Public Functions

FlickerLightEffect(const std::string &name)
void apply()

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

void set_alpha(float alpha)
void set_intensity(float intensity)

Protected Attributes

float intensity_ = {0.015f}
float alpha_ = {0.95f}
class LambdaLightEffect : public light::LightEffect

Public Functions

LambdaLightEffect(const std::string &name, const std::function<void()> &fuint32_t update_interval, )
void apply()

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

Protected Attributes

std::function<void()> f_
uint32_t update_interval_
uint32_t last_run_ = {0}
class BaseFastLEDLightEffect : public light::LightEffect

Subclassed by light::FastLEDColorWipeEffect, light::FastLEDFireworksEffect, light::FastLEDFlickerEffect, light::FastLEDLambdaLightEffect, light::FastLEDRainbowLightEffect, light::FastLEDRandomTwinkleEffect, light::FastLEDScanEffect, light::FastLEDTwinkleEffect

Public Functions

BaseFastLEDLightEffect(const std::string &name)
void start_()
void stop()

Called when this effect is about to be removed.

virtual void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb) = 0
void apply()

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

Protected Functions

FastLEDLightOutputComponent *get_fastled_output_() const
class FastLEDLambdaLightEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDLambdaLightEffect(const std::string &name, const std::function<void(FastLEDLightOutputComponent&)> &f, uint32_t update_interval, )
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)

Protected Attributes

std::function<void(FastLEDLightOutputComponent&)> f_
uint32_t update_interval_
uint32_t last_run_ = {0}
class FastLEDRainbowLightEffect : public light::BaseFastLEDLightEffect

Rainbow effect for FastLED.

Public Functions

FastLEDRainbowLightEffect(const std::string &name)
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)
void set_speed(uint32_t speed)
void set_width(uint32_t width)

Protected Attributes

uint32_t speed_ = {10}
uint16_t width_ = {50}
struct FastLEDColorWipeEffectColor

Public Members

float r
float g
float b
bool random
size_t num_leds
class FastLEDColorWipeEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDColorWipeEffect(const std::string &name)
void set_colors(const std::vector<FastLEDColorWipeEffectColor> &colors)
void set_add_led_interval(uint32_t add_led_interval)
void set_reverse(bool reverse)
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)

Protected Attributes

std::vector<FastLEDColorWipeEffectColor> colors_
size_t at_color_ = {0}
uint32_t last_add_ = {0}
uint32_t add_led_interval_ = {100}
size_t leds_added_ = {0}
bool reverse_ = {false}
class FastLEDScanEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDScanEffect(const std::string &name)
void set_move_interval(uint32_t move_interval)
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)

Protected Attributes

uint32_t move_interval_ = {100}
uint32_t last_move_ = {0}
int at_led_ = {0}
bool direction_ = {true}
class FastLEDTwinkleEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDTwinkleEffect(const std::string &name)
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)
void set_twinkle_probability(float twinkle_probability)
void set_progress_interval(uint32_t progress_interval)

Protected Attributes

float twinkle_probability_ = {0.05f}
uint32_t progress_interval_ = {4}
uint32_t last_progress_ = {0}
class FastLEDRandomTwinkleEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDRandomTwinkleEffect(const std::string &name)
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)
void set_twinkle_probability(float twinkle_probability)
void set_progress_interval(uint32_t progress_interval)

Protected Attributes

float twinkle_probability_ = {0.05f}
uint32_t progress_interval_ = {32}
uint32_t last_progress_ = {0}
class FastLEDFireworksEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDFireworksEffect(const std::string &name)
void init()

Internal method called by the LightState when this light effect is registered in it.

void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)
void set_update_interval(uint32_t update_interval)
void set_spark_probability(float spark_probability)
void set_use_random_color(bool random_color)
void set_fade_out_rate(uint8_t fade_out_rate)

Protected Attributes

uint8_t fade_out_rate_ = {120}
uint32_t update_interval_ = {32}
uint32_t last_update_ = {0}
float spark_probability_ = {0.10f}
bool use_random_color_ = {false}
class FastLEDFlickerEffect : public light::BaseFastLEDLightEffect

Public Functions

FastLEDFlickerEffect(const std::string &name)
void apply(FastLEDLightOutputComponent &fastled, uint8_t brightness, CRGB rgb)
void set_update_interval(uint32_t update_interval)
void set_intensity(float intensity)

Protected Attributes

uint32_t update_interval_ = {16}
uint32_t last_update_ = {0}
float intensity_ = {0.05f}

LightOutput

class LightOutput

Interface to write LightStates to hardware.

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

Public Functions

virtual LightTraits get_traits() = 0

Return the LightTraits of this LightOutput.

virtual void write_state(LightState *state) = 0
class BinaryLightOutput : public light::LightOutput

Public Functions

BinaryLightOutput(output::BinaryOutput *output)
LightTraits get_traits()

Return the LightTraits of this LightOutput.

void write_state(LightState *state)

Protected Attributes

output::BinaryOutput *output_
class MonochromaticLightOutput : public light::LightOutput

Public Functions

MonochromaticLightOutput(output::FloatOutput *output)
LightTraits get_traits()

Return the LightTraits of this LightOutput.

void write_state(LightState *state)

Protected Attributes

output::FloatOutput *output_
class CWWWLightOutput : public light::LightOutput

Public Functions

CWWWLightOutput(float cold_white_mireds, float warm_white_mireds, output::FloatOutput *cold_white, output::FloatOutput *warm_white)
LightTraits get_traits()

Return the LightTraits of this LightOutput.

void write_state(LightState *state)

Protected Attributes

float cold_white_mireds_
float warm_white_mireds_
output::FloatOutput *cold_white_
output::FloatOutput *warm_white_
class RGBLightOutput : public light::LightOutput

Public Functions

RGBLightOutput(output::FloatOutput *red, output::FloatOutput *green, output::FloatOutput *blue)
LightTraits get_traits()

Return the LightTraits of this LightOutput.

void write_state(LightState *state)

Protected Attributes

output::FloatOutput *red_
output::FloatOutput *green_
output::FloatOutput *blue_
class RGBWLightOutput : public light::LightOutput

Public Functions

RGBWLightOutput(output::FloatOutput *red, output::FloatOutput *green, output::FloatOutput *blue, output::FloatOutput *white)
LightTraits get_traits()

Return the LightTraits of this LightOutput.

void write_state(LightState *state)

Protected Attributes

output::FloatOutput *red_
output::FloatOutput *green_
output::FloatOutput *blue_
output::FloatOutput *white_
class RGBWWLightOutput : public light::LightOutput

Public Functions

RGBWWLightOutput(float cold_white_mireds, float warm_white_mireds, output::FloatOutput *red, output::FloatOutput *green, output::FloatOutput *blue, output::FloatOutput *cold_white, output::FloatOutput *warm_white)
LightTraits get_traits()

Return the LightTraits of this LightOutput.

void write_state(LightState *state)

Protected Attributes

float cold_white_mireds_
float warm_white_mireds_
output::FloatOutput *red_
output::FloatOutput *green_
output::FloatOutput *blue_
output::FloatOutput *cold_white_
output::FloatOutput *warm_white_

LightState

class LightState : public Nameable, public Component

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

Public Functions

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

Construct this LightState using the provided traits and name.

void start_effect(uint32_t effect_index)

Start an effect with the given index.

void stop_effect()

Stop the current effect (if one is active).

void start_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.

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

void start_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.

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

void set_immediately(const LightColorValues &target)

Set the color values immediately.

void set_immediately_without_sending(const LightColorValues &target)

Set the color values immediately without sending the new state.

void current_values_as_binary(bool *binary)
void current_values_as_brightness(float *brightness)
void current_values_as_rgb(float *red, float *green, float *blue)
void current_values_as_rgbw(float *red, float *green, float *blue, float *white)
void current_values_as_rgbww(float color_temperature_cw, float color_temperature_ww, float *red, float *green, float *blue, float *cold_white, float *warm_white)
void current_values_as_cwww(float color_temperature_cw, float color_temperature_ww, float *cold_white, float *warm_white)
LightTraits get_traits()
template <typename T>
ToggleAction<T> *make_toggle_action()
template <typename T>
TurnOffAction<T> *make_turn_off_action()
template <typename T>
TurnOnAction<T> *make_turn_on_action()
LightState::StateCall turn_on()
LightState::StateCall turn_off()
LightState::StateCall toggle()
LightState::StateCall make_call()
void setup()

Load state from preferences.

void loop()

This method will be called repeatedly.

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

float get_setup_priority() const

Shortly after HARDWARE.

LightColorValues get_current_values()

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

LightColorValues get_remote_values()

Return the values that should be reported to the remote.

void send_values()

Causes the callback defined by add_send_callback() to trigger.

LightOutput *get_output() const
void set_transformer(std::unique_ptr<LightTransformer> transformer)

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

const LightColorValues &get_current_values_lazy()

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

std::string get_effect_name()

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

void add_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().

Parameters
  • send_callback: The callback.

bool supports_effects()

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

void dump_json(JsonObject &root)

Dump the state of this light as JSON.

uint32_t get_default_transition_length() const

Defaults to 1 second (1000 ms).

void set_default_transition_length(uint32_t default_transition_length)

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

float get_gamma_correct() const
void set_gamma_correct(float gamma_correct)

Set the gamma correction factor.

const std::vector<LightEffect *> &get_effects() const
void add_effects(std::vector<LightEffect *> effects)

Protected Attributes

ESPPreferenceObject rtc_
uint32_t default_transition_length_ = {1000}
LightEffect *active_effect_ = {nullptr}
optional<uint32_t> active_effect_index_ = {}
std::unique_ptr<LightTransformer> transformer_ = {nullptr}
LightColorValues values_ = {}
LightColorValues remote_values_ = {}
CallbackManager<void()> remote_values_callback_ = {}
LightOutput *output_

Store the output to allow effects to have more access.

bool next_write_ = {true}
float gamma_correct_ = {2.8f}
std::vector<LightEffect *> effects_
class StateCall

Public Functions

StateCall(LightState *state)
LightState::StateCall &set_state(bool state)
LightState::StateCall &set_transition_length(uint32_t transition_length)
LightState::StateCall &set_flash_length(uint32_t flash_length)
LightState::StateCall &set_brightness(float brightness)
LightState::StateCall &set_rgb(float red, float green, float blue)
LightState::StateCall &set_rgbw(float red, float green, float blue, float white)
LightState::StateCall &set_red(float red)
LightState::StateCall &set_green(float green)
LightState::StateCall &set_blue(float blue)
LightState::StateCall &set_white(float white)
LightState::StateCall &set_color_temperature(float color_temperature)
LightState::StateCall &set_effect(const std::string &effect)
LightState::StateCall &set_effect(uint32_t effect_index)
LightState::StateCall &parse_color_json(JsonObject &root)
LightState::StateCall &parse_json(JsonObject &root)
void perform() const

Protected Attributes

LightState *state_
optional<bool> binary_state_
optional<float> brightness_
optional<float> red_
optional<float> green_
optional<float> blue_
optional<float> white_
optional<float> color_temperature_
optional<uint32_t> transition_length_
optional<uint32_t> flash_length_
optional<uint32_t> effect_

LightTraits

class LightTraits

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

Public Functions

LightTraits()
LightTraits(bool brightness, bool rgb, bool rgb_white_value, bool fast_led = false, bool color_temperature = false)
bool has_brightness() const
bool has_rgb() const
bool has_rgb_white_value() const
bool has_color_temperature() const
bool has_fast_led() const

Hack to allow FastLED light effects without dynamic_cast.

Protected Attributes

bool brightness_ = {false}
bool rgb_ = {false}
bool rgb_white_value_ = {false}
bool color_temperature_ = {false}
bool fast_led_ = {false}

LightTransformer

class LightTransformer

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

Subclassed by light::LightFlashTransformer, light::LightTransitionTransformer

Public Functions

LightTransformer(uint32_t start_time, uint32_t length, const LightColorValues &start_values, const LightColorValues &target_values)
LightTransformer()
bool is_finished()

Whether this transformation is finished.

virtual bool is_continuous() = 0

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

virtual LightColorValues get_values() = 0

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

LightColorValues get_remote_values()

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

LightColorValues get_end_values()

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

Protected Functions

float get_progress()

Get the completion of this transformer, 0 to 1.

const LightColorValues &get_start_values() const
const LightColorValues &get_target_values() const

Protected Attributes

uint32_t start_time_
uint32_t length_
LightColorValues start_values_
LightColorValues target_values_
class LightTransitionTransformer : public light::LightTransformer

Public Functions

LightTransitionTransformer(uint32_t start_time, uint32_t length, const LightColorValues &start_values, const LightColorValues &target_values)
LightColorValues get_values()

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

bool is_continuous()

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

class LightFlashTransformer : public light::LightTransformer

Public Functions

LightFlashTransformer(uint32_t start_time, uint32_t length, const LightColorValues &start_values, const LightColorValues &target_values)
LightColorValues get_values()

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

LightColorValues get_end_values()

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

bool is_continuous()

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

MQTTJSONLightComponent

class MQTTJSONLightComponent : public mqtt::MQTTComponent

Public Functions

MQTTJSONLightComponent(LightState *state)
LightState *get_state() const
void setup()

Where the component’s initialization should happen.

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

void dump_config()
void send_discovery(JsonObject &root, mqtt::SendDiscoveryConfig &config)

Send discovery info the Home Assistant, override this.

void send_initial_state()
bool is_internal()

Protected Functions

std::string friendly_name() const

Get the friendly name of this MQTT component.

std::string component_type() const

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

void publish_state()

Protected Attributes

LightState *state_
template <typename T>
class TurnOffAction : public Action<T>

Public Functions

TurnOffAction(LightState *state)
void set_transition_length(std::function<uint32_t(T)> transition_length)
void set_transition_length(uint32_t transition_length)
void play(T x)

Protected Attributes

LightState *state_
TemplatableValue<uint32_t, T> transition_length_
template <typename T>
class TurnOnAction : public Action<T>

Public Functions

TurnOnAction(LightState *state)
void set_transition_length(std::function<uint32_t(T)> &&transition_length)
void set_transition_length(uint32_t transition_length)
void set_flash_length(std::function<uint32_t(T)> &&flash_length)
void set_flash_length(uint32_t flash_length)
void set_brightness(std::function<float(T)> &&brightness)
void set_brightness(float brightness)
void set_red(std::function<float(T)> &&red)
void set_red(float red)
void set_green(std::function<float(T)> &&green)
void set_green(float green)
void set_blue(std::function<float(T)> &&blue)
void set_blue(float blue)
void set_white(std::function<float(T)> &&white)
void set_white(float white)
void set_color_temperature(std::function<float(T)> &&color_temperature)
void set_color_temperature(float color_temperature)
void set_effect(std::function<std::string(T)> &&effect)
void set_effect(std::string effect)
void play(T x)

Protected Attributes

LightState *state_
TemplatableValue<float, T> brightness_
TemplatableValue<float, T> red_
TemplatableValue<float, T> green_
TemplatableValue<float, T> blue_
TemplatableValue<float, T> white_
TemplatableValue<float, T> color_temperature_
TemplatableValue<uint32_t, T> transition_length_
TemplatableValue<uint32_t, T> flash_length_
TemplatableValue<std::string, T> effect_
template <typename T>
class ToggleAction : public Action<T>

Public Functions

ToggleAction(LightState *state)
void set_transition_length(std::function<uint32_t(T)> transition_length)
void set_transition_length(uint32_t transition_length)
void play(T x)

Protected Attributes

LightState *state_
TemplatableValue<uint32_t, T> transition_length_