|
ESPHome 2026.11.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) |
| Component * | get_current_component () |
| void | set_current_source (const LogString *source) |
| const LogString * | get_current_source () |
| 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) | |
| 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. | |
| void | set_current_execution_context_ (Component *component, const LogString *source, uint32_t now) |
| 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} |
| const LogString * | current_source_ {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_ {false} |
| 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 453 of file application.cpp.
|
protected |
Definition at line 415 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 279 of file application.cpp.
|
inlineprotected |
Definition at line 429 of file application.h.
|
protected |
Definition at line 424 of file application.cpp.
|
protected |
Definition at line 461 of file application.cpp.
|
protected |
Definition at line 478 of file application.cpp.
| 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 238 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 244 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 290 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 318 of file application.h.
|
inline |
Get the area of this Application set by pre_setup().
Definition at line 156 of file application.h.
|
inline |
Definition at line 351 of file application.h.
| time_t esphome::Application::get_build_time | ( | ) |
Get the build time as a Unix timestamp.
Definition at line 563 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 549 of file application.cpp.
|
inline |
Get the comment of this Application as a string.
Definition at line 173 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 554 of file application.cpp.
| uint32_t esphome::Application::get_config_hash | ( | ) |
Get the config hash as a 32-bit integer.
Definition at line 559 of file application.cpp.
| uint32_t esphome::Application::get_config_version_hash | ( | ) |
Get the config hash extended with ESPHome version.
Definition at line 561 of file application.cpp.
|
inline |
Definition at line 107 of file application.h.
|
inline |
Definition at line 112 of file application.h.
|
inline |
Definition at line 339 of file application.h.
|
inline |
Get the friendly name of this Application set by pre_setup().
Definition at line 153 of file application.h.
|
inline |
Get the cached time in milliseconds from when the current component started its loop execution.
Definition at line 198 of file application.h.
|
inline |
Definition at line 220 of file application.h.
|
inline |
Get the name of this Application set by pre_setup().
Definition at line 150 of file application.h.
|
inline |
Definition at line 366 of file application.h.
|
inline |
Definition at line 179 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 326 of file application.h.
|
inline |
Make a loop iteration. Call this in your loop() function.
Definition at line 705 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 292 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 421 of file application.h.
|
protected |
Definition at line 66 of file application.cpp.
|
inline |
Definition at line 101 of file application.h.
|
inline |
Definition at line 135 of file application.h.
| void esphome::Application::run_powerdown_hooks | ( | ) |
Definition at line 316 of file application.cpp.
| void esphome::Application::run_safe_shutdown_hooks | ( | ) |
Definition at line 307 of file application.cpp.
| void esphome::Application::safe_reboot | ( | ) |
Definition at line 299 of file application.cpp.
|
inline |
Definition at line 222 of file application.h.
|
inlineprotected |
Definition at line 675 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 252 of file application.cpp.
|
inlineprotected |
Definition at line 405 of file application.h.
|
inline |
Definition at line 111 of file application.h.
|
inlineprotected |
Freshen the cached loop component start time. Called by Scheduler before each dispatch.
Definition at line 401 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
Sleep per wake is capped at 2 * WDT_FEED_INTERVAL_MS (except host and ESP8266); raise the platform watchdog timeout to sleep longer.
| loop_interval | The interval in milliseconds to run the core loop at. Defaults to 16 milliseconds. |
Definition at line 216 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 72 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 322 of file application.cpp.
|
protected |
|
protected |
|
inlinestatic |
Wake from any context (ISR, thread, callback).
Definition at line 387 of file application.h.
|
inlinestatic |
Wake from ISR (ESP8266). No task_woken arg — no FreeRTOS. Caller must be IRAM_ATTR.
Definition at line 380 of file application.h.
|
inlinestatic |
Wake from ISR (Zephyr). No task_woken arg — k_sem_give() handles ISR scheduling internally.
Definition at line 383 of file application.h.
|
inlinestatic |
Wake from ISR (ESP32 and LibreTiny).
Definition at line 377 of file application.h.
|
inline |
Wake the main event loop from another thread or callback.
Definition at line 373 of file application.h.
|
protected |
Definition at line 532 of file application.h.
|
protected |
Definition at line 544 of file application.h.
|
staticconstexpr |
Size of buffer required for build time string (including null terminator)
Definition at line 182 of file application.h.
|
protected |
Definition at line 390 of file application.h.
|
protected |
Definition at line 538 of file application.h.
|
protected |
Definition at line 490 of file application.h.
|
protected |
Definition at line 529 of file application.h.
|
protected |
Definition at line 491 of file application.h.
|
protected |
Definition at line 541 of file application.h.
|
protected |
Definition at line 526 of file application.h.
|
staticconstexpr |
Maximum size of the comment buffer (including null terminator)
Definition at line 167 of file application.h.
|
protected |
Definition at line 514 of file application.h.
|
protected |
Definition at line 535 of file application.h.
|
protected |
Definition at line 534 of file application.h.
|
protected |
Definition at line 517 of file application.h.
|
protected |
Definition at line 522 of file application.h.
|
protected |
Definition at line 519 of file application.h.
|
protected |
Definition at line 518 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 528 of file application.h.
|
protected |
Definition at line 513 of file application.h.
|
protected |
Definition at line 533 of file application.h.
| Scheduler esphome::Application::scheduler |
Definition at line 369 of file application.h.
|
protected |
Definition at line 557 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 279 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 240 of file application.h.