ESPHome 2025.12.0-dev
Loading...
Searching...
No Matches
Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes
esphome::light::LightCall Class Reference

This class represents a requested change in a light state. More...

#include <light_call.h>

Public Member Functions

 LightCall (LightState *parent)
 
LightCall & set_state (optional< bool > state)
 Set the binary ON/OFF state of the light.
 
LightCall & set_state (bool state)
 Set the binary ON/OFF state of the light.
 
LightCall & set_transition_length (optional< uint32_t > transition_length)
 Set the transition length of this call in milliseconds.
 
LightCall & set_transition_length (uint32_t transition_length)
 Set the transition length of this call in milliseconds.
 
LightCall & set_transition_length_if_supported (uint32_t transition_length)
 Set the transition length property if the light supports transitions.
 
LightCall & set_flash_length (optional< uint32_t > flash_length)
 Start and set the flash length of this call in milliseconds.
 
LightCall & set_flash_length (uint32_t flash_length)
 Start and set the flash length of this call in milliseconds.
 
LightCall & set_brightness (optional< float > brightness)
 Set the target brightness of the light from 0.0 (fully off) to 1.0 (fully on)
 
LightCall & set_brightness (float brightness)
 Set the target brightness of the light from 0.0 (fully off) to 1.0 (fully on)
 
LightCall & set_brightness_if_supported (float brightness)
 Set the brightness property if the light supports brightness.
 
LightCall & set_color_mode (optional< ColorMode > color_mode)
 Set the color mode of the light.
 
LightCall & set_color_mode (ColorMode color_mode)
 Set the color mode of the light.
 
LightCall & set_color_mode_if_supported (ColorMode color_mode)
 Set the color mode of the light, if this mode is supported.
 
LightCall & set_color_brightness (optional< float > brightness)
 Set the color brightness of the light from 0.0 (no color) to 1.0 (fully on)
 
LightCall & set_color_brightness (float brightness)
 Set the color brightness of the light from 0.0 (no color) to 1.0 (fully on)
 
LightCall & set_color_brightness_if_supported (float brightness)
 Set the color brightness property if the light supports RGBW.
 
LightCall & set_red (optional< float > red)
 Set the red RGB value of the light from 0.0 to 1.0.
 
LightCall & set_red (float red)
 Set the red RGB value of the light from 0.0 to 1.0.
 
LightCall & set_red_if_supported (float red)
 Set the red property if the light supports RGB.
 
LightCall & set_green (optional< float > green)
 Set the green RGB value of the light from 0.0 to 1.0.
 
LightCall & set_green (float green)
 Set the green RGB value of the light from 0.0 to 1.0.
 
LightCall & set_green_if_supported (float green)
 Set the green property if the light supports RGB.
 
LightCall & set_blue (optional< float > blue)
 Set the blue RGB value of the light from 0.0 to 1.0.
 
LightCall & set_blue (float blue)
 Set the blue RGB value of the light from 0.0 to 1.0.
 
LightCall & set_blue_if_supported (float blue)
 Set the blue property if the light supports RGB.
 
LightCall & set_white (optional< float > white)
 Set the white value value of the light from 0.0 to 1.0 for RGBW[W] lights.
 
LightCall & set_white (float white)
 Set the white value value of the light from 0.0 to 1.0 for RGBW[W] lights.
 
LightCall & set_white_if_supported (float white)
 Set the white property if the light supports RGB.
 
LightCall & set_color_temperature (optional< float > color_temperature)
 Set the color temperature of the light in mireds for CWWW or RGBWW lights.
 
LightCall & set_color_temperature (float color_temperature)
 Set the color temperature of the light in mireds for CWWW or RGBWW lights.
 
LightCall & set_color_temperature_if_supported (float color_temperature)
 Set the color_temperature property if the light supports color temperature.
 
LightCall & set_cold_white (optional< float > cold_white)
 Set the cold white value of the light from 0.0 to 1.0.
 
LightCall & set_cold_white (float cold_white)
 Set the cold white value of the light from 0.0 to 1.0.
 
LightCall & set_cold_white_if_supported (float cold_white)
 Set the cold white property if the light supports cold white output.
 
