|
ESPHome 2026.6.0-dev
|
#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) |
| Component * | get_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 StringRef & | get_name () const |
| Get the name of this Application set by pre_setup(). | |
| const StringRef & | get_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 |
| Component * | current_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_ {} |
Definition at line 67 of file application.h.
|
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().
|
protected |
Definition at line 424 of file application.cpp.
|
protected |
Definition at line 386 of file application.cpp.
|
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.
|
inlineprotected |
Definition at line 423 of file application.h.
|
protected |
Definition at line 395 of file application.cpp.
|
protected |
Definition at line 432 of file application.cpp.
|
protected |
Definition at line 449 of file application.cpp.
|
inline |
Get the build time as a string (deprecated, use get_build_time_string() instead)
Definition at line 195 of file application.h.
| 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.
|
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.
|
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.
|
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.
|
inline |
Get the area of this Application set by pre_setup().
Definition at line 152 of file application.h.
|
inline |
Definition at line 355 of file application.h.
| time_t esphome::Application::get_build_time | ( | ) |
Get the build time as a Unix timestamp.
Definition at line 534 of file application.cpp.
| 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.
|
inline |
Get the comment of this Application as a string.
Definition at line 169 of file application.h.
| 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.
| uint32_t esphome::Application::get_config_hash | ( | ) |
Get the config hash as a 32-bit integer.
Definition at line 530 of file application.cpp.
| uint32_t esphome::Application::get_config_version_hash | ( | ) |
Get the config hash extended with ESPHome version.
Definition at line 532 of file application.cpp.
|
inline |
Definition at line 108 of file application.h.
|
inline |
Definition at line 343 of file application.h.
|
inline |
Get the friendly name of this Application set by pre_setup().
Definition at line 149 of file application.h.
|
inline |
Get the cached time in milliseconds from when the current component started its loop execution.
Definition at line 203 of file application.h.
|
inline |
Definition at line 225 of file application.h.
|
inline |
Get the name of this Application set by pre_setup().
Definition at line 146 of file application.h.
|
inline |
Definition at line 370 of file application.h.
|
inline |
Definition at line 175 of file application.h.
|
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.
|
inline |
Make a loop iteration. Call this in your loop() function.
Definition at line 594 of file application.h.
|
inline |
Pre-setup with MAC suffix: overwrites placeholder in mutable static buffers with actual MAC.
Definition at line 72 of file application.h.
|
inline |
Pre-setup without MAC suffix: StringRef points directly at const string literals in flash.
Definition at line 92 of file application.h.
| void esphome::Application::reboot | ( | ) |
Definition at line 263 of file application.cpp.
|
inline |
Definition at line 104 of file application.h.
|
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.
|
protected |
Definition at line 53 of file application.cpp.
|
inline |
Definition at line 101 of file application.h.
|
inline |
Definition at line 131 of file application.h.
| void esphome::Application::run_powerdown_hooks | ( | ) |
Definition at line 287 of file application.cpp.
| void esphome::Application::run_safe_shutdown_hooks | ( | ) |
Definition at line 278 of file application.cpp.
| void esphome::Application::safe_reboot | ( | ) |
Definition at line 270 of file application.cpp.
|
inline |
Definition at line 227 of file application.h.
|
inlineprotected |
Definition at line 564 of file application.h.
|
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.
|
inline |
Definition at line 107 of file application.h.
|
inlineprotected |
Freshen the cached loop component start time. Called by Scheduler before each dispatch.
Definition at line 403 of file application.h.
|
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.
| loop_interval | The interval in milliseconds to run the core loop at. Defaults to 16 milliseconds. |
Definition at line 221 of file application.h.
| 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.
| void esphome::Application::teardown_components | ( | uint32_t | timeout_ms | ) |
Teardown all components with a timeout.
| timeout_ms | Maximum time to wait for teardown in milliseconds |
Definition at line 293 of file application.cpp.
|
protected |
|
protected |
|
inlinestatic |
Wake from any context (ISR, thread, callback).
Definition at line 391 of file application.h.
|
inlinestatic |
Wake from ISR (ESP8266). No task_woken arg — no FreeRTOS. Caller must be IRAM_ATTR.
Definition at line 384 of file application.h.
|
inlinestatic |
Wake from ISR (Zephyr). No task_woken arg — k_sem_give() handles ISR scheduling internally.
Definition at line 387 of file application.h.
|
inlinestatic |
Wake from ISR (ESP32 and LibreTiny).
Definition at line 381 of file application.h.
|
inline |
Wake the main event loop from another thread or callback.
Definition at line 377 of file application.h.
|
protected |
Definition at line 525 of file application.h.
|
protected |
Definition at line 537 of file application.h.
|
staticconstexpr |
Size of buffer required for build time string (including null terminator)
Definition at line 178 of file application.h.
|
protected |
Definition at line 394 of file application.h.
|
protected |
Definition at line 531 of file application.h.
|
protected |
Definition at line 484 of file application.h.
|
protected |
Definition at line 522 of file application.h.
|
protected |
Definition at line 534 of file application.h.
|
protected |
Definition at line 519 of file application.h.
|
staticconstexpr |
Maximum size of the comment buffer (including null terminator)
Definition at line 163 of file application.h.
|
protected |
Definition at line 507 of file application.h.
|
protected |
Definition at line 528 of file application.h.
|
protected |
Definition at line 527 of file application.h.
|
protected |
Definition at line 510 of file application.h.
|
protected |
Definition at line 515 of file application.h.
|
protected |
Definition at line 512 of file application.h.
|
protected |
Definition at line 511 of file application.h.
|
protected |
Definition at line 520 of file application.h.
|
protected |
Definition at line 503 of file application.h.
|
protected |
Definition at line 521 of file application.h.
|
protected |
Definition at line 506 of file application.h.
|
protected |
Definition at line 526 of file application.h.
| Scheduler esphome::Application::scheduler |
Definition at line 373 of file application.h.
|
protected |
Definition at line 550 of file application.h.
|
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.
|
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:
Definition at line 244 of file application.h.