ESPHome 2026.6.0-dev
Loading...
Searching...
No Matches
esphome::Application Class Reference

#include <application.h>

Data Structures

class  ComponentPhaseGuard
 

Public Member Functions

void pre_setup (char *name, size_t name_len, char *friendly_name, size_t friendly_name_len)
 Pre-setup with MAC suffix: overwrites placeholder in mutable static buffers with actual MAC.
 
void pre_setup (const char *name, size_t name_len, const char *friendly_name, size_t friendly_name_len)
 Pre-setup without MAC suffix: StringRef points directly at const string literals in flash.
 
void register_device (Device *device)
 
void register_area (Area *area)
 
void set_current_component (Component *component)
 
Componentget_current_component ()
 
void register_serial_proxy (serial_proxy::SerialProxy *proxy)
 
void setup ()
 Reserve space for components to avoid memory fragmentation.
 
void ESPHOME_ALWAYS_INLINE loop ()
 Make a loop iteration. Call this in your loop() function.
 
const StringRefget_name () const
 Get the name of this Application set by pre_setup().
 
const StringRefget_friendly_name () const
 Get the friendly name of this Application set by pre_setup().
 
const char * get_area () const
 Get the area of this Application set by pre_setup().
 
void get_comment_string (std::span< char, ESPHOME_COMMENT_SIZE_MAX > buffer)
 Copy the comment string into the provided buffer.
 
std::string get_comment ()
 Get the comment of this Application as a string.
 
bool is_name_add_mac_suffix_enabled () const
 
uint32_t get_config_hash ()
 Get the config hash as a 32-bit integer.
 
uint32_t get_config_version_hash ()
 Get the config hash extended with ESPHome version.
 
time_t get_build_time ()
 Get the build time as a Unix timestamp.
 
void get_build_time_string (std::span< char, BUILD_TIME_STR_SIZE > buffer)
 Copy the build time string into the provided buffer Buffer must be BUILD_TIME_STR_SIZE bytes (compile-time enforced)
 
 ESPDEPRECATED ("Use get_build_time_string() instead. Removed in 2026.7.0", "2026.1.0") std
 Get the build time as a string (deprecated, use get_build_time_string() instead)
 
uint32_t IRAM_ATTR HOT get_loop_component_start_time () const
 Get the cached time in milliseconds from when the current component started its loop execution.
 
void set_loop_interval (uint32_t loop_interval)
 Set the target interval with which to run the loop() calls.
 
uint32_t get_loop_interval () const
 
void schedule_dump_config ()
 
void feed_wdt ()
 Feed the task watchdog.
 
void ESPHOME_ALWAYS_INLINE feed_wdt_with_time (uint32_t time)
 Feed the task watchdog, hot entry.
 
void reboot ()
 
void safe_reboot ()
 
void run_safe_shutdown_hooks ()
 
void run_powerdown_hooks ()
 
void teardown_components (uint32_t timeout_ms)
 Teardown all components with a timeout.
 
uint8_t get_app_state () const
 Return the public app state status bits (STATUS_LED_* only).
 
bool is_setup_complete () const
 True once Application::setup() has finished walking all components and finalized the initial status flags.
 
const auto & get_devices ()
 
const auto & get_areas ()
 
auto & get_serial_proxies () const
 
void wake_loop_threadsafe ()
 Wake the main event loop from another thread or callback.
 

Static Public Member Functions

static void IRAM_ATTR wake_loop_isrsafe (BaseType_t *px)
 Wake from ISR (ESP32 and LibreTiny).
 
static void IRAM_ATTR ESPHOME_ALWAYS_INLINE wake_loop_isrsafe ()
 Wake from ISR (ESP8266). No task_woken arg — no FreeRTOS. Caller must be IRAM_ATTR.
 
static void wake_loop_isrsafe ()
 Wake from ISR (Zephyr). No task_woken arg — k_sem_give() handles ISR scheduling internally.
 
static void IRAM_ATTR wake_loop_any_context ()
 Wake from any context (ISR, thread, callback).
 

Data Fields

Scheduler scheduler
 

Static Public Attributes

static constexpr size_t ESPHOME_COMMENT_SIZE_MAX = 256
 Maximum size of the comment buffer (including null terminator)
 