LightCall & set_warm_white (optional< float > warm_white)
 Set the warm white value of the light from 0.0 to 1.0.
 
LightCall & set_warm_white (float warm_white)
 Set the warm white value of the light from 0.0 to 1.0.
 
LightCall & set_warm_white_if_supported (float warm_white)
 Set the warm white property if the light supports cold white output.
 
LightCall & set_effect (optional< std::string > effect)
 Set the effect of the light by its name.
 
LightCall & set_effect (const std::string &effect)
 Set the effect of the light by its name.
 
LightCall & set_effect (uint32_t effect_number)
 Set the effect of the light by its internal index number (only for internal use).
 
LightCall & set_effect (optional< uint32_t > effect_number)
 
LightCall & set_publish (bool publish)
 Set whether this light call should trigger a publish state.
 
LightCall & set_save (bool save)
 Set whether this light call should trigger a save state to recover them at startup..
 
bool has_state () const
 
bool has_brightness () const
 
bool has_color_brightness () const
 
bool has_red () const
 
bool has_green () const
 
bool has_blue () const
 
bool has_white () const
 
bool has_color_temperature () const
 
bool has_cold_white () const
 
bool has_warm_white () const
 
bool has_color_mode () const
 
LightCall & set_rgb (float red, float green, float blue)
 Set the RGB color of the light by RGB values.
 
LightCall & set_rgbw (float red, float green, float blue, float white)
 Set the RGBW color of the light by RGB values.
 
LightCall & from_light_color_values (const LightColorValues &values)
 
void perform ()
 

Protected Types

enum  FieldFlags : uint16_t {
  FLAG_HAS_STATE = 1 << 0 , FLAG_HAS_TRANSITION = 1 << 1 , FLAG_HAS_FLASH = 1 << 2 , FLAG_HAS_EFFECT = 1 << 3 ,
  FLAG_HAS_BRIGHTNESS = 1 << 4 , FLAG_HAS_COLOR_BRIGHTNESS = 1 << 5 , FLAG_HAS_RED = 1 << 6 , FLAG_HAS_GREEN = 1 << 7 ,
  FLAG_HAS_BLUE = 1 << 8 , FLAG_HAS_WHITE = 1 << 9 , FLAG_HAS_COLOR_TEMPERATURE = 1 << 10 , FLAG_HAS_COLD_WHITE = 1 << 11 ,
  FLAG_HAS_WARM_WHITE = 1 << 12 , FLAG_HAS_COLOR_MODE = 1 << 13 , FLAG_PUBLISH = 1 << 14 , FLAG_SAVE = 1 << 15
}
 

Protected Member Functions

ColorMode get_active_color_mode_ ()
 Get the currently targeted, or active if none set, color mode.
 
LightColorValues validate_ ()
 Validate all properties and return the target light color values.
 
ColorMode compute_color_mode_ ()
 
color_mode_bitmask_t get_suitable_color_modes_mask_ ()
 Get potential color modes bitmask for this light call.
 
void transform_parameters_ ()
 Some color modes also can be set using non-native parameters, transform those calls.
 
bool has_transition_ ()
 
bool has_flash_ ()
 
bool has_effect_ ()
 
bool get_publish_ ()
 
bool get_save_ ()
 
void set_flag_ (FieldFlags flag, bool value=true)
 
void clear_flag_ (FieldFlags flag)
 
void log_and_clear_unsupported_ (FieldFlags flag, const LogString *feature, bool use_color_mode_log)
 

Protected Attributes

LightState * parent_
 
uint32_t transition_length_
 
uint32_t flash_length_
 
uint32_t effect_
 
float brightness_
 
float color_brightness_
 
float red_
 
float green_
 
float blue_
 
float white_
 
float color_temperature_
 
float cold_white_
 
float warm_white_
 
uint16_t flags_ {FLAG_PUBLISH | FLAG_SAVE}
 
ColorMode color_mode_
 
bool state_
 

Detailed Description

This class represents a requested change in a light state.

Light state changes are tracked using a bitfield flags_ to minimize memory usage. Each possible light property has a flag indicating whether it has been set. This design keeps LightCall at ~56 bytes to minimize heap fragmentation on ESP8266 and other memory-constrained devices.

Definition at line 21 of file light_call.h.

