Use a custom state class for addressable lights, to allow type system to discriminate between addressable and non-addressable lights. More...

#include <addressable_light.h>

Inheritance diagram for esphome::light::AddressableLightState:

Public Member Functions
float	get_estimated_current_ma () const

void	loop () override

Public Member Functions inherited from esphome::light::LightState
	LightState (LightOutput *output)

LightTraits	get_traits ()

LightCall	turn_on ()
	Make a light state call.

LightCall	turn_off ()

LightCall	toggle ()

const LightColorValues &	get_reported_values () const
	The values reported to the frontend: current_values while a light publishes intermediate states on an interval, otherwise remote_values.

bool	is_transitioning () const
	True from the call that starts a transition or flash until it reaches its target.

bool	called_since_clear () const
	True once a call is performed after clear_called(), so an output can tell whether a call came after something it noted.

void	clear_called ()

LightCall	make_call ()

bool	set_external_state (const LightColorValues &values)
	Take over the state of a light mirrored from elsewhere: current and target values at once, published but not written or saved; a running effect stops.

void	setup () override
	Load state from preferences.

void	dump_config () override

void	loop () override

float	get_setup_priority () const override
	Shortly after HARDWARE.

void	publish_state ()
	Publish the currently active state to the frontend.

LightOutput *	get_output () const
	Get the light output associated with this object.

StringRef	get_effect_name ()
	Return the name of the current effect, or if no effect is active "None".

void	add_remote_values_listener (LightRemoteValuesListener *listener)
	Add a listener for remote values changes.

void	add_target_state_reached_listener (LightTargetStateReachedListener *listener)
	Add a listener for target state reached.

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.

uint32_t	get_default_transition_length () const

void	set_flash_transition_length (uint32_t flash_transition_length)
	Set the flash transition length; only compiled in when a light configures one.

uint32_t	get_flash_transition_length () const

	ESPDEPRECATED ("set_flash_transition_length() does nothing unless flash_transition_length is set in YAML. Removed in " "2027.4.0", "2026.10.0") void set_flash_transition_length(uint32_t flash_transition_length)

uint32_t	get_flash_transition_length () const

	ESPDEPRECATED ("set_gamma_correct() does nothing; gamma is fixed at build time by gamma_correct in YAML. Removed in " "2027.4.0", "2026.10.0") void set_gamma_correct(float gamma_correct)

float	get_gamma_correct () const
	The gamma correction factor, read from the entry after the gamma lookup table; 0 without one.

void	set_transition_state_publish_interval (uint32_t transition_state_publish_interval)

uint32_t	get_transition_state_publish_interval () const

void	set_gamma_table (const GammaTable *table)
	Set the pre-computed PROGMEM gamma curve.

const uint16_t *	get_gamma_table () const
	Get the forward gamma lookup table, 256 PROGMEM entries.

float	gamma_correct_lut (float value) const
	Apply gamma correction using the pre-computed forward LUT.

float	gamma_uncorrect_lut (float value) const
	Reverse gamma correction by binary-searching the forward LUT.

float	gamma_correct_lut (float value) const
	No gamma LUT — passthrough.

float	gamma_uncorrect_lut (float value) const

void	set_state_callback (void(*callback)(LightStateRTCState &, bool restored))
	Set the callback that resolves the boot-time state, called once during setup then cleared.

void	set_save_enabled (bool save_enabled)
	Set whether this light persists its state to preferences at all.

void	set_resume_effect (bool resume_effect)
	Set whether a plain turn-on restores the effect that was active when the light was turned off.

bool	supports_effects () const
	Return whether the light has any effects that meet the trait requirements.

const ConstVector< LightEffect * > &	get_effects () const
	Get all effects for this light state.

void	add_effects (LightEffect const effects, size_t count)
	Codegen only: point at the generated table of this light's effects, which must outlive it.

size_t	get_effect_count () const
	Get the total number of effects available for this light.

uint32_t	get_current_effect_index () const
	Get the currently active effect index (0 = no effect, 1+ = effect index).

uint32_t	get_effect_index (const std::string &effect_name) const
	Get effect index by name. Returns 0 if effect not found.

