#include <component.h>

Inheritance diagram for esphome::Component:

Public Member Functions
virtual void	setup ()
	Where the component's initialization should happen.

virtual void	loop ()
	This method will be called repeatedly.

virtual void	dump_config ()

virtual float	get_setup_priority () const
	priority of setup().

float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

virtual float	get_loop_priority () const
	priority of loop().

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.

virtual void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const char *message)

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 (const char *message="unspecified")

void	status_set_error (const char *message="unspecified")

void	status_clear_warning ()

void	status_clear_error ()

void	status_momentary_warning (const std::string &name, uint32_t length=5000)

void	status_momentary_error (const std::string &name, uint32_t length=5000)

bool	has_overridden_loop () const

void	set_component_source (const char *source)
	Set where this component was loaded from for some debug messages.

const char *	get_component_source () const
	Get the integration where this component was declared as a string.

bool	should_warn_of_blocking (uint32_t blocking_time)

Protected Member Functions
virtual void	call_loop ()

virtual void	call_setup ()

virtual void	call_dump_config ()

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

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

bool	cancel_interval (const std::string &name)
	Cancel an interval function.

void	set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
	Set an retry function with a unique name.

void	set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)

bool	cancel_retry (const std::string &name)
	Cancel a retry function.

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

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

bool	cancel_timeout (const std::string &name)
	Cancel a timeout function.

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

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

bool	cancel_defer (const std::string &name)
	Cancel a defer callback using the specified name, name must not be empty.

Protected Attributes
uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-1: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED) Bit 2: STATUS_LED_WARNING Bit 3: STATUS_LED_ERROR Bits 4-7: Unused - reserved for future expansion (50% of the bits are free)

float	setup_priority_override_ {NAN}

const char *	component_source_ {nullptr}

uint16_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_MS}
	Warn if blocked for this many ms (max 65.5s)

std::string	error_message_ {}

Detailed Description

Definition at line 70 of file component.h.

Member Function Documentation

◆ call()

void esphome::Component::call ( )

Definition at line 93 of file component.cpp.

◆ call_dump_config()

void esphome::Component::call_dump_config ( )

protectedvirtual

Reimplemented in esphome::mqtt::MQTTComponent.

Definition at line 85 of file component.cpp.

◆ call_loop()

void esphome::Component::call_loop ( )

protectedvirtual

Reimplemented in esphome::mqtt::MQTTComponent.

Definition at line 83 of file component.cpp.

◆ call_setup()

void esphome::Component::call_setup ( )

protectedvirtual

Reimplemented in esphome::light::AddressableLight, esphome::mqtt::MQTTComponent, esphome::PollingComponent, and esphome::touchscreen::Touchscreen.

Definition at line 84 of file component.cpp.

◆ can_proceed()

bool esphome::Component::can_proceed ( )

virtual

Reimplemented in esphome::cst226::CST226Touchscreen, esphome::esp32_ble_server::BLEServer, esphome::ethernet::EthernetComponent, esphome::midea::ApplianceBase< T >, esphome::midea::ApplianceBase< dudanov::midea::ac::AirConditioner >, esphome::mipi_spi::MipiSpi, esphome::mqtt::MQTTClientComponent, esphome::qspi_dbi::QspiDbi, esphome::wifi::WiFiComponent, and esphome::wireguard::Wireguard.

Definition at line 179 of file component.cpp.

◆ cancel_defer()

bool esphome::Component::cancel_defer ( const std::string & name )

protected

Cancel a defer callback using the specified name, name must not be empty.

Definition at line 158 of file component.cpp.

◆ cancel_interval()

bool esphome::Component::cancel_interval ( const std::string & name )

protected

Cancel an interval function.

Parameters

name	The identifier for this interval function.

Returns: Whether an interval functions was deleted.

Definition at line 62 of file component.cpp.

◆ cancel_retry()

bool esphome::Component::cancel_retry ( const std::string & name )

protected

Cancel a retry function.

Parameters

name	The identifier for this retry function.

Returns: Whether a retry function was deleted.

Definition at line 71 of file component.cpp.

◆ cancel_timeout()

bool esphome::Component::cancel_timeout ( const std::string & name )

protected

Cancel a timeout function.

Parameters

name	The identifier for this timeout function.

Returns: Whether a timeout functions was deleted.

Definition at line 79 of file component.cpp.