Member Enumeration Documentation

◆ FieldFlags

enum esphome::light::LightCall::FieldFlags : uint16_t
protected
Enumerator
FLAG_HAS_STATE 
FLAG_HAS_TRANSITION 
FLAG_HAS_FLASH 
FLAG_HAS_EFFECT 
FLAG_HAS_BRIGHTNESS 
FLAG_HAS_COLOR_BRIGHTNESS 
FLAG_HAS_RED 
FLAG_HAS_GREEN 
FLAG_HAS_BLUE 
FLAG_HAS_WHITE 
FLAG_HAS_COLOR_TEMPERATURE 
FLAG_HAS_COLD_WHITE 
FLAG_HAS_WARM_WHITE 
FLAG_HAS_COLOR_MODE 
FLAG_PUBLISH 
FLAG_SAVE 

Definition at line 194 of file light_call.h.

Constructor & Destructor Documentation

◆ LightCall()

esphome::light::LightCall::LightCall ( LightState * parent)
inlineexplicit

Definition at line 23 of file light_call.h.

Member Function Documentation

◆ clear_flag_()

void esphome::light::LightCall::clear_flag_ ( FieldFlags flag)
inlineprotected

Definition at line 229 of file light_call.h.

◆ compute_color_mode_()

ColorMode esphome::light::LightCall::compute_color_mode_ ( )
protected

Definition at line 410 of file light_call.cpp.

◆ from_light_color_values()

LightCall & esphome::light::LightCall::from_light_color_values ( const LightColorValues & values)

Definition at line 527 of file light_call.cpp.

◆ get_active_color_mode_()

ColorMode esphome::light::LightCall::get_active_color_mode_ ( )
protected

Get the currently targeted, or active if none set, color mode.

Definition at line 541 of file light_call.cpp.

◆ get_publish_()

bool esphome::light::LightCall::get_publish_ ( )
inlineprotected

Definition at line 216 of file light_call.h.

◆ get_save_()

bool esphome::light::LightCall::get_save_ ( )
inlineprotected

Definition at line 217 of file light_call.h.

◆ get_suitable_color_modes_mask_()

color_mode_bitmask_t esphome::light::LightCall::get_suitable_color_modes_mask_ ( )
protected

Get potential color modes bitmask for this light call.

Definition at line 455 of file light_call.cpp.

◆ has_blue()

bool esphome::light::LightCall::has_blue ( ) const
inline

Definition at line 147 of file light_call.h.

◆ has_brightness()

bool esphome::light::LightCall::has_brightness ( ) const
inline

Definition at line 143 of file light_call.h.

◆ has_cold_white()

bool esphome::light::LightCall::has_cold_white ( ) const
inline

Definition at line 150 of file light_call.h.

◆ has_color_brightness()

bool esphome::light::LightCall::has_color_brightness ( ) const
inline

Definition at line 144 of file light_call.h.

◆ has_color_mode()

bool esphome::light::LightCall::has_color_mode ( ) const
inline

Definition at line 152 of file light_call.h.

◆ has_color_temperature()

bool esphome::light::LightCall::has_color_temperature ( ) const
inline

Definition at line 149 of file light_call.h.

◆ has_effect_()

bool esphome::light::LightCall::has_effect_ ( )
inlineprotected

Definition at line 215 of file light_call.h.

◆ has_flash_()

bool esphome::light::LightCall::has_flash_ ( )
inlineprotected

Definition at line 214 of file light_call.h.

◆ has_green()

bool esphome::light::LightCall::has_green ( ) const
inline

Definition at line 146 of file light_call.h.

◆ has_red()

bool esphome::light::LightCall::has_red ( ) const
inline

Definition at line 145 of file light_call.h.

◆ has_state()

bool esphome::light::LightCall::has_state ( ) const
inline

Definition at line 142 of file light_call.h.

◆ has_transition_()

bool esphome::light::LightCall::has_transition_ ( )
inlineprotected

Definition at line 213 of file light_call.h.

◆ has_warm_white()

bool esphome::light::LightCall::has_warm_white ( ) const
inline

Definition at line 151 of file light_call.h.

◆ has_white()

bool esphome::light::LightCall::has_white ( ) const
inline