static constexpr size_t BUILD_TIME_STR_SIZE = 26
 Size of buffer required for build time string (including null terminator)
 
static constexpr uint32_t WDT_FEED_INTERVAL_MS = 2000
 Minimum interval between real arch_feed_wdt() calls.
 
static constexpr uint32_t STATUS_LED_DISPATCH_INTERVAL_MS = 100
 Dispatch interval for the status LED update.
 

Protected Member Functions

friend void::setup ()
 
friend void::original_setup ()
 
void set_loop_component_start_time_ (uint32_t now)
 Freshen the cached loop component start time. Called by Scheduler before each dispatch.
 
bool any_component_has_status_flag_ (uint8_t flag) const
 Walk all registered components looking for any whose component_state_ has the given flag set.
 
template<typename T >
void register_component_ (T *comp, uint8_t source_index=0)
 Register a component, detecting loop() override at compile time.
 
void register_component_impl_ (Component *comp, bool has_loop)
 
void calculate_looping_components_ ()
 
void add_looping_components_by_state_ (bool match_loop_done)
 
void disable_component_loop_ (Component *component)
 
void enable_component_loop_ (Component *component)
 
void enable_pending_loops_ ()
 
void activate_looping_component_ (uint16_t index)
 
uint32_t ESPHOME_ALWAYS_INLINE scheduler_tick_ (uint32_t now)
 
void __attribute__ ((noinline)) process_dump_config_()
 Process dump_config output one component per loop iteration.
 
void feed_wdt_slow_ (uint32_t time)
 Slow path for feed_wdt(): actually calls arch_feed_wdt() and updates last_wdt_feed_.
 
void service_status_led_slow_ (uint32_t time)
 Slow path for the status_led dispatch rate limit.
 

Protected Attributes

friend Component
 
Componentcurrent_component_ {nullptr}
 
FixedVector< Component * > looping_components_ {}
 
StringRef name_
 
StringRef friendly_name_
 
uint32_t last_loop_ {0}
 
uint32_t loop_component_start_time_ {0}
 
uint32_t last_wdt_feed_ {0}
 
uint32_t last_status_led_service_ {0}
 
uint16_t dump_config_at_ {std::numeric_limits<uint16_t>::max()}
 
uint16_t loop_interval_ {16}
 
uint16_t looping_components_active_end_ {0}
 
uint16_t current_loop_index_ {0}
 
uint8_t app_state_ {0}
 
bool name_add_mac_suffix_
 
bool in_loop_ {false}
 
volatile bool has_pending_enable_loop_requests_ {false}
 
StaticVector< Component *, ESPHOME_COMPONENT_COUNT > components_ {}
 
StaticVector< Device *, ESPHOME_DEVICE_COUNT > devices_ {}
 
StaticVector< Area *, ESPHOME_AREA_COUNT > areas_ {}
 
StaticVector< serial_proxy::SerialProxy *, SERIAL_PROXY_COUNT > serial_proxies_ {}
 

Detailed Description

Definition at line 67 of file application.h.

Member Function Documentation

◆ __attribute__()

void esphome::Application::__attribute__ ( (noinline) )
protected

Process dump_config output one component per loop iteration.

Extracted from loop() to keep cold startup/reconnect logging out of the hot path. Caller must ensure dump_config_at_ < components_.size().

◆ activate_looping_component_()

void esphome::Application::activate_looping_component_ ( uint16_t index)
protected

Definition at line 424 of file application.cpp.

◆ add_looping_components_by_state_()

void esphome::Application::add_looping_components_by_state_ ( bool match_loop_done)
protected

Definition at line 386 of file application.cpp.

◆ any_component_has_status_flag_()

bool esphome::Application::any_component_has_status_flag_ ( uint8_t flag) const
protected

Walk all registered components looking for any whose component_state_ has the given flag set.

Used by Component::status_clear_*_slow_path_() (which is a friend) to decide whether to clear the corresponding bit on this->app_state_ (the app-wide "any component has this status" indicator).

Definition at line 250 of file application.cpp.

◆ calculate_looping_components_()

void esphome::Application::calculate_looping_components_ ( )
inlineprotected

Definition at line 423 of file application.h.

◆ disable_component_loop_()

