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

#include <application.h>

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
 
bool register_socket (struct lwip_sock *sock)
 Register/unregister a socket to be monitored for read events.
 
void unregister_socket (struct lwip_sock *sock)
 
bool register_socket_fd (int fd)
 Fallback select() path: monitors file descriptors.
 
void unregister_socket_fd (int fd)
 
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 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 = 3
 Minimum interval between real arch_feed_wdt() calls.
 

Protected Member Functions

friend void::setup ()
 
friend void::original_setup ()
 
bool is_socket_ready_ (int fd) const
 
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)
 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)
 
void ESPHOME_ALWAYS_INLINE before_loop_tasks_ (uint32_t loop_start_time)
 
void ESPHOME_ALWAYS_INLINE after_loop_tasks_ ()
 
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(), updates last_wdt_feed_, and re-dispatches the status LED.
 
void yield_with_select_ (uint32_t delay_ms)
 Perform a delay while also monitoring socket file descriptors for readiness.
 
void ESPHOME_ALWAYS_INLINE yield_with_select_ (uint32_t delay_ms)
 
void setup_wake_loop_threadsafe_ ()
 
void drain_wake_notifications_ ()
 

Protected Attributes

friend Component
 
Componentcurrent_component_ {nullptr}
 
FixedVector< Component * > looping_components_ {}
 
std::vector< struct lwip_sock * > monitored_sockets_
 
std::vector< int > socket_fds_
 
int wake_socket_fd_ {-1}
 
StringRef name_
 
StringRef friendly_name_
 
uint32_t last_loop_ {0}
 
uint32_t loop_component_start_time_ {0}
 
uint32_t last_wdt_feed_ {0}
 
int max_fd_ {-1}
 
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}
 
bool socket_fds_changed_ {false}
 
fd_set read_fds_ {}
 
fd_set base_read_fds_ {}
 
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 77 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 421 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 383 of file application.cpp.

◆ after_loop_tasks_()

void ESPHOME_ALWAYS_INLINE esphome::Application::after_loop_tasks_ ( )
inlineprotected

Definition at line 403 of file application.h.

◆ 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 247 of file application.cpp.

◆ before_loop_tasks_()

void ESPHOME_ALWAYS_INLINE esphome::Application::before_loop_tasks_ ( uint32_t loop_start_time)
inlineprotected

Definition at line 546 of file application.h.

◆ calculate_looping_components_()

void esphome::Application::calculate_looping_components_ ( )
inlineprotected

Definition at line 380 of file application.h.

◆ disable_component_loop_()

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

Definition at line 392 of file application.cpp.

◆ drain_wake_notifications_()

void esphome::Application::drain_wake_notifications_ ( )
inlineprotected

Definition at line 530 of file application.h.

◆ enable_component_loop_()

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

Definition at line 429 of file application.cpp.

◆ enable_pending_loops_()

void esphome::Application::enable_pending_loops_ ( )
protected

Definition at line 446 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 198 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 212 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(), updates last_wdt_feed_, and re-dispatches the status LED.

Out of line so the inline wrapper stays tiny.

Definition at line 221 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 + status LED update live in feed_wdt_slow_.

Definition at line 245 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 268 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 155 of file application.h.

◆ get_areas()

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

Definition at line 301 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 715 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 701 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 172 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 706 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 711 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 713 of file application.cpp.

◆ get_current_component()

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

Definition at line 120 of file application.h.

◆ get_devices()

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

Definition at line 289 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 152 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 206 of file application.h.

◆ get_loop_interval()

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

Definition at line 228 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 149 of file application.h.

◆ get_serial_proxies()

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

Definition at line 316 of file application.h.

◆ is_name_add_mac_suffix_enabled()

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

Definition at line 178 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 276 of file application.h.

◆ is_socket_ready_()

bool esphome::Application::is_socket_ready_ ( int fd) const
inlineprotected

Definition at line 363 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 577 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 82 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 104 of file application.h.

◆ reboot()

void esphome::Application::reboot ( )

Definition at line 260 of file application.cpp.

◆ register_area()

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

Definition at line 116 of file application.h.

◆ register_component_()

template<typename T >
void esphome::Application::register_component_ ( T * comp)
inlineprotected

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

Uses HasLoopOverride<T> which handles ambiguous &T::loop from multiple inheritance.

Definition at line 374 of file application.h.

◆ register_component_impl_()

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

Definition at line 60 of file application.cpp.

◆ register_device()

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

Definition at line 113 of file application.h.

◆ register_serial_proxy()

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

Definition at line 134 of file application.h.

◆ register_socket()

bool esphome::Application::register_socket ( struct lwip_sock * sock)

Register/unregister a socket to be monitored for read events.

WARNING: These functions are NOT thread-safe. They must only be called from the main loop. Fast select path: hooks netconn callback and registers for monitoring.

Returns
true if registration was successful, false if sock is null

Definition at line 499 of file application.cpp.

◆ register_socket_fd()