Definition at line 148 of file light_call.h.

◆ log_and_clear_unsupported_()

void esphome::light::LightCall::log_and_clear_unsupported_ ( FieldFlags flag,
const LogString * feature,
bool use_color_mode_log )
protected

Definition at line 189 of file light_call.cpp.

◆ perform()

void esphome::light::LightCall::perform ( )

Definition at line 85 of file light_call.cpp.

◆ set_blue() [1/2]

LightCall & esphome::light::LightCall::set_blue ( float blue)

Set the blue RGB value of the light from 0.0 to 1.0.

Note that this only controls the color of the light, not its brightness.

◆ set_blue() [2/2]

LightCall & esphome::light::LightCall::set_blue ( optional< float > blue)

Set the blue RGB value of the light from 0.0 to 1.0.

Note that this only controls the color of the light, not its brightness.

◆ set_blue_if_supported()

LightCall & esphome::light::LightCall::set_blue_if_supported ( float blue)

Set the blue property if the light supports RGB.

Definition at line 574 of file light_call.cpp.

◆ set_brightness() [1/2]

LightCall & esphome::light::LightCall::set_brightness ( float brightness)

Set the target brightness of the light from 0.0 (fully off) to 1.0 (fully on)

◆ set_brightness() [2/2]

LightCall & esphome::light::LightCall::set_brightness ( optional< float > brightness)

Set the target brightness of the light from 0.0 (fully off) to 1.0 (fully on)

◆ set_brightness_if_supported()

LightCall & esphome::light::LightCall::set_brightness_if_supported ( float brightness)

Set the brightness property if the light supports brightness.

Definition at line 549 of file light_call.cpp.

◆ set_cold_white() [1/2]

LightCall & esphome::light::LightCall::set_cold_white ( float cold_white)

Set the cold white value of the light from 0.0 to 1.0.

◆ set_cold_white() [2/2]

LightCall & esphome::light::LightCall::set_cold_white ( optional< float > cold_white)

Set the cold white value of the light from 0.0 to 1.0.

◆ set_cold_white_if_supported()

LightCall & esphome::light::LightCall::set_cold_white_if_supported ( float cold_white)

Set the cold white property if the light supports cold white output.

Definition at line 590 of file light_call.cpp.

◆ set_color_brightness() [1/2]

LightCall & esphome::light::LightCall::set_color_brightness ( float brightness)

Set the color brightness of the light from 0.0 (no color) to 1.0 (fully on)

◆ set_color_brightness() [2/2]

LightCall & esphome::light::LightCall::set_color_brightness ( optional< float > brightness)

Set the color brightness of the light from 0.0 (no color) to 1.0 (fully on)

◆ set_color_brightness_if_supported()

LightCall & esphome::light::LightCall::set_color_brightness_if_supported ( float brightness)

Set the color brightness property if the light supports RGBW.

Definition at line 559 of file light_call.cpp.

◆ set_color_mode() [1/2]

LightCall & esphome::light::LightCall::set_color_mode ( ColorMode color_mode)

Set the color mode of the light.

◆ set_color_mode() [2/2]

LightCall & esphome::light::LightCall::set_color_mode ( optional< ColorMode > color_mode)

Set the color mode of the light.

◆ set_color_mode_if_supported()

LightCall & esphome::light::LightCall::set_color_mode_if_supported ( ColorMode color_mode)

Set the color mode of the light, if this mode is supported.

Definition at line 554 of file light_call.cpp.

◆ set_color_temperature() [1/2]

LightCall & esphome::light::LightCall::set_color_temperature ( float color_temperature)

Set the color temperature of the light in mireds for CWWW or RGBWW lights.

◆ set_color_temperature() [2/2]

LightCall & esphome::light::LightCall::set_color_temperature ( optional< float > color_temperature)

Set the color temperature of the light in mireds for CWWW or RGBWW lights.

◆ set_color_temperature_if_supported()

LightCall & esphome::light::LightCall::set_color_temperature_if_supported ( float color_temperature)

Set the color_temperature property if the light supports color temperature.

Definition at line 584 of file light_call.cpp.

◆ set_effect() [1/4]

LightCall & esphome::light::LightCall::set_effect ( const std::string & effect)