void esphome::Application::disable_component_loop_ ( Component * component)
protected

Definition at line 395 of file application.cpp.

◆ enable_component_loop_()

void esphome::Application::enable_component_loop_ ( Component * component)
protected

Definition at line 432 of file application.cpp.

◆ enable_pending_loops_()

void esphome::Application::enable_pending_loops_ ( )
protected

Definition at line 449 of file application.cpp.

◆ ESPDEPRECATED()

esphome::Application::ESPDEPRECATED ( "Use get_build_time_string() instead. Removed in 2026.7.0" ,
"2026.1.0"  )
inline

Get the build time as a string (deprecated, use get_build_time_string() instead)

Definition at line 195 of file application.h.

◆ feed_wdt()

void esphome::Application::feed_wdt ( )

Feed the task watchdog.

Cold entry — callers without a millis() timestamp in hand. Out of line to keep call sites tiny.

Definition at line 209 of file application.cpp.

◆ feed_wdt_slow_()

void HOT esphome::Application::feed_wdt_slow_ ( uint32_t time)
protected

Slow path for feed_wdt(): actually calls arch_feed_wdt() and updates last_wdt_feed_.

Out of line so the inline wrapper stays tiny. Does NOT touch status_led — that's gated separately via service_status_led_slow_ because the two rate limits have very different safe ranges (~ seconds for WDT, < 250 ms for LED blink rendering).

Definition at line 215 of file application.cpp.

◆ feed_wdt_with_time()

void ESPHOME_ALWAYS_INLINE esphome::Application::feed_wdt_with_time ( uint32_t time)
inline

Feed the task watchdog, hot entry.

Callers that already have a millis() timestamp pay only a load + sub + branch on the common (no-op) path. The actual arch feed lives in feed_wdt_slow_. When USE_STATUS_LED is compiled in, also gates a separate (shorter) interval for dispatching status_led so the LED blink pattern stays readable even though arch_feed_wdt pokes are now rate-limited at WDT_FEED_INTERVAL_MS. The two rate limits are independent so raising WDT_FEED_INTERVAL_MS does not distort the LED cadence.

Definition at line 294 of file application.h.

◆ get_app_state()

uint8_t esphome::Application::get_app_state ( ) const
inline

Return the public app state status bits (STATUS_LED_* only).

Internal bookkeeping bits like APP_STATE_SETUP_COMPLETE are masked out so external readers (status_led components, etc.) never see them.

Definition at line 322 of file application.h.

◆ get_area()

const char * esphome::Application::get_area ( ) const
inline

Get the area of this Application set by pre_setup().

Definition at line 152 of file application.h.

◆ get_areas()

const auto & esphome::Application::get_areas ( )
inline

Definition at line 355 of file application.h.

◆ get_build_time()

time_t esphome::Application::get_build_time ( )

Get the build time as a Unix timestamp.

Definition at line 534 of file application.cpp.

◆ get_build_time_string()

void esphome::Application::get_build_time_string ( std::span< char, BUILD_TIME_STR_SIZE > buffer)

Copy the build time string into the provided buffer Buffer must be BUILD_TIME_STR_SIZE bytes (compile-time enforced)

Definition at line 520 of file application.cpp.

◆ get_comment()

std::string esphome::Application::get_comment ( )
inline

Get the comment of this Application as a string.

Definition at line 169 of file application.h.

◆ get_comment_string()

void esphome::Application::get_comment_string ( std::span< char, ESPHOME_COMMENT_SIZE_MAX > buffer)

Copy the comment string into the provided buffer.

Definition at line 525 of file application.cpp.

◆ get_config_hash()

uint32_t esphome::Application::get_config_hash ( )

Get the config hash as a 32-bit integer.

Definition at line 530 of file application.cpp.

◆ get_config_version_hash()

uint32_t esphome::Application::get_config_version_hash ( )

Get the config hash extended with ESPHome version.

Definition at line 532 of file application.cpp.

◆ get_current_component()

Component * esphome::Application::get_current_component ( )
inline

Definition at line 108 of file application.h.

◆ get_devices()

const auto & esphome::Application::get_devices ( )
inline

Definition at line 343 of file application.h.

◆ get_friendly_name()

const StringRef & esphome::Application::get_friendly_name ( ) const
inline