bool esphome::Application::register_socket_fd ( int fd)

Fallback select() path: monitors file descriptors.

NOTE: File descriptors >= FD_SETSIZE (typically 10 on ESP) will be rejected with an error.

Returns
true if registration was successful, false if fd exceeds limits

Definition at line 524 of file application.cpp.

◆ run_powerdown_hooks()

void esphome::Application::run_powerdown_hooks ( )

Definition at line 284 of file application.cpp.

◆ run_safe_shutdown_hooks()

void esphome::Application::run_safe_shutdown_hooks ( )

Definition at line 275 of file application.cpp.

◆ safe_reboot()

void esphome::Application::safe_reboot ( )

Definition at line 267 of file application.cpp.

◆ schedule_dump_config()

void esphome::Application::schedule_dump_config ( )
inline

Definition at line 230 of file application.h.

◆ set_current_component()

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

Definition at line 119 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 224 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 66 of file application.cpp.

◆ setup_wake_loop_threadsafe_()

void esphome::Application::setup_wake_loop_threadsafe_ ( )
protected

Definition at line 645 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 290 of file application.cpp.

◆ unregister_socket()

void esphome::Application::unregister_socket ( struct lwip_sock * sock)

Definition at line 508 of file application.cpp.

◆ unregister_socket_fd()

void esphome::Application::unregister_socket_fd ( int fd)

Definition at line 544 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 346 of file application.h.

◆ wake_loop_isrsafe()

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

Wake from ISR (ESP32 and LibreTiny).

Definition at line 342 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 338 of file application.h.

◆ yield_with_select_() [1/2]

void ESPHOME_ALWAYS_INLINE esphome::Application::yield_with_select_ ( uint32_t delay_ms)
inlineprotected

Perform a delay while also monitoring socket file descriptors for readiness.

Definition at line 575 of file application.cpp.

◆ yield_with_select_() [2/2]

void ESPHOME_ALWAYS_INLINE esphome::Application::yield_with_select_ ( uint32_t delay_ms)
inlineprotected

Field Documentation

◆ app_state_

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

Definition at line 480 of file application.h.

◆ areas_

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

Definition at line 502 of file application.h.

◆ base_read_fds_

fd_set esphome::Application::base_read_fds_ {}
protected

Definition at line 492 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 181 of file application.h.

◆ Component

friend esphome::Application::Component
protected

Definition at line 349 of file application.h.

◆ components_

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

Definition at line 496 of file application.h.

◆ current_component_

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

Definition at line 431 of file application.h.

◆ current_loop_index_

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

Definition at line 477 of file application.h.

◆ devices_

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

Definition at line 499 of file application.h.

◆ dump_config_at_

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

Definition at line 474 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 166 of file application.h.

◆ friendly_name_

StringRef esphome::Application::friendly_name_
protected

Definition at line 462 of file application.h.

◆ has_pending_enable_loop_requests_

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

Definition at line 483 of file application.h.

◆ in_loop_

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

Definition at line 482 of file application.h.

◆ last_loop_

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

Definition at line 465 of file application.h.

◆ last_wdt_feed_

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

Definition at line 467 of file application.h.

◆ loop_component_start_time_

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

Definition at line 466 of file application.h.

◆ loop_interval_

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

Definition at line 475 of file application.h.

◆ looping_components_

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

Definition at line 450 of file application.h.

◆ looping_components_active_end_

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

Definition at line 476 of file application.h.

◆ max_fd_

int esphome::Application::max_fd_ {-1}
protected

Definition at line 470 of file application.h.

◆ monitored_sockets_

std::vector<struct lwip_sock *> esphome::Application::monitored_sockets_
protected

Definition at line 452 of file application.h.

◆ name_

StringRef esphome::Application::name_
protected

Definition at line 461 of file application.h.

◆ name_add_mac_suffix_

bool esphome::Application::name_add_mac_suffix_
protected

Definition at line 481 of file application.h.

◆ read_fds_

fd_set esphome::Application::read_fds_ {}
protected

Definition at line 491 of file application.h.

◆ scheduler

Scheduler esphome::Application::scheduler

Definition at line 319 of file application.h.

◆ serial_proxies_

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

Definition at line 515 of file application.h.

◆ socket_fds_

std::vector<int> esphome::Application::socket_fds_
protected

Definition at line 454 of file application.h.

◆ socket_fds_changed_

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

Definition at line 486 of file application.h.

◆ wake_socket_fd_

int esphome::Application::wake_socket_fd_ {-1}
protected

Definition at line 457 of file application.h.

◆ WDT_FEED_INTERVAL_MS

uint32_t esphome::Application::WDT_FEED_INTERVAL_MS = 3
staticconstexpr

Minimum interval between real arch_feed_wdt() calls.

Chosen to keep the rate of HAL pokes low while still being small enough that any plausible watchdog timeout (seconds) has orders of magnitude of safety margin.

Definition at line 235 of file application.h.


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