Set the effect of the light by its name.

Definition at line 506 of file light_call.cpp.

◆ set_effect() [2/4]

LightCall & esphome::light::LightCall::set_effect ( optional< std::string > effect)

Set the effect of the light by its name.

◆ set_effect() [3/4]

LightCall & esphome::light::LightCall::set_effect ( optional< uint32_t > effect_number)

Definition at line 623 of file light_call.cpp.

◆ set_effect() [4/4]

LightCall & esphome::light::LightCall::set_effect ( uint32_t effect_number)

Set the effect of the light by its internal index number (only for internal use).

Definition at line 618 of file light_call.cpp.

◆ set_flag_()

void esphome::light::LightCall::set_flag_ ( FieldFlags flag,
bool value = true )
inlineprotected

Definition at line 220 of file light_call.h.

◆ set_flash_length() [1/2]

LightCall & esphome::light::LightCall::set_flash_length ( optional< uint32_t > flash_length)

Start and set the flash length of this call in milliseconds.

◆ set_flash_length() [2/2]

LightCall & esphome::light::LightCall::set_flash_length ( uint32_t flash_length)

Start and set the flash length of this call in milliseconds.

◆ set_green() [1/2]

LightCall & esphome::light::LightCall::set_green ( float green)

Set the green RGB value of the light from 0.0 to 1.0.

Note that this only controls the color of the light, not its brightness.

◆ set_green() [2/2]

LightCall & esphome::light::LightCall::set_green ( optional< float > green)

Set the green RGB value of the light from 0.0 to 1.0.

Note that this only controls the color of the light, not its brightness.

◆ set_green_if_supported()

LightCall & esphome::light::LightCall::set_green_if_supported ( float green)

Set the green property if the light supports RGB.

Definition at line 569 of file light_call.cpp.

◆ set_publish()

LightCall & esphome::light::LightCall::set_publish ( bool publish)

Set whether this light call should trigger a publish state.

Definition at line 630 of file light_call.cpp.

◆ set_red() [1/2]

LightCall & esphome::light::LightCall::set_red ( float red)

Set the red RGB value of the light from 0.0 to 1.0.

Note that this only controls the color of the light, not its brightness.

◆ set_red() [2/2]

LightCall & esphome::light::LightCall::set_red ( optional< float > red)

Set the red RGB value of the light from 0.0 to 1.0.

Note that this only controls the color of the light, not its brightness.

◆ set_red_if_supported()

LightCall & esphome::light::LightCall::set_red_if_supported ( float red)

Set the red property if the light supports RGB.

Definition at line 564 of file light_call.cpp.

◆ set_rgb()

LightCall & esphome::light::LightCall::set_rgb ( float red,
float green,
float blue )

Set the RGB color of the light by RGB values.

Please note that this only changes the color of the light, not the brightness.

Parameters
redThe red color value from 0.0 to 1.0.
greenThe green color value from 0.0 to 1.0.
blueThe blue color value from 0.0 to 1.0.
Returns
The light call for chaining setters.

Definition at line 638 of file light_call.cpp.

◆ set_rgbw()

LightCall & esphome::light::LightCall::set_rgbw ( float red,
float green,
float blue,
float white )

Set the RGBW color of the light by RGB values.

Please note that this only changes the color of the light, not the brightness.

Parameters
redThe red color value from 0.0 to 1.0.
greenThe green color value from 0.0 to 1.0.
blueThe blue color value from 0.0 to 1.0.
whiteThe white color value from 0.0 to 1.0.
Returns
The light call for chaining setters.

Definition at line 644 of file light_call.cpp.

◆ set_save()

LightCall & esphome::light::LightCall::set_save ( bool save)

Set whether this light call should trigger a save state to recover them at startup..

Definition at line 634 of file light_call.cpp.

◆ set_state() [1/2]

LightCall & esphome::light::LightCall::set_state ( bool state)

Set the binary ON/OFF state of the light.

◆ set_state() [2/2]

LightCall & esphome::light::LightCall::set_state ( optional< bool > state)

Set the binary ON/OFF state of the light.

◆ set_transition_length() [1/2]

LightCall & esphome::light::LightCall::set_transition_length ( optional< uint32_t > transition_length)

Set the transition length of this call in milliseconds.

This argument is ignored for starting flashes and effects.

Defaults to the default transition length defined in the light configuration.

◆ set_transition_length() [2/2]

LightCall & esphome::light::LightCall::set_transition_length ( uint32_t transition_length)

Set the transition length of this call in milliseconds.

This argument is ignored for starting flashes and effects.

Defaults to the default transition length defined in the light configuration.

◆ set_transition_length_if_supported()

LightCall & esphome::light::LightCall::set_transition_length_if_supported ( uint32_t transition_length)

Set the transition length property if the light supports transitions.

Definition at line 544 of file light_call.cpp.

◆ set_warm_white() [1/2]

LightCall & esphome::light::LightCall::set_warm_white ( float warm_white)

Set the warm white value of the light from 0.0 to 1.0.

◆ set_warm_white() [2/2]

LightCall & esphome::light::LightCall::set_warm_white ( optional< float > warm_white)

Set the warm white value of the light from 0.0 to 1.0.

◆ set_warm_white_if_supported()

LightCall & esphome::light::LightCall::set_warm_white_if_supported ( float warm_white)

Set the warm white property if the light supports cold white output.

Definition at line 595 of file light_call.cpp.

◆ set_white() [1/2]

LightCall & esphome::light::LightCall::set_white ( float white)

Set the white value value of the light from 0.0 to 1.0 for RGBW[W] lights.

◆ set_white() [2/2]

LightCall & esphome::light::LightCall::set_white ( optional< float > white)

Set the white value value of the light from 0.0 to 1.0 for RGBW[W] lights.

◆ set_white_if_supported()

LightCall & esphome::light::LightCall::set_white_if_supported ( float white)

Set the white property if the light supports RGB.

Definition at line 579 of file light_call.cpp.

◆ transform_parameters_()

void esphome::light::LightCall::transform_parameters_ ( )
protected

Some color modes also can be set using non-native parameters, transform those calls.

Definition at line 371 of file light_call.cpp.

◆ validate_()

LightColorValues esphome::light::LightCall::validate_ ( )
protected

Validate all properties and return the target light color values.

Definition at line 199 of file light_call.cpp.

Field Documentation

◆ blue_

float esphome::light::LightCall::blue_
protected

Definition at line 245 of file light_call.h.

◆ brightness_

float esphome::light::LightCall::brightness_
protected

Definition at line 241 of file light_call.h.

◆ cold_white_

float esphome::light::LightCall::cold_white_
protected

Definition at line 248 of file light_call.h.

◆ color_brightness_

float esphome::light::LightCall::color_brightness_
protected

Definition at line 242 of file light_call.h.

◆ color_mode_

ColorMode esphome::light::LightCall::color_mode_
protected

Definition at line 253 of file light_call.h.

◆ color_temperature_

float esphome::light::LightCall::color_temperature_
protected

Definition at line 247 of file light_call.h.

◆ effect_

uint32_t esphome::light::LightCall::effect_
protected

Definition at line 240 of file light_call.h.

◆ flags_

uint16_t esphome::light::LightCall::flags_ {FLAG_PUBLISH | FLAG_SAVE}
protected

Definition at line 252 of file light_call.h.

◆ flash_length_

uint32_t esphome::light::LightCall::flash_length_
protected

Definition at line 239 of file light_call.h.

◆ green_

float esphome::light::LightCall::green_
protected

Definition at line 244 of file light_call.h.

◆ parent_

LightState* esphome::light::LightCall::parent_
protected

Definition at line 234 of file light_call.h.

◆ red_

float esphome::light::LightCall::red_
protected

Definition at line 243 of file light_call.h.

◆ state_

bool esphome::light::LightCall::state_
protected

Definition at line 254 of file light_call.h.

◆ transition_length_

uint32_t esphome::light::LightCall::transition_length_
protected

Definition at line 238 of file light_call.h.

◆ warm_white_

float esphome::light::LightCall::warm_white_
protected

Definition at line 249 of file light_call.h.

◆ white_

float esphome::light::LightCall::white_
protected

Definition at line 246 of file light_call.h.

The documentation for this class was generated from the following files:
Generated by doxygen 1.12.0