Get the friendly name of this Application set by pre_setup().

Definition at line 149 of file application.h.

◆ get_loop_component_start_time()

uint32_t IRAM_ATTR HOT esphome::Application::get_loop_component_start_time ( ) const
inline

Get the cached time in milliseconds from when the current component started its loop execution.

Definition at line 203 of file application.h.

◆ get_loop_interval()

uint32_t esphome::Application::get_loop_interval ( ) const
inline

Definition at line 225 of file application.h.

◆ get_name()

const StringRef & esphome::Application::get_name ( ) const
inline

Get the name of this Application set by pre_setup().

Definition at line 146 of file application.h.

◆ get_serial_proxies()

auto & esphome::Application::get_serial_proxies ( ) const
inline

Definition at line 370 of file application.h.

◆ is_name_add_mac_suffix_enabled()

bool esphome::Application::is_name_add_mac_suffix_enabled ( ) const
inline

Definition at line 175 of file application.h.

◆ is_setup_complete()

bool esphome::Application::is_setup_complete ( ) const
inline

True once Application::setup() has finished walking all components and finalized the initial status flags.

Before this point, the slow-setup busy-wait may be forcing STATUS_LED_WARNING on, and status_clear_* intentionally skips its walk-and-clear step so the forced bit doesn't get wiped. Stored as a free bit on app_state_ (bit 6) to avoid costing additional RAM.

Definition at line 330 of file application.h.

◆ loop()

void ESPHOME_ALWAYS_INLINE esphome::Application::loop ( )
inline

Make a loop iteration. Call this in your loop() function.

Definition at line 594 of file application.h.

◆ pre_setup() [1/2]

void esphome::Application::pre_setup ( char * name,
size_t name_len,
char * friendly_name,
size_t friendly_name_len )
inline

Pre-setup with MAC suffix: overwrites placeholder in mutable static buffers with actual MAC.

Definition at line 72 of file application.h.

◆ pre_setup() [2/2]

void esphome::Application::pre_setup ( const char * name,
size_t name_len,
const char * friendly_name,
size_t friendly_name_len )
inline

Pre-setup without MAC suffix: StringRef points directly at const string literals in flash.

Definition at line 92 of file application.h.

◆ reboot()

void esphome::Application::reboot ( )

Definition at line 263 of file application.cpp.

◆ register_area()

void esphome::Application::register_area ( Area * area)
inline

Definition at line 104 of file application.h.

◆ register_component_()

template<typename T >
void esphome::Application::register_component_ ( T * comp,
uint8_t source_index = 0 )
inlineprotected

Register a component, detecting loop() override at compile time.

Uses HasLoopOverride<T> which handles ambiguous &T::loop from multiple inheritance. Optionally sets the component source index in the same call to avoid emitting a separate set_component_source_() line in generated code.

Definition at line 415 of file application.h.

◆ register_component_impl_()

void esphome::Application::register_component_impl_ ( Component * comp,
bool has_loop )
protected

Definition at line 53 of file application.cpp.

◆ register_device()

void esphome::Application::register_device ( Device * device)
inline

Definition at line 101 of file application.h.

◆ register_serial_proxy()

void esphome::Application::register_serial_proxy ( serial_proxy::SerialProxy * proxy)
inline

Definition at line 131 of file application.h.

◆ run_powerdown_hooks()

void esphome::Application::run_powerdown_hooks ( )

Definition at line 287 of file application.cpp.

◆ run_safe_shutdown_hooks()

void esphome::Application::run_safe_shutdown_hooks ( )

Definition at line 278 of file application.cpp.

◆ safe_reboot()

void esphome::Application::safe_reboot ( )

Definition at line 270 of file application.cpp.

◆ schedule_dump_config()

void esphome::Application::schedule_dump_config ( )
inline

Definition at line 227 of file application.h.

◆ scheduler_tick_()

uint32_t ESPHOME_ALWAYS_INLINE esphome::Application::scheduler_tick_ ( uint32_t now)
inlineprotected

Definition at line 564 of file application.h.

◆ service_status_led_slow_()

void HOT esphome::Application::service_status_led_slow_ ( uint32_t time)
protected

Slow path for the status_led dispatch rate limit.