◆ defer() [1/2]

void esphome::Component::defer	(	const std::string &	name,
		std::function< void()> &&	f )

protected

Defer a callback to the next loop() call.

If name is specified and a defer() object with the same name exists, the old one is first removed.

Parameters

name	The name of the defer function.
f	The callback.

Definition at line 161 of file component.cpp.

◆ defer() [2/2]

void esphome::Component::defer ( std::function< void()> && f )

protected

Defer a callback to the next loop() call.

Definition at line 155 of file component.cpp.

◆ dump_config()

void esphome::Component::dump_config ( )

virtual

Definition at line 219 of file component.cpp.

◆ get_actual_setup_priority()

float esphome::Component::get_actual_setup_priority ( ) const

Definition at line 220 of file component.cpp.

◆ get_component_source()

const char * esphome::Component::get_component_source ( ) const

Get the integration where this component was declared as a string.

Returns "<unknown>" if source not set

Definition at line 119 of file component.cpp.

◆ get_component_state()

uint8_t esphome::Component::get_component_state ( ) const

Definition at line 92 of file component.cpp.

◆ get_loop_priority()

float esphome::Component::get_loop_priority ( ) const

virtual

priority of loop().

higher -> executed earlier

Defaults to 0.

Returns: The loop priority of this component

Reimplemented in esphome::ch422g::CH422GComponent, esphome::deep_sleep::DeepSleepComponent, esphome::pca9554::PCA9554Component, esphome::status_led::StatusLED, esphome::status_led::StatusLEDLightOutput, and esphome::wifi::WiFiComponent.

Definition at line 50 of file component.cpp.

◆ get_setup_priority()

float esphome::Component::get_setup_priority ( ) const

virtual

priority of setup().

higher -> executed earlier

Defaults to setup_priority::DATA, i.e. 600.

Returns: The setup priority of this component

Definition at line 52 of file component.cpp.

◆ has_overridden_loop()

bool esphome::Component::has_overridden_loop ( ) const

Definition at line 227 of file component.cpp.

◆ is_failed()

bool esphome::Component::is_failed ( ) const

Definition at line 174 of file component.cpp.

◆ is_in_loop_state()

bool esphome::Component::is_in_loop_state ( ) const

Check if this component has completed setup and is in the loop state.

Returns: True if in loop state, false otherwise.

Definition at line 152 of file component.cpp.

◆ is_ready()

bool esphome::Component::is_ready ( ) const

Definition at line 175 of file component.cpp.

◆ loop()

void esphome::Component::loop ( )

virtual

This method will be called repeatedly.

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

Definition at line 56 of file component.cpp.

◆ mark_failed() [1/2]

void esphome::Component::mark_failed ( )

virtual

Mark this component as failed.

Any future timeouts/intervals/setup/loop will no longer be called.

This might be useful if a component wants to indicate that a connection to its peripheral failed. For example, i2c based components can check if the remote device is responding and otherwise mark the component as failed. Eventually this will also enable smart status LEDs.

Definition at line 137 of file component.cpp.

◆ mark_failed() [2/2]

void esphome::Component::mark_failed ( const char * message )

inline

Definition at line 148 of file component.h.

◆ on_powerdown()

virtual void esphome::Component::on_powerdown ( )

inlinevirtual

Called after teardown is complete to power down hardware.

This is called after all components have finished their teardown process, making it safe to power down hardware like ethernet PHY.

Reimplemented in esphome::ethernet::EthernetComponent, esphome::ili9xxx::ILI9XXXDisplay, esphome::pn532::PN532, and esphome::power_supply::PowerSupply.

Definition at line 124 of file component.h.

◆ on_safe_shutdown()

virtual void esphome::Component::on_safe_shutdown ( )

inlinevirtual

Reimplemented in esphome::esp32_dac::ESP32DAC, esphome::safe_mode::SafeModeComponent, and esphome::waveshare_epaper::WaveshareEPaperBase.

Definition at line 111 of file component.h.

◆ on_shutdown()

virtual void esphome::Component::on_shutdown ( )

inlinevirtual

Reimplemented in esphome::api::APIServer, esphome::debug::DebugComponent, esphome::esp32_camera_web_server::CameraWebServer, esphome::esp32_touch::ESP32TouchComponent, esphome::globals::RestoringGlobalsComponent< T >, esphome::globals::RestoringGlobalStringComponent< T, SZ >, esphome::mdns::MDNSComponent, esphome::mqtt::MQTTClientComponent, esphome::opentherm::OpenthermHub, esphome::preferences::IntervalSyncer, esphome::ShutdownTrigger, and esphome::wireguard::Wireguard.

Definition at line 110 of file component.h.

◆ reset_to_construction_state()

void esphome::Component::reset_to_construction_state ( )

Reset this component back to the construction state to allow setup to run again.

This can be used by components that have recoverable failures to attempt setup again.

Definition at line 143 of file component.cpp.

◆ set_component_source()

void esphome::Component::set_component_source ( const char * source )

inline

Set where this component was loaded from for some debug messages.

This is set by the ESPHome core, and should not be called manually.

Definition at line 181 of file component.h.

◆ set_interval() [1/2]

void esphome::Component::set_interval	(	const std::string &	name,
		uint32_t	interval,
		std::function< void()> &&	f )

protected

Set an interval function with a unique name.

Empty name means no cancelling possible.

This will call f every interval ms. Can be cancelled via CancelInterval(). Similar to javascript's setInterval().

IMPORTANT NOTE: The only guarantee offered by this call is that the callback will be called no earlier than the specified interval after the previous call. Any given interval may be longer due to other components blocking the loop() call.

So do not rely on this having correct timing. If you need exact timing please use hardware timers.

Note also that the first call to f will not happen immediately, but after a random delay. This is intended to prevent many interval functions from being called at the same time.

Parameters

name	The identifier for this interval function.
interval	The interval in ms.
f	The function (or lambda) that should be called

See also: cancel_interval()

Definition at line 58 of file component.cpp.

◆ set_interval() [2/2]

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

protected

Definition at line 167 of file component.cpp.

◆ set_retry() [1/2]

void esphome::Component::set_retry	(	const std::string &	name,
		uint32_t	initial_wait_time,
		uint8_t	max_attempts,
		std::function< RetryResult(uint8_t)> &&	f,
		float	backoff_increase_factor = 1.0f )

protected

Set an retry function with a unique name.

Empty name means no cancelling possible.

This will call the retry function f on the next scheduler loop. f should return RetryResult::DONE if it is successful and no repeat is required. Otherwise, returning RetryResult::RETRY will call f again in the future.

The first retry of f happens after initial_wait_time milliseconds. The delay between retries is increased by multiplying by backoff_increase_factor each time. If no backoff_increase_factor is supplied (default = 1.0), the wait time will stay constant.

The retry function f needs to accept a single argument: the number of attempts remaining. On the final retry of f, this value will be 0.

This retry function can also be cancelled by name via cancel_retry().

IMPORTANT: Do not rely on this having correct timing. This is only called from loop() and therefore can be significantly delayed.

REMARK: It is an error to supply a negative or zero backoff_increase_factor, and 1.0 will be used instead.

REMARK: The interval between retries is stored into a uint32_t, so this doesn't behave correctly if initial_wait_time * (backoff_increase_factor ** (max_attempts - 2)) overflows.

Parameters

name	The identifier for this retry function.
initial_wait_time	The time in ms before f is called again
max_attempts	The maximum number of executions
f	The function (or lambda) that should be called
backoff_increase_factor	time between retries is multiplied by this factor on every retry after the first

See also: cancel_retry()

Definition at line 66 of file component.cpp.

◆ set_retry() [2/2]

void esphome::Component::set_retry	(	uint32_t	initial_wait_time,
		uint8_t	max_attempts,
		std::function< RetryResult(uint8_t)> &&	f,
		float	backoff_increase_factor = 1.0f )

protected

Definition at line 170 of file component.cpp.

◆ set_setup_priority()

void esphome::Component::set_setup_priority ( float priority )

Definition at line 225 of file component.cpp.

◆ set_timeout() [1/2]

void esphome::Component::set_timeout	(	const std::string &	name,
		uint32_t	timeout,
		std::function< void()> &&	f )

protected

Set a timeout function with a unique name.

Similar to javascript's setTimeout(). Empty name means no cancelling possible.

IMPORTANT: Do not rely on this having correct timing. This is only called from loop() and therefore can be significantly delay. If you need exact timing please use hardware timers.

Parameters

name	The identifier for this timeout function.
timeout	The timeout in ms.
f	The function (or lambda) that should be called

See also: cancel_timeout()

Definition at line 75 of file component.cpp.

◆ set_timeout() [2/2]

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

protected

Definition at line 164 of file component.cpp.

◆ setup()

void esphome::Component::setup ( )

virtual

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.

Definition at line 54 of file component.cpp.

◆ should_warn_of_blocking()

bool esphome::Component::should_warn_of_blocking ( uint32_t blocking_time )

Definition at line 124 of file component.cpp.

◆ status_clear_error()

void esphome::Component::status_clear_error ( )

Definition at line 205 of file component.cpp.

◆ status_clear_warning()

void esphome::Component::status_clear_warning ( )

Definition at line 199 of file component.cpp.

◆ status_has_error()

bool esphome::Component::status_has_error ( ) const

Definition at line 181 of file component.cpp.

◆ status_has_warning()

bool esphome::Component::status_has_warning ( ) const

Definition at line 180 of file component.cpp.

◆ status_momentary_error()

void esphome::Component::status_momentary_error	(	const std::string &	name,
		uint32_t	length = 5000 )

Definition at line 215 of file component.cpp.

◆ status_momentary_warning()

void esphome::Component::status_momentary_warning	(	const std::string &	name,
		uint32_t	length = 5000 )

Definition at line 211 of file component.cpp.

◆ status_set_error()

void esphome::Component::status_set_error ( const char * message = "unspecified" )

Definition at line 190 of file component.cpp.

◆ status_set_warning()

void esphome::Component::status_set_warning ( const char * message = "unspecified" )

Definition at line 182 of file component.cpp.

◆ teardown()

virtual bool esphome::Component::teardown ( )

inlinevirtual

Called during teardown to allow component to gracefully finish operations.

Returns: true if teardown is complete, false if more time is needed

Reimplemented in esphome::api::APIServer.

Definition at line 117 of file component.h.

Field Documentation

◆ component_source_

const char* esphome::Component::component_source_ {nullptr}

protected

Definition at line 320 of file component.h.

◆ component_state_

uint8_t esphome::Component::component_state_ {0x00}

protected

State of this component - each bit has a purpose: Bits 0-1: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED) Bit 2: STATUS_LED_WARNING Bit 3: STATUS_LED_ERROR Bits 4-7: Unused - reserved for future expansion (50% of the bits are free)

Definition at line 318 of file component.h.

◆ error_message_

std::string esphome::Component::error_message_ {}

protected

Definition at line 322 of file component.h.

◆ setup_priority_override_

float esphome::Component::setup_priority_override_ {NAN}

protected

Definition at line 319 of file component.h.

◆ warn_if_blocking_over_

uint16_t esphome::Component::warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_MS}

protected

Warn if blocked for this many ms (max 65.5s)

Definition at line 321 of file component.h.

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

esphome/core/component.h
esphome/core/component.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ call()

◆ call_dump_config()

◆ call_loop()

◆ call_setup()

◆ can_proceed()

◆ cancel_defer()

◆ cancel_interval()

◆ cancel_retry()

◆ cancel_timeout()

◆ defer() [1/2]

◆ defer() [2/2]

◆ dump_config()

◆ get_actual_setup_priority()

◆ get_component_source()

◆ get_component_state()

◆ get_loop_priority()

◆ get_setup_priority()

◆ has_overridden_loop()

◆ is_failed()

◆ is_in_loop_state()

◆ is_ready()

◆ loop()

◆ mark_failed() [1/2]

◆ mark_failed() [2/2]

◆ on_powerdown()

◆ on_safe_shutdown()

◆ on_shutdown()

◆ reset_to_construction_state()

◆ set_component_source()

◆ set_interval() [1/2]

◆ set_interval() [2/2]

◆ set_retry() [1/2]

◆ set_retry() [2/2]

◆ set_setup_priority()

◆ set_timeout() [1/2]

◆ set_timeout() [2/2]

◆ setup()

◆ should_warn_of_blocking()

◆ status_clear_error()

◆ status_clear_warning()

◆ status_has_error()

◆ status_has_warning()

◆ status_momentary_error()

◆ status_momentary_warning()

◆ status_set_error()

◆ status_set_warning()

◆ teardown()

Field Documentation

◆ component_source_

◆ component_state_

◆ error_message_

◆ setup_priority_override_

◆ warn_if_blocking_over_