uint32_t	get_effect_index (const char *name, size_t len) const
	Get effect index by name (const char* overload, avoids std::string construction).

LightEffect *	get_effect_by_index (uint32_t index) const
	Get effect by index. Returns nullptr if index is invalid.

std::string	get_effect_name_by_index (uint32_t index) const
	Get effect name by index. Returns "None" for index 0, empty string for invalid index.

void	current_values_as_binary (bool *binary)
	The result of all the current_values_as_* methods have gamma correction applied.

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 red, float green, float blue, float cold_white, float *warm_white, bool constant_brightness=false)

void	current_values_as_rgbct (float red, float green, float blue, float color_temperature, float *white_brightness)

void	current_values_as_cwww (float cold_white, float warm_white, bool constant_brightness=false)

void	current_values_as_ct (float color_temperature, float white_brightness)

bool	is_transformer_active () const
	Indicator if a transformer (e.g.

Public Member Functions inherited from esphome::EntityBase
	ESPDEPRECATED ("Use get_name_to() or get_log_name() instead. Will be removed in ESPHome 2027.5.0", "2026.11.0") const StringRef &get_name() const
	The name is in flash here; the first call makes a RAM copy that is kept for the life of the device.

StringRef	get_name_to (std::span< char, ENTITY_NAME_BUF_SIZE > buffer) const
	Get the name of this Entity, copied out of flash into buffer.

	ESPDEPRECATED ("Use get_name_to() or get_log_name() instead. Will be removed in ESPHome 2027.5.0", "2026.11.0") const StringRef &get_name() const

const StringRef &	get_name_to (std::span< char, ENTITY_NAME_BUF_SIZE >) const

bool	name_equals (const StringRef &other) const

const ProgmemStringRef &	get_name_progmem () const
	The name as stored, for consumers that read flash themselves (e.g. API progmem fields).

size_t	write_name_to (char *buf, size_t buf_size) const
	Copy the name into buf (null terminated), returns its length.

const LogString *	get_log_name () const
	Get the name for a "%s" log argument (LOG_STR_ARG).

bool	has_own_name () const

uint32_t	get_object_id_hash () const

StringRef	get_object_id_to (std::span< char, OBJECT_ID_MAX_LEN > buf) const
	Get object_id with zero heap allocation For static case: returns StringRef to internal storage (buffer unused) For dynamic case: formats into buffer and returns StringRef to buffer.

size_t	write_object_id_to (char *buf, size_t buf_size) const
	Write object_id directly to buffer, returns length written (excluding null) Useful for building compound strings without intermediate buffer.

bool	is_internal () const

void	set_internal (bool internal)

bool	is_disabled_by_default () const

EntityCategory	get_entity_category () const

const char *	get_device_class_to (std::span< char, MAX_DEVICE_CLASS_LENGTH > buffer) const

ProgmemStringRef	get_device_class_progmem () const
	The device class as stored (in flash on ESP8266), for consumers that read flash themselves.

StringRef	get_unit_of_measurement_ref () const

const char *	get_icon_to (std::span< char, MAX_ICON_LENGTH > buffer) const

ProgmemStringRef	get_icon_progmem () const
	The icon as stored (in flash on ESP8266), for consumers that read flash themselves.

uint32_t	get_device_id () const

Device *	get_device () const

bool	has_state () const

void	set_has_state (bool state)

	ESPDEPRECATED ("Use make_entity_preference<T>() instead, or preferences won't be migrated. " "See https://github.com/esphome/backlog/issues/85. Will be removed in 2027.1.0.", "2026.7.0") uint32_t get_preference_hash()
	Get a unique hash for storing preferences/settings for this entity.

template<typename T >
ESPPreferenceObject	make_entity_preference (uint32_t version=0)
	Create a preference object for storing this entity's state/settings.

template<typename T >
ESPPreferenceObject	make_entity_preference (uint32_t version, bool in_flash)
	As make_entity_preference(), stored in flash or RTC memory where the backend supports the choice.

Public Member Functions inherited from esphome::Component
float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

virtual bool	teardown ()
	Called during teardown to allow component to gracefully finish operations.

virtual void	on_powerdown ()
	Called after teardown is complete to power down hardware.

uint8_t	get_component_state () const

void	reset_to_construction_state ()
	Reset this component back to the construction state to allow setup to run again.

bool	is_in_loop_state () const
	Check if this component has completed setup and is in the loop state.

bool	is_idle () const
	Check if this component is idle.

void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const LogString *message)

void	disable_loop ()
	Disable this component's loop.

void	enable_loop ()
	Enable this component's loop.

void	enable_loop_soon_any_context ()
	Thread and ISR-safe version of enable_loop() that can be called from any context.

bool	is_failed () const

bool	is_ready () const

virtual bool	can_proceed ()

bool	status_has_warning () const

bool	status_has_error () const

void	status_set_warning ()

void	status_set_warning (const char *message)

void	status_set_warning (const LogString *message)

bool	status_comm_result (bool ok)
	Clears the warning when `ok`, else sets it with `message` (default "Communication failed"); returns `ok`.

bool	status_comm_result (bool ok, const LogString *message)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

	ESPDEPRECATED ("Use status_momentary_warning() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_warning(const char *name

void	status_momentary_warning (uint32_t length=5000)
	Set warning status flag and clear it after `length` ms.

void	status_momentary_warning (const LogString *message, uint32_t length=5000)

	ESPDEPRECATED ("Use status_momentary_error() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_error(const char *name

void	status_momentary_error (uint32_t length=5000)
	Set error status flag and clear it after `length` ms.

void	status_momentary_error (const LogString *message, uint32_t length=5000)

bool	has_overridden_loop () const

const LogString *	get_component_log_str () const ESPHOME_ALWAYS_INLINE
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)

Additional Inherited Members
Data Fields inherited from esphome::light::LightState
LightColorValues	current_values
	The current values of the light as outputted to the light.

LightColorValues	remote_values
	The remote color values reported to the frontend.

Data Fields inherited from esphome::Component
uint32_t	length = 5000)

Protected Member Functions inherited from esphome::light::LightState
void	apply_effect_and_transformer_ ()

void	write_if_pending_ ()

void	start_effect_ (uint32_t effect_index)
	Internal method to start an effect with the given index.

LightEffect *	get_active_effect_ ()
	Internal method to get the currently active effect.

void	stop_effect_ ()
	Internal method to stop the current effect (if one is active).

void	start_transition_ (const LightColorValues &target, uint32_t length, bool set_remote_values)
	Internal method to start a transition to the target color with the given length.

void	start_flash_ (const LightColorValues &target, uint32_t length, bool set_remote_values)
	Internal method to start a flash for the specified amount of time.

void	set_immediately_ (const LightColorValues &target, bool set_remote_values)
	Internal method to set the color values to target immediately (with no transition).

void	set_transformer_remote_values_ (const LightColorValues &target, bool set_remote_values)
	Point remote_values at the new transformer's target and, when this light publishes intermediate states on an interval, start the interval clock.

void	set_transformer_remote_values_ (const LightColorValues &target, bool set_remote_values)

void	save_remote_values_ ()
	Internal method to save the current remote_values to the preferences.

void	disable_loop_if_idle_ ()
	Disable loop if neither transformer nor effect is active.

void	schedule_write_ ()
	Schedule a write to the light output and enable the loop to process it.

Protected Member Functions inherited from esphome::EntityBase
friend	void::setup ()

friend	void::original_setup ()

void	configure_entity_ (const char *name, uint32_t object_id_hash, uint32_t entity_fields)
	Combined entity setup from codegen: set name, object_id hash, entity string indices, and flags.

void	set_device_ (Device *device)

ESPPreferenceObject	make_entity_preference_ (size_t size, uint32_t version)
	Non-template helpers for make_entity_preference() to avoid code bloat.

ESPPreferenceObject	make_entity_preference_ (size_t size, uint32_t version, bool in_flash)

uint32_t	entity_preference_key_ (uint32_t version)
	Key for both helpers; preference hash migration goes here.

Protected Member Functions inherited from esphome::Component
friend	void::setup ()

friend	void::original_setup ()

void	set_component_source_ (uint8_t index)
	Set where this component was loaded from for some debug messages.

virtual void	call_setup ()

void	call_dump_config_ ()

void	enable_loop_slow_path_ ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

bool	set_status_flag_ (uint8_t flag)
	Helper to set a status LED flag on both this component and the app.

bool	set_error_flag_ (const LogString *message)
	Set the error flag and log it; true when it was not set before.

void	set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a const char* name.

void	set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a numeric ID (zero heap allocation).

void	set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const char *name)
	Cancel an interval function.

bool	cancel_interval (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

void	set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a const char* name.

void	set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a numeric ID (zero heap allocation).

void	set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const char *name)
	Cancel a timeout function.

bool	cancel_timeout (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

void	defer (const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call with a const char* name.

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call.

void	defer (uint32_t id, std::function< void()> &&f)
	Defer a callback with a numeric ID (zero heap allocation)

bool	cancel_defer (const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

bool	cancel_defer (uint32_t id)

void	status_clear_warning_slow_path_ ()

void	status_clear_error_slow_path_ ()

Protected Attributes inherited from esphome::light::LightState
friend	LightOutput

friend	LightCall

LightOutput *	output_
	Store the output to allow effects to have more access.

std::unique_ptr< LightTransformer >	transformer_ {nullptr}
	The currently active transformer for this light (transition/flash).

ConstVector< LightEffect * >	effects_
	List of effects for this light.

ESPPreferenceObject	rtc_
	Object used to store the persisted values of the light.

std::unique_ptr< std::vector< LightRemoteValuesListener * > >	remote_values_listeners_
	Listeners for remote values changes.

std::unique_ptr< std::vector< LightTargetStateReachedListener * > >	target_state_reached_listeners_
	Listeners for target state reached.

void(*	state_callback_ )(LightStateRTCState &, bool restored)
	Callback that resolves the boot-time state — called once during setup, then cleared.

uint32_t	default_transition_length_ {}
	Default transition length for all transitions in ms.

uint32_t	flash_transition_length_ {}
	Transition length to use for flash transitions.

uint32_t	transition_state_publish_interval_ {0}

uint32_t	last_transition_state_publish_ {0}

const GammaTable *	gamma_table_ {nullptr}

uint16_t	active_effect_index_ {}
	1-based index of the active effect, 0 if none; codegen caps effects at MAX_EFFECTS in effects.py

uint16_t	previous_effect_index_ {0}
	The effect index that was active when the light was last turned off; shares the active index's word.

bool	next_write_ {true}
	Whether the light value should be written in the next cycle.

bool	is_transformer_active_: 1 {false}

bool	called_: 1 {false}

bool	save_enabled_: 1 {false}
	Whether this light persists its state to preferences at all.

bool	transition_publish_enabled_: 1 {false}
	True while the active transformer publishes current_values on an interval from loop().

bool	resume_effect_: 1 {false}
	Whether a plain turn-on restores the effect that was active when the light was turned off.

Protected Attributes inherited from esphome::EntityBase
ProgmemStringRef	name_

uint32_t	object_id_hash_ {}

Device *	device_ {}

struct esphome::EntityBase::EntityFlags	flags_

uint8_t	device_class_idx_ {}

uint8_t	uom_idx_ {}

uint8_t	icon_idx_ {}

Protected Attributes inherited from esphome::Component
uint8_t	component_source_index_ {0}
	Index into component source PROGMEM lookup table (0 = not set)

uint8_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
	Warn threshold in centiseconds (max 2550ms)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

ComponentRuntimeStats	runtime_stats_

Detailed Description

Use a custom state class for addressable lights, to allow type system to discriminate between addressable and non-addressable lights.

Definition at line 26 of file addressable_light.h.

Member Function Documentation

◆ get_estimated_current_ma()

float esphome::light::AddressableLightState::get_estimated_current_ma ( ) const

Definition at line 12 of file addressable_light.cpp.

◆ loop()

void esphome::light::AddressableLightState::loop ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 16 of file addressable_light.cpp.

The documentation for this class was generated from the following files:

esphome/components/light/addressable_light.h
esphome/components/light/addressable_light.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ get_estimated_current_ma()

◆ loop()