Runs the status_led component's loop() based on its state (LOOP / LOOP_DONE with status bits set), and updates last_status_led_service_. Out of line to keep the feed_wdt_with_time hot path a couple of load+branch sequences.

Definition at line 223 of file application.cpp.

◆ set_current_component()

void esphome::Application::set_current_component ( Component * component)
inline

Definition at line 107 of file application.h.

◆ set_loop_component_start_time_()

void esphome::Application::set_loop_component_start_time_ ( uint32_t now)
inlineprotected

Freshen the cached loop component start time. Called by Scheduler before each dispatch.

Definition at line 403 of file application.h.

◆ set_loop_interval()

void esphome::Application::set_loop_interval ( uint32_t loop_interval)
inline

Set the target interval with which to run the loop() calls.

If the loop() method takes longer than the target interval, ESPHome won't sleep in loop(), but if the time spent in loop() is small than the target, ESPHome will delay at the end of the App.loop() method.

This is done to conserve power: In most use-cases, high-speed loop() calls are not required and degrade power consumption.

Each component can request a high frequency loop execution by using the HighFrequencyLoopRequester helper in helpers.h

Note: This method is not called by ESPHome core code. It is only used by lambda functions in YAML configurations or by external components.

Parameters
loop_intervalThe interval in milliseconds to run the core loop at. Defaults to 16 milliseconds.

Definition at line 221 of file application.h.

◆ setup()

void esphome::Application::setup ( )

Reserve space for components to avoid memory fragmentation.

Set up all the registered components. Call this at the end of your setup() function.

Definition at line 59 of file application.cpp.

◆ teardown_components()

void esphome::Application::teardown_components ( uint32_t timeout_ms)

Teardown all components with a timeout.

Parameters
timeout_msMaximum time to wait for teardown in milliseconds

Definition at line 293 of file application.cpp.

◆ void::original_setup()

esphome::Application::void::original_setup ( )
protected

◆ void::setup()

esphome::Application::void::setup ( )
protected

◆ wake_loop_any_context()

static void IRAM_ATTR esphome::Application::wake_loop_any_context ( )
inlinestatic

Wake from any context (ISR, thread, callback).

Definition at line 391 of file application.h.

◆ wake_loop_isrsafe() [1/3]

static void IRAM_ATTR ESPHOME_ALWAYS_INLINE esphome::Application::wake_loop_isrsafe ( )
inlinestatic

Wake from ISR (ESP8266). No task_woken arg — no FreeRTOS. Caller must be IRAM_ATTR.

Definition at line 384 of file application.h.

◆ wake_loop_isrsafe() [2/3]

static void esphome::Application::wake_loop_isrsafe ( )
inlinestatic

Wake from ISR (Zephyr). No task_woken arg — k_sem_give() handles ISR scheduling internally.

Definition at line 387 of file application.h.

◆ wake_loop_isrsafe() [3/3]

static void IRAM_ATTR esphome::Application::wake_loop_isrsafe ( BaseType_t * px)
inlinestatic

Wake from ISR (ESP32 and LibreTiny).

Definition at line 381 of file application.h.

◆ wake_loop_threadsafe()

void esphome::Application::wake_loop_threadsafe ( )
inline

Wake the main event loop from another thread or callback.

See also
esphome::wake_loop_threadsafe() in wake.h for platform details.

Definition at line 377 of file application.h.

Field Documentation

◆ app_state_

uint8_t esphome::Application::app_state_ {0}
protected

Definition at line 525 of file application.h.

◆ areas_

StaticVector<Area *, ESPHOME_AREA_COUNT> esphome::Application::areas_ {}
protected

Definition at line 537 of file application.h.

◆ BUILD_TIME_STR_SIZE

size_t esphome::Application::BUILD_TIME_STR_SIZE = 26
staticconstexpr

Size of buffer required for build time string (including null terminator)

Definition at line 178 of file application.h.

◆ Component

friend esphome::Application::Component
protected

Definition at line 394 of file application.h.

◆ components_

StaticVector<Component *, ESPHOME_COMPONENT_COUNT> esphome::Application::components_ {}
protected

Definition at line 531 of file application.h.

◆ current_component_

Component* esphome::Application::current_component_ {nullptr}
protected

Definition at line 484 of file application.h.

◆ current_loop_index_

uint16_t esphome::Application::current_loop_index_ {0}
protected

Definition at line 522 of file application.h.

◆ devices_

StaticVector<Device *, ESPHOME_DEVICE_COUNT> esphome::Application::devices_ {}
protected

Definition at line 534 of file application.h.

◆ dump_config_at_

uint16_t esphome::Application::dump_config_at_ {std::numeric_limits<uint16_t>::max()}
protected

Definition at line 519 of file application.h.

◆ ESPHOME_COMMENT_SIZE_MAX

size_t esphome::Application::ESPHOME_COMMENT_SIZE_MAX = 256
staticconstexpr

Maximum size of the comment buffer (including null terminator)

Definition at line 163 of file application.h.

◆ friendly_name_

StringRef esphome::Application::friendly_name_
protected

Definition at line 507 of file application.h.

◆ has_pending_enable_loop_requests_

volatile bool esphome::Application::has_pending_enable_loop_requests_ {false}
protected

Definition at line 528 of file application.h.

◆ in_loop_

bool esphome::Application::in_loop_ {false}
protected

Definition at line 527 of file application.h.

◆ last_loop_

uint32_t esphome::Application::last_loop_ {0}
protected

Definition at line 510 of file application.h.

◆ last_status_led_service_

uint32_t esphome::Application::last_status_led_service_ {0}
protected

Definition at line 515 of file application.h.

◆ last_wdt_feed_

uint32_t esphome::Application::last_wdt_feed_ {0}
protected

Definition at line 512 of file application.h.

◆ loop_component_start_time_

uint32_t esphome::Application::loop_component_start_time_ {0}
protected

Definition at line 511 of file application.h.

◆ loop_interval_

uint16_t esphome::Application::loop_interval_ {16}
protected

Definition at line 520 of file application.h.

◆ looping_components_

FixedVector<Component *> esphome::Application::looping_components_ {}
protected

Definition at line 503 of file application.h.

◆ looping_components_active_end_

uint16_t esphome::Application::looping_components_active_end_ {0}
protected

Definition at line 521 of file application.h.

◆ name_

StringRef esphome::Application::name_
protected

Definition at line 506 of file application.h.

◆ name_add_mac_suffix_

bool esphome::Application::name_add_mac_suffix_
protected

Definition at line 526 of file application.h.

◆ scheduler

Scheduler esphome::Application::scheduler

Definition at line 373 of file application.h.

◆ serial_proxies_

StaticVector<serial_proxy::SerialProxy *, SERIAL_PROXY_COUNT> esphome::Application::serial_proxies_ {}
protected

Definition at line 550 of file application.h.

◆ STATUS_LED_DISPATCH_INTERVAL_MS

uint32_t esphome::Application::STATUS_LED_DISPATCH_INTERVAL_MS = 100
staticconstexpr

Dispatch interval for the status LED update.

Deliberately shorter than WDT_FEED_INTERVAL_MS because the status LED error blink has a 250 ms period (status_led.cpp:ERROR_PERIOD_MS) and a 150 ms on-window; the dispatch cadence must be short enough to render that blink without aliasing. Sampling every 100 ms yields an on/off observation inside every error period with headroom for the 250 ms warning on-window.

Definition at line 283 of file application.h.

◆ WDT_FEED_INTERVAL_MS

static constexpr uint32_t esphome::Application::WDT_FEED_INTERVAL_MS = 2000
staticconstexpr

Minimum interval between real arch_feed_wdt() calls.

Sized so the outer feed in Application::loop() is effectively rate-limited across both the normal ~62 Hz cadence and worst-case wake-storm scenarios (e.g. external stacks like OpenThread posting frequent wake notifications). Component loops and scheduler items still feed after every op, so any op exceeding this threshold triggers a real feed naturally. Safety margins vs. platform watchdog timeouts:

  • ESP32 task WDT (user-configurable): ~5x <– auto-scaled below
  • ESP8266 soft WDT (~1.6 s): ~16x <– 100 ms feed (see USE_ESP8266 below)
  • ESP8266 HW WDT (~6 s): ~60x
  • BK72xx HW WDT (10 s): ~5x <– platform override below

Definition at line 244 of file application.h.


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