ESPHome Developer Documentation | Blog

ClimateTraits Boolean Accessors Removed in Favor of Feature Flags

Thu, 14 May 2026 00:00:00 GMT

The ten deprecated ClimateTraits::get/set_supports_* accessors have been removed. External climate components must migrate to the add_feature_flags() / has_feature_flags() API introduced in 2025.11.0 — the 6-month deprecation window has elapsed.

This is a breaking change for external components in ESPHome 2026.5.0 and later.

Background

PR #16289: Remove deprecations scheduled for 2026.5.0

In 2025.11.0 the old boolean getter/setter pairs were superseded by an add_feature_flags() / has_feature_flags() bitmask API on ClimateTraits. The booleans were kept as thin shims marked ESPDEPRECATED("...", "2025.11.0") to give external components a 6-month window. That window has now closed and the shims are gone. (The same release also migrated other ClimateTraits enum sets to packed-bitmask storage in a separate change; see the climate entity class optimizations post for that adjacent story.)

The replacement API has been the canonical way to express climate capabilities since 2025.11.0, and every in-tree climate component (heat-pump IR codecs, mini-split bridges, thermostat platform, etc.) has been on it for months.

What’s Changing

The following ten methods have been removed from ClimateTraits:

Removed method	Replacement flag
`set_supports_current_temperature(bool)`	`add_feature_flags(climate::CLIMATE_SUPPORTS_CURRENT_TEMPERATURE)`
`get_supports_current_temperature()`	`has_feature_flags(climate::CLIMATE_SUPPORTS_CURRENT_TEMPERATURE)`
`set_supports_current_humidity(bool)`	`add_feature_flags(climate::CLIMATE_SUPPORTS_CURRENT_HUMIDITY)`
`get_supports_current_humidity()`	`has_feature_flags(climate::CLIMATE_SUPPORTS_CURRENT_HUMIDITY)`
`set_supports_two_point_target_temperature(bool)`	`add_feature_flags(climate::CLIMATE_REQUIRES_TWO_POINT_TARGET_TEMPERATURE)`
`get_supports_two_point_target_temperature()`	`has_feature_flags(climate::CLIMATE_REQUIRES_TWO_POINT_TARGET_TEMPERATURE)`
`set_supports_target_humidity(bool)`	`add_feature_flags(climate::CLIMATE_SUPPORTS_TARGET_HUMIDITY)`
`get_supports_target_humidity()`	`has_feature_flags(climate::CLIMATE_SUPPORTS_TARGET_HUMIDITY)`
`set_supports_action(bool)`	`add_feature_flags(climate::CLIMATE_SUPPORTS_ACTION)`
`get_supports_action()`	`has_feature_flags(climate::CLIMATE_SUPPORTS_ACTION)`

Watch for `two_point_target_temperature`

set_supports_two_point_target_temperature(true) maps to CLIMATE_REQUIRES_TWO_POINT_TARGET_TEMPERATURE, not CLIMATE_SUPPORTS_TWO_POINT_TARGET_TEMPERATURE. The bitmask flag name reflects the actual semantic — when set, the climate device requires both target_temperature_low and target_temperature_high to be specified instead of a single target_temperature. If your old code called set_supports_two_point_target_temperature(true), this is the flag you want — but double-check that your device actually requires both setpoints (rare for single-setpoint heat-pump and IR-controlled units) rather than just optionally supporting them, since the new name reflects the stricter semantic.

Who This Affects

External climate components in C++ that still call the old accessors. A GitHub code search for the removed identifiers across public repositories turned up ~20+ such components — heat-pump IR drivers, mini-split bridges, brand-specific climate integrations (Haier, Daikin IR, Ecodan, Sanyou, Sharp, Mill Heat, …).

YAML configurations are not affected. Built-in climate platforms migrated in 2025.11.0 and any user-facing config keys are unchanged.

Migration Guide

// Before (no longer compiles)
ClimateTraits traits;
traits.set_supports_current_temperature(true);
traits.set_supports_action(true);
traits.set_supports_two_point_target_temperature(true);

if (traits.get_supports_action()) {
  // ...
}

// After
ClimateTraits traits;
traits.add_feature_flags(climate::CLIMATE_SUPPORTS_CURRENT_TEMPERATURE);
traits.add_feature_flags(climate::CLIMATE_SUPPORTS_ACTION);
traits.add_feature_flags(climate::CLIMATE_REQUIRES_TWO_POINT_TARGET_TEMPERATURE);

if (traits.has_feature_flags(climate::CLIMATE_SUPPORTS_ACTION)) {
  // ...
}

add_feature_flags() accepts a bitwise OR of multiple flags, so a long sequence of individual calls can be condensed:

traits.add_feature_flags(
    climate::CLIMATE_SUPPORTS_CURRENT_TEMPERATURE |
    climate::CLIMATE_SUPPORTS_CURRENT_HUMIDITY |
    climate::CLIMATE_SUPPORTS_TARGET_HUMIDITY |
    climate::CLIMATE_SUPPORTS_ACTION);

has_feature_flags() is a bitwise-AND check: it returns true when any of the bits in the argument are set on the traits. For most capability checks you’ll be testing one flag at a time, which behaves exactly like the old get_supports_*() boolean — pass a single flag. If you pass several OR’d together, the result is “is at least one of these supported,” not “are all of these supported.”

Timeline

2025.11.0: Feature-flag API added; boolean accessors marked ESPDEPRECATED.
2026.5.0: Boolean accessors removed.

Finding Code That Needs Updates

# Find any of the ten removed boolean accessors in one pass.
# The two alternation groups isolate the accessor side (set/get) and the trait name,
# so the output line tells you exactly which one to migrate.
grep -rEn '(set|get)_supports_(current_temperature|current_humidity|two_point_target_temperature|target_humidity|action)' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #16289 — Remove climate / ektf2232 deprecations
2025.11.0 Climate optimizations blog post — the deprecation that started the clock
2026.4.0 Climate fan custom mode storage blog post — related climate-API tightening

Default-Constructed PollingComponent No Longer Polls

Thu, 14 May 2026 00:00:00 GMT

The no-argument PollingComponent() constructor now initializes the update interval to SCHEDULER_DONT_RUN (UINT32_MAX) instead of 1. External components that subclass PollingComponent, instantiate it with no constructor argument, and never call set_update_interval() will stop polling. Pass an interval to the constructor or call set_update_interval() explicitly.

This is a breaking change for external components in ESPHome 2026.5.0 and later.

Background

PR #15832: Default PollingComponent() to not run when codegen is bypassed

Codegen-driven components always pass the user’s update_interval: through to the constructor (or call set_update_interval() explicitly), so they were never affected by the default value. The default only mattered when an external component bypassed codegen — wrote PollingComponent() directly in C++ and never set an interval.

The old default of 1 was a workaround. Before the recent scheduler rework (#15516), the inefficient scheduler informally throttled interval=0 and interval=1 into something close to plain loop() behavior, so components that forgot to set an interval got “some” polling. After the scheduler became efficient and #15799 / #15831 hardened the runtime coercion path, an explicit 1 ms interval would have meant 1000 polls per second — starving the watchdog and masking any real symptoms.

No author who forgets to set an interval actually wants 1000 polls per second. The correct behavior when an interval is genuinely missing is to fail loudly — don’t poll at all, log Update Interval: never, and let the developer notice.

What’s Changing

// Before
PollingComponent() : update_interval_(1) {}
// → polled every 1 ms when never configured

// After
PollingComponent() : update_interval_(SCHEDULER_DONT_RUN) {}
// → does not poll until set_update_interval() is called

SCHEDULER_DONT_RUN is UINT32_MAX. The scheduler already treats this value as disabled, and LOG_UPDATE_INTERVAL already prints Update Interval: never for this value — so the dump_config output is also self-describing. See PR #15832 for the full picture of how the scheduler and Component handle this sentinel.

Who This Affects

External components written in C++ that meet all three of these conditions:

Inherit from PollingComponent in C++
Construct the instance via the no-argument PollingComponent() constructor (not PollingComponent(interval))
Never call set_update_interval() afterwards

Components driven by ESPHome’s Python code generation (cv.polling_component_schema(...), sensor.sensor_schema(), etc.) are unaffected — the codegen always passes the configured (or schema-default) interval through to the constructor, so the default value never matters for them.

A known example is psvanstrom/esphome-p1reader, which independently switched to PollingComponent(10) ahead of this change.

Migration Guide

Pick whichever fits your component:

// Option 1: pass the interval to the constructor (recommended for fixed-interval components)
class MyComponent : public PollingComponent {
 public:
  MyComponent() : PollingComponent(60000) {}  // 60 s
  // ...
};

// Option 2: keep the no-arg constructor and let codegen set the interval before registration.
class MyComponent : public PollingComponent {
 public:
  void update() override;       // your periodic work
  void dump_config() override;
  // (no need to override setup() or pass an interval to the constructor —
  // the Python codegen below calls set_update_interval() for you)
};

# Python side — use polling_component_schema; cg.register_component() handles set_update_interval
# automatically when CONF_UPDATE_INTERVAL is in config.
CONFIG_SCHEMA = cv.Schema({
    cv.GenerateID(): cv.declare_id(MyComponent),
    # ...
}).extend(cv.polling_component_schema("60s"))

async def to_code(config):
    var = cg.new_Pvariable(config[CONF_ID])
    await cg.register_component(var, config)   # ← this sets the update interval for you

cg.register_component() (in esphome/cpp_helpers.py) calls set_update_interval(config[CONF_UPDATE_INTERVAL]) before it registers the variable with App, so by the time App::register_component() triggers call_setup() → start_poller(), update_interval_ already holds the user’s configured value.

WARNING

Don’t call set_update_interval() from inside setup()

PollingComponent::call_setup() runs start_poller() before the subclass’s setup() — see the implementation (search for PollingComponent::call_setup). By the time setup() executes, the scheduler interval has already been registered with whatever update_interval_ held at registration time (SCHEDULER_DONT_RUN if the default constructor was used). Calling set_update_interval() from setup() only updates the field — it does not re-register the interval, so polling stays disabled.

The header comment for call_setup explicitly says the poller starts first “allowing setup to cancel it if desired.” So if you really need a runtime decision inside setup() to change the cadence, the supported pattern is stop_poller() → set_update_interval(ms) → start_poller(). Setting the interval before registration (Option 2 above, or via the constructor in Option 1) is much cleaner.

// Option 3: if you want the component to behave like a plain Component (no polling),
// inherit from Component instead — that's the new explicit way to express "no polling."
class MyComponent : public Component {
  // ...
};

If you see Update Interval: never in your device’s startup log and the component used to poll, you’re hitting this case — pick option 1 or 2.

Finding Code That Needs Updates

# Find subclasses of PollingComponent (also catches forward declarations and
# struct/class variations on the same line).
grep -rEn 'class .* PollingComponent|struct .* PollingComponent|: *public *PollingComponent' your_component/

# Find no-arg PollingComponent constructor calls (likely affected)
grep -rEn 'PollingComponent\(\)' your_component/

# Find whether set_update_interval is ever called
grep -rn 'set_update_interval' your_component/

If your component has PollingComponent() (no argument) and no set_update_interval() call anywhere, you’ll need to add one of the three options above before 2026.5.0.

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15832 — Default PollingComponent() to not run when codegen is bypassed
PR #15831 — Prerequisite: encode the old runtime coerce as a compile-time no-op
PR #15799 — Earlier scheduler hardening that made the old default actually mean 1 ms

FloatOutput Power Scaling Fields Gated Behind USE_OUTPUT_FLOAT_POWER_SCALING

Thu, 14 May 2026 00:00:00 GMT

The min_power_ / max_power_ / zero_means_zero_ fields and their setters on FloatOutput are now gated behind a new USE_OUTPUT_FLOAT_POWER_SCALING build flag. The codegen turns the flag on automatically whenever a YAML config references the feature. Lambdas that call id(out).set_min_power(...) / set_max_power(...) / set_zero_means_zero(...) without any matching YAML key or action will now fail to compile with a clear static_assert pointing at the one-line YAML fix.

This is a breaking change for external components and YAML configs that drive power scaling exclusively from lambdas in ESPHome 2026.5.0 and later.

Background

PR #15998: Gate FloatOutput power scaling fields behind USE_OUTPUT_FLOAT_POWER_SCALING

min_power_, max_power_, and zero_means_zero_ cost 12 bytes per instance on every PWM channel, DAC channel, LEDC output, and dimmer-chip channel — paid by every device with any output: block, regardless of whether the user touches the feature. Inside esphome/esphome, total YAML usage of min_power / max_power / zero_means_zero is on the order of 17 lines, mostly in test fixtures. The output.set_min_power / output.set_max_power runtime actions (added in #8934) have no callers outside the action’s own test fixture.

This follows the same pattern the entity base classes already use — USE_POWER_SUPPLY gates BinaryOutput::power_, and USE_ENTITY_ICON / USE_ENTITY_DEVICE_CLASS / USE_ENTITY_UNIT_OF_MEASUREMENT gate string members of EntityBase. Configs that opt in pay the cost; configs that don’t get it stripped.

Measured savings

Built with the unmodified example configs from devices.esphome.io for two real ESP8266 PWM lights — neither uses min_power / max_power / zero_means_zero / scaling actions:

H801 RGBW LED Controller — 5 PWM outputs (RGB + cold-white + warm-white, the “RGBWW” light: platform):

Metric	Baseline	PR	Δ
RAM (.bss + .data)	30,416 B	30,352 B	-64 B
Flash	346,047 B	345,799 B	-248 B
`sizeof(ESP8266PWM)`	40 B	28 B	-12 B

H802 RGBW LED Controller — 4 PWM outputs: -48 B RAM, -248 B flash, same 12 B per channel.

Per-instance .bss savings scale linearly with channel count (12 B × N). Flash savings (~248 B per binary) come from the elided multiply/subtract in set_level() and the dropped scaling-related strings/branches in dump_config().

What’s Changing

USE_OUTPUT_FLOAT_POWER_SCALING is a new cg.add_define() flag that controls four things at compile time on FloatOutput:

min_power_, max_power_, zero_means_zero_ member fields
set_min_power(), set_max_power(), set_zero_means_zero() setters
The min/max/zero-means-zero math inside FloatOutput::set_level()
The SetMinPowerAction / SetMaxPowerAction action templates

The Python codegen turns the flag on automatically whenever:

A min_power: / max_power: / zero_means_zero: key is set on any output: entry, or
An output.set_min_power / output.set_max_power action is registered anywhere in the config.

zero_means_zero_ now has a default initializer (it was undefined before, hidden behind an unconditional setter call driven by the schema default).

Who This Affects

You are affected only if all three of these are true:

You do not set min_power, max_power, or zero_means_zero on any of your outputs in YAML, and
You do not use the output.set_min_power or output.set_max_power automation actions anywhere, and
You do call id(...).set_min_power(...), id(...).set_max_power(...), or id(...).set_zero_means_zero(...) directly from a lambda:.

If any of those is false, your config is unaffected and behaves exactly as before.

External hardware-driver components that ship their own C++ and call these setters from setup() or dump_config() fall in this bucket — typically inverter / charger / DC-DC bridges that auto-configure scaling per detected hardware (e.g. several of the syssi/esphome-* repos).

Migration Guide

YAML lambda users — add one line of YAML

The build will fail with a clear error at your lambda:

error: static assertion failed: set_min_power() requires USE_OUTPUT_FLOAT_POWER_SCALING.
To enable it, add 'min_power: 0%' (or any value) to one output entry in your YAML — the
codegen will then keep the scaling fields.

The fix is one line of YAML — add this to any one output entry:

output:
  - platform: esp8266_pwm
    id: out
    pin: 4
    min_power: 0%        # ← add this (or max_power: 100%, or zero_means_zero: true)

min_power: 0% / max_power: 100% are the existing defaults, so this changes no runtime behavior — it just tells the codegen “compile in runtime power scaling so my lambda can use it.”

External component authors — declare the define

If your component ships its own output.* C++ and depends on the scaling setters, you have two options:

(Recommended) Add the YAML key on any output. The codegen will turn the define on for you. This is the same flow regular users follow.
If you cannot rely on user YAML, declare the define in your component’s Python codegen:
```
import esphome.codegen as cg

async def to_code(config):
    cg.add_define("USE_OUTPUT_FLOAT_POWER_SCALING")
    # ...
```
The output component will then include the fields and setters regardless of YAML.

Finding Code That Needs Updates

# C++ — find calls to the gated setters from lambdas or component code
grep -rEn 'set_min_power|set_max_power|set_zero_means_zero' your_component/

# YAML — find lambdas that call the setters
grep -rEn 'set_min_power|set_max_power|set_zero_means_zero' your_configs/

# YAML — check if any output entry already enables the feature (no action needed if so).
# Drop ^ to also catch top-level entries; expect false positives from unrelated
# components that happen to use a same-named key — visually confirm matches are
# under an output: entry before concluding you've already opted in.
grep -rEn '(min_power|max_power|zero_means_zero):' your_configs/

Questions?

If you have questions about migrating your external component or configuration, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15998 — Gate FloatOutput power scaling fields behind USE_OUTPUT_FLOAT_POWER_SCALING
Output component documentation — min_power / max_power / zero_means_zero reference
Pattern reference: USE_POWER_SUPPLY (gates BinaryOutput::power_), USE_ENTITY_ICON / USE_ENTITY_DEVICE_CLASS / USE_ENTITY_UNIT_OF_MEASUREMENT (gate EntityBase strings)

Main Loop Cadence Decoupled from Scheduler Wake Timing

Thu, 14 May 2026 00:00:00 GMT

Every component’s loop() now runs at the configured loop_interval_ (default ~62 Hz). Previously, when other scheduler activity was running — set_interval / set_timeout / PollingComponent updates with sub-loop_interval_ cadences — the component phase got pulled forward up to ~128 Hz; quiet configs with no such scheduler entries were unaffected and always ran at the documented rate. Background events (MQTT RX, USB RX, BLE events, ESPNOW, camera, micro_wake_word, speaker, USB host/CDC, lwIP socket) still wake their component within one tick via the existing wake_loop_* paths. App.set_loop_interval() — the documented knob for power savings — finally works.

This is a behavior change in ESPHome 2026.5.0 and later with no API break, but it affects every component whose loop() implicitly depended on running at ~2× the configured rate when scheduler activity was driving the pull-forward.

Background

PR #15792: decouple main loop cadence from scheduler wake timing

What was happening

Sampling runtime stats over 60 s on a typical ESP32 IDF config (api + esp32_ble + esp32_ble_tracker + bluetooth_proxy + debug + a couple of sensors) at the default loop_interval_ = 16 ms:

Component	Before	After	What’s counted
`api`	7650 / 60 s ≈ 128 Hz	3720 / 60 s ≈ 62 Hz	`loop()` calls
`esp32_ble`	7650 ≈ 128 Hz	3720 ≈ 62 Hz	`loop()` calls
`esp32_ble_tracker`	7650 ≈ 128 Hz	3720 ≈ 62 Hz	`loop()` calls
`debug`	7651 ≈ 128 Hz	3720 ≈ 62 Hz	`loop()` calls
`bluetooth_proxy`	589 ≈ 10 Hz	599 ≈ 10 Hz	100 ms `set_interval` (unaffected)

Every component with a real loop() was running at ~2× the configured loop_interval_. 62 Hz is what the documentation has always promised; the 128 Hz was emergent behavior.

Why it happened

Application::loop() bounded its sleep by min(loop_interval_ - elapsed, next_schedule_in()) with a delay_time / 2 floor. If the scheduler had any entry due sooner than loop_interval_ / 2, the loop slept for loop_interval_ / 2 and ran the entire component phase again — every component’s loop() got pulled forward by whatever else happened to be scheduling work. The effect was config-dependent and non-local: adding one scheduled item anywhere silently shifted every other component’s cadence.

Two recent trends made this bite harder: (1) more components are PollingComponents, each of which is a set_interval under the hood; (2) more components use set_interval / set_timeout directly for retries, debouncing, animations, and protocol timing. App.set_loop_interval() — the documented knob for power savings — was silently defeated by the same coupling.

Removing the floor is safe now because wake_loop_threadsafe() is accessible everywhere as of 2026.4.0 (see the 2026.4.0 wake_loop blog post). Any component that needs to wake the loop sooner than loop_interval_ has a proper way to do it without the floor papering over missing wake-ups.

What’s Changing

Application::loop() is restructured into two independent phases:

Phase A (every tick): drain wake notifications, run scheduler.call(), feed the watchdog.
Phase B (gated): iterate registered components. Runs when any of these is true:
- loop_interval_ has elapsed since the last component phase, or
- HighFrequencyLoopRequester is active, or
- a background producer set the wake-request flag via wake_loop_* (MQTT RX, USB RX, BLE events, ESPNOW, camera, micro_wake_word, speaker, USB host/CDC, lwIP socket, or a component-level enable_loop_soon_any_context()).

Sleep between ticks is min(time-until-next-component-phase, next_schedule_in()). A scheduler-timer wake runs only Phase A; a wake_loop_threadsafe() wake runs Phase B too so the producer’s component can drain its queued work.

The delay_time / 2 floor is removed entirely. Zero-delay set_interval(0, ...) registrations no longer busy-loop the component phase, because Phase B is gated separately from scheduler timer expiry. HighFrequencyLoopRequester remains the correct mechanism for “I need fast wakes sometimes.” Zero-delay defer() is unaffected.

Ordering preserved: defer() → FIFO before components; scheduled items before components when both are due; scheduled callbacks still main-thread-only; the WDT is fed ≥ once per tick.

Who This Affects

Every component that overrides loop() — in-tree and external alike — but most won’t notice. Specifically:

Components whose loop() depended on running at ~128 Hz — animations stepping per loop tick, debounce / state-machine timing keyed to loop count, anything that implicitly assumed the doubled rate. Those will now step at ~62 Hz when scheduler activity was previously providing the pull-forward.
Background-event producers — already wired up. Every existing wake_loop_* caller (MQTT RX, USB RX, BLE events, ESPNOW, camera, micro_wake_word, speaker, USB host/CDC, lwIP socket, and per-component enable_loop_soon_any_context() calls) now sets a wake-request flag before signalling the platform so that Phase B runs in the next tick. No action needed in callers.
Components that need sub-loop_interval_ cadence — see the migration guide below for the preferred event-driven pattern. HighFrequencyLoopRequester is available but should be a last resort.
Power-managed configs using App.set_loop_interval() — this knob now actually saves power. If you previously bumped loop_interval_ to 100 ms and saw no power reduction, expect a real change this release.

Migration Guide

For most components, do nothing. Your loop() will simply run at the documented rate.

If your component genuinely needs to run more often than loop_interval_, the preferred pattern is event-driven, not high-frequency: keep the loop disabled while there’s nothing to do, and have your event source re-enable it. The Component base class has the primitives you need:

API	Where you call it	Purpose
`this->disable_loop()`	Main thread (typically the tail of `loop()` once your work is done)	Take the component out of the iteration list — its `loop()` won’t be called again until something re-enables it.
`this->enable_loop()`	Main thread	Put the component back in the iteration list.
`this->enable_loop_soon_any_context()`	ISR, FreeRTOS task, or any thread	ISR-safe enable. Sets a pending flag that the main loop drains on the next tick. There is intentionally no `disable_loop_soon_any_context()` — use `disable_loop()` from `loop()` itself.
`App.wake_loop_threadsafe()`	FreeRTOS task / non-ISR thread (BLE callbacks, network events, platform task callbacks)	Forces Phase B in the next tick globally; lets every enabled component drain queued work without changing per-component enable state.
`App.wake_loop_any_context()` / `App.wake_loop_isrsafe()`	ISR context	ISR-safe global wake. See Waking from ISR for per-platform IRAM and `xHigherPriorityTaskWoken` notes.

The typical event-driven pattern looks like this:

#include "esphome/core/application.h"
#include "esphome/core/component.h"

class MyEventDrivenComponent : public Component {
 public:
  void setup() override {
    // ... register hardware / callbacks ...
    this->disable_loop();  // nothing to do until an event arrives
  }

  void loop() override {
    this->drain_queued_events_();
    if (this->queue_empty_()) {
      this->disable_loop();  // re-enable from on_event()
    }
  }

  // Called from a FreeRTOS task / network callback / etc.
  void on_event(Event e) {
    this->queue_.push(e);
    this->enable_loop_soon_any_context();  // ISR-safe; also wakes the main loop
  }
};

enable_loop_soon_any_context() both flips the component’s enable bit and wakes the main loop, so loop() runs within a tick of the event landing — regardless of where loop_interval_ is set. This composes cleanly with App.set_loop_interval(...) for power-managed configs: idle current drops because the loop sleeps; latency stays low because events wake it.

WARNING

HighFrequencyLoopRequester is a last resort

HighFrequencyLoopRequester::start() keeps Phase B running every tick unconditionally. It exists for genuinely time-critical workloads (e.g. tight bit-banged protocol timing where you can’t wait for an event), and even there, scoping the request as narrowly as possible — start() only while the critical work is in flight, stop() immediately after — is the supported usage. If you’re reaching for it because “I just need faster wakes,” prefer disable_loop() / enable_loop_soon_any_context() first — it gets you the same latency at a fraction of the wakeup count.

The full architectural rationale, including how to decide between loop(), set_interval(), and the scheduler under the new cadence rules, is documented in Choosing Between loop() and the Scheduler.

Finding Code That Needs Updates

# Components with a loop() override (the work you might want to review).
# The narrower `override`-style pattern catches modern code; the wider one
# also picks up older external components that declared `void loop();` without
# `override` and is precisely where you're most likely to find code that
# implicitly depended on the old ~128 Hz cadence.
grep -rn 'void loop() override' your_component/
grep -rEn 'void[[:space:]]+loop[[:space:]]*\([[:space:]]*\)' your_component/

# Zero-delay set_interval calls — previously busy-looped the component phase
grep -rEn 'set_interval\(\s*0\s*,' your_component/

# Background producers that should be using a wake primitive
grep -rn 'wake_loop_threadsafe\|enable_loop_soon_any_context\|wake_loop_any_context\|wake_loop_isrsafe' your_component/

# Components already opted in to high-frequency wakes (no action needed)
grep -rn 'HighFrequencyLoopRequester' your_component/

If your loop() was implicitly relying on the ~128 Hz emergent rate and ~62 Hz is now insufficient, switch to HighFrequencyLoopRequester (for sustained fast wakes) or a wake primitive driven from your event source (for event-driven wakes).

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15792 — decouple main loop cadence from scheduler wake timing
PR #15846 — prerequisite WDT-feed rate-limit adjustment
Architecture doc: loop control and main-loop cadence
2026.4.0 blog: wake_loop moved to core — provided the unconditional wake primitive that made this fix safe

Modbus Server Split Out of modbus_controller

Thu, 14 May 2026 00:00:00 GMT

Modbus server mode has been split out of modbus_controller into a new dedicated modbus_server component. Configurations that used modbus_controller as a Modbus server (the role: server setting lives on the modbus: bus, not on modbus_controller) must move their server_registers: and server_courtesy_response: blocks under a new top-level modbus_server: entry.

This is a breaking change for YAML configurations using server mode in ESPHome 2026.5.0 and later.

Background

PR #15509: Split modbus_server from modbus_controller

Server-mode register handling was wedged into modbus_controller alongside its client-mode polling. The two roles share a transport (the modbus: bus) but almost nothing else: server mode dispatches inbound requests to user lambdas, while client mode polls outbound register reads on a schedule. Keeping both in the same component made the controller heavier than it needed to be, complicated review of server-side fixes, and prevented the server logic from sharing helpers with future modbus-based components.

modbus_server is a thin Component that implements modbus::ModbusDevice and owns the register table plus the optional courtesy response, with no client-mode machinery. The migration in this PR is intentionally close to a copy/paste — functional improvements to server mode (out-of-range handling, multi-register transactions, parser fixes, etc.) come in follow-up PRs.

Flash savings (approximate)

Configuration	Before	After
Pure server	`modbus_controller` ~4.5 KB	`modbus_server` ~1.8 KB
Pure client	`modbus_controller` ~6.4 KB	`modbus_controller` ~3.9 KB

Devices that previously combined client and server in one modbus_controller will now have two separate components, but each is much smaller.

What’s Changing

YAML keys moved

Old (under `modbus_controller`)	New (under `modbus_server`)
`server_registers:`	`registers:`
`server_courtesy_response:`	`courtesy_response:`

`modbus_controller` is now client-only

role: server on the bus is still supported — that selects the transport-layer role. What changed is that the register table is no longer accepted on modbus_controller. Put it on modbus_server instead.

Who This Affects

YAML configurations that used modbus_controller as a Modbus server — typically battery management bridges (BMS protocol bridges, yamBMS forks), EVSE bridges, energy/inverter proxies, and any “act as a register slave” project. Pure-client modbus_controller users (the more common case — reading from third-party Modbus devices) are not affected.

Migration Guide

# Before
modbus:
  role: server

modbus_controller:
  - address: 1
    server_registers:
      - address: 0x0001
        value_type: U_WORD
        read_lambda: "return id(my_sensor).state;"
    server_courtesy_response:
      enabled: true
      register_value: 0

# After
modbus:
  role: server

modbus_server:
  - address: 1
    registers:
      - address: 0x0001
        value_type: U_WORD
        read_lambda: "return id(my_sensor).state;"
    courtesy_response:
      enabled: true
      register_value: 0

A modbus: bus has a single role and your device occupies one side of it: modbus_controller requires role: client, modbus_server requires role: server, and the bus schema enforces this — you cannot mix the two on the same modbus: instance. Modbus only allows one client per bus, so the “both on one device” pattern was never valid; if a previous config had server_registers: under a client-mode modbus_controller, those registers were silently inactive. Run a second modbus: bus on a different UART if you need a device that’s both a server on one wire and a client on another.

Timeline

2026.5.0: Server-mode keys removed from modbus_controller; new modbus_server component active.

This is a clean break — there is no deprecation period or migration shim. modbus_controller configs that still contain server_registers: or server_courtesy_response: will fail validation on 2026.5.0. (For contrast, the earlier modbus_controller → modbus::helpers namespace refactor in 2026.4.0 kept deprecation shims through 2026.10.0 — that pattern doesn’t apply here because there’s no in-place rename to forward, and the affected configs are caught at config-validation time with a precise error message rather than at runtime.)

Finding Code That Needs Updates

# YAML — find server-mode keys still under modbus_controller.
# -E (extended regex) keeps the alternation portable across GNU and BSD/macOS grep.
grep -rEn 'server_registers:|server_courtesy_response:' your_configs/

Questions?

If you have questions about migrating your configuration, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15509 — Split modbus_server from modbus_controller
PR #15291 and PR #14172 — Earlier helper-function refactor that enabled this split (blog post)
ESPHome Modbus Server documentation (new page)
ESPHome Modbus Controller documentation

RingBuffer Moved Out of Core Into ring_buffer Helper Component

Thu, 14 May 2026 00:00:00 GMT

RingBuffer has moved from esphome/core/ring_buffer.h into a new ring_buffer helper component at esphome/components/ring_buffer/ring_buffer.h under the esphome::ring_buffer namespace. The old location is deprecated and will be removed in ESPHome 2026.11.0.

This is a breaking change for external components in ESPHome 2026.5.0 and later.

Background

PR #16298: Move core ring buffer to helper component

The core RingBuffer was an ESP32-only implementation used exclusively by audio components — audio, i2s_audio, micro_wake_word, mixer, resampler, sound_level, speaker, voice_assistant. Nothing outside that audio cluster touches it. Living in esphome/core/ meant:

The ring_buffer.h header was parsed for every build, regardless of platform or whether audio was in use. Linker stripping kept unused code out of the final binary, but build-time parsing and tooling overhead applied universally.
Changes to RingBuffer couldn’t be staged in an external_components PR — they always required a core change.
The ESP32-only implementation lived alongside genuinely cross-platform core code.

Moving it into a real component (esphome::ring_buffer::RingBuffer) lets audio consumers AUTO_LOAD it the same way every other shared utility is pulled in, and opens the door to iterating on the implementation without touching core.

The old esphome/core/ring_buffer.h header now forwards to the new location and will be removed in 2026.11.0 per the standard 6-month policy. The behavior of the shim depends on whether your component declares AUTO_LOAD = ["ring_buffer"]:

With AUTO_LOAD: the shim forwards esphome::RingBuffer to esphome::ring_buffer::RingBuffer via a using alias marked ESPDEPRECATED(...). Code keeps compiling, but each use emits a deprecation warning at the call site.
Without AUTO_LOAD: the new header isn’t on the include path, so the shim fires a hard #error telling you exactly what to do: “esphome/components/ring_buffer/ring_buffer.h not found. Add ‘ring_buffer’ to your component’s AUTO_LOAD list to use esphome::ring_buffer::RingBuffer.” The build fails immediately rather than producing a confusing missing-header diagnostic from somewhere else.

What’s Changing

C++ include and namespace

// Before
#include "esphome/core/ring_buffer.h"

std::unique_ptr<esphome::RingBuffer> buf = esphome::RingBuffer::create(1024);

// After
#include "esphome/components/ring_buffer/ring_buffer.h"

std::unique_ptr<esphome::ring_buffer::RingBuffer> buf =
    esphome::ring_buffer::RingBuffer::create(1024);

Python codegen — declare `AUTO_LOAD`

Any component whose C++ uses RingBuffer must auto-load the helper component so the build system pulls in its sources. In your component’s __init__.py:

AUTO_LOAD = ["ring_buffer"]

If your component already has an AUTO_LOAD, append "ring_buffer" to it.

Who This Affects

External audio / streaming components that use RingBuffer directly — typically:

Custom microphone / I²S audio pipelines
Speaker / playback components
Streaming protocol bridges (BLE audio, Nordic UART, etc.)
Forks or extensions of micro_wake_word, voice_assistant, speaker

All in-tree consumers (audio, i2s_audio, micro_wake_word, mixer, resampler, sound_level, speaker, voice_assistant) were migrated in esphome/esphome#16298.

Non-audio components are unaffected.

Migration Guide

Update the include path:

#include "esphome/core/ring_buffer.h"
#include "esphome/components/ring_buffer/ring_buffer.h"

Update the namespace at every callsite:
```
esphome::RingBuffer::create(size);
esphome::ring_buffer::RingBuffer::create(size);
```
If you have many callsites, you can avoid editing each one by adding a using esphome::ring_buffer::RingBuffer; declaration inside your component’s own namespace block so RingBuffer resolves correctly from unqualified references:
```
namespace esphome::my_component {

using esphome::ring_buffer::RingBuffer;   // ← here, not at file scope

class MyComponent : public Component {
  std::unique_ptr<RingBuffer> buf_;        // unqualified still works
};

}  // namespace esphome::my_component
```
Avoid putting the using at file scope (outside any namespace) — that pulls the name into the global namespace, which works for ::RingBuffer lookups but doesn’t help code inside esphome::my_component that previously relied on esphome::RingBuffer being a sibling.
Add AUTO_LOAD in your component’s __init__.py:
```
AUTO_LOAD = ["ring_buffer"]
```

The API of RingBuffer itself (create(), read(), write(), write_without_replacement(), available(), etc.) is unchanged — only its location and namespace move.

Timeline

2026.5.0: New location active; old esphome/core/ring_buffer.h deprecated (compile warning).
2026.11.0: Old header removed.

Finding Code That Needs Updates

# C++ — find the old include
grep -rn 'esphome/core/ring_buffer.h' your_component/

# C++ — find old namespace usage
grep -rn 'esphome::RingBuffer' your_component/

# Python — find AUTO_LOAD declarations that need ring_buffer added
grep -rn 'AUTO_LOAD' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #16298 — Move core ring buffer to helper component

BLE Event Handler Dispatch Devirtualized

Thu, 09 Apr 2026 00:00:00 GMT

Virtual handler interfaces (GAPEventHandler, GAPScanEventHandler, GATTcEventHandler, GATTsEventHandler, BLEStatusEventHandler) have been replaced with callback-based dispatch. External components that inherit from these interfaces must update their registration approach.

This is a developer breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15310: Devirtualize BLE event handler dispatch

The previous virtual handler pattern required vtable lookups and multiple-inheritance this-pointer adjustment thunks on every BLE event dispatch. The new approach uses StaticCallbackManager with lambda callbacks, eliminating vtable overhead. Each lambda captures a single pointer (fits in Callback inline storage, no heap allocation).

Before (virtual dispatch):

ESP32BLE::loop()
  → vtable load → indirect call → thunk this-adjust → gap_scan_event_handler()

After (callback dispatch):

ESP32BLE::loop()
  → StaticCallbackManager::call() → Callback::fn_(ctx_, args) → direct call

What’s Changing

The following virtual handler base classes are removed:

GAPEventHandler
GAPScanEventHandler
GATTcEventHandler
GATTsEventHandler
BLEStatusEventHandler

Registration now uses add_*_callback() methods with lambdas instead of register_*_handler() with object pointers. The Python register_* helper functions are unchanged — they generate lambda-based callbacks internally.

Who This Affects

External ESP32 BLE components that inherit from the virtual handler classes.

Migration Guide

C++ changes

Remove the handler base class from your inheritance list
Remove override from handler methods

// Before
class MyComponent : public Component, public GAPScanEventHandler {
  void gap_scan_event_handler(const BLEScanResult &scan_result) override;
};

// After
class MyComponent : public Component {
  void gap_scan_event_handler(const BLEScanResult &scan_result);
};

Python codegen

The Python register_* helper functions are unchanged — no Python changes needed:

# This still works — generates lambda-based callbacks internally
esp32_ble.register_gap_scan_event_handler(parent, var)

Supporting Multiple ESPHome Versions

// Before 2026.4.0, inherit from the handler class
// After 2026.4.0, just declare the method

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 4, 0)
class MyComponent : public Component {
#else
class MyComponent : public Component, public GAPScanEventHandler {
#endif
  void gap_scan_event_handler(const BLEScanResult &scan_result)
#if ESPHOME_VERSION_CODE < VERSION_CODE(2026, 4, 0)
    override
#endif
  ;
};

Timeline

ESPHome 2026.4.0 (April 2026): Virtual handler classes removed
No deprecation period — this is a class removal

Finding Code That Needs Updates

# Find handler class inheritance
grep -rn 'GAPEventHandler\|GAPScanEventHandler\|GATTcEventHandler\|GATTsEventHandler\|BLEStatusEventHandler' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15310: Devirtualize BLE event handler dispatch

CallbackManager: std::function Replaced with Lightweight Callback

Thu, 09 Apr 2026 00:00:00 GMT

CallbackManager and LazyCallbackManager now use a lightweight 8-byte Callback struct instead of std::function (16 bytes). External components that define their own callback registration methods using std::function should update to templates for optimal performance.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #14853: Replace std::function with lightweight Callback in CallbackManager

std::function has significant overhead on embedded targets: 16 bytes per instance on 32-bit platforms, plus heap allocation for captured lambdas. The new Callback struct uses C++20 if constexpr to store small trivially-copyable callables (like [this] lambdas) inline within the Callback object, alongside a function pointer, avoiding heap allocation while keeping the total size at 8 bytes.

Measured savings

Platform	Config	Flash Delta	Heap Delta
ESP8266	minimal	-160 B
ESP8266	ratgdo (cover + sensors)	-592 B	+142 B free
ESP8266	MQTT + web_server + many entities	-832 B	+488 B free
ESP32 IDF	large (climate, BLE, web_server)	-456 B
ESP32 IDF	minimal	-212 B	+72 B free

What’s Changing

All callback registration methods (add_on_*_callback, add_*_callback, register_listener, etc.) on entity base classes and components are now templates instead of taking std::function.

// Before
void add_on_state_callback(std::function<void(float)> &&callback) {
  this->state_callback_.add(std::move(callback));
}

// After
template<typename F> void add_on_state_callback(F &&callback) {
  this->state_callback_.add(std::forward<F>(callback));
}

Who This Affects

External components that define their own callback registration methods taking std::function.

Existing code continues to compile and work correctly. However, unconverted methods use a less efficient heap-allocation path: the lambda gets wrapped in std::function before reaching CallbackManager::add(), which then heap-allocates it. Previously the std::function was stored directly in the vector element with no extra allocation.

Callers of entity callbacks (registering callbacks on ESPHome entities) need no changes.

Migration Guide

Convert callback registration methods from std::function to templates:

your_component.h

// Before (still compiles, but now less efficient than before)
class MyComponent : public Component {
 public:
  void add_on_data_callback(std::function<void(float)> &&callback) {
    this->data_callback_.add(std::move(callback));
  }
 protected:
  CallbackManager<void(float)> data_callback_;
};

your_component.h

// After (optimal — inline storage, zero heap allocation for [this] lambdas)
class MyComponent : public Component {
 public:
  template<typename F> void add_on_data_callback(F &&callback) {
    this->data_callback_.add(std::forward<F>(callback));
  }
 protected:
  CallbackManager<void(float)> data_callback_;
};

If you had a separate .cpp definition, move the body inline into the header and remove the .cpp definition (templates must be defined in headers).

Supporting Multiple ESPHome Versions

The template approach is backward compatible — it works on older ESPHome versions too, since the template accepts std::function as well as raw lambdas. No version guard needed.

Timeline

ESPHome 2026.4.0 (April 2026): CallbackManager uses Callback instead of std::function
No deprecation period — existing code still compiles but uses a less efficient path

Finding Code That Needs Updates

# Find callback registration methods that still use std::function
grep -rn 'std::function.*&&.*callback' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #14853: Replace std::function with lightweight Callback in CallbackManager

Climate and Fan Custom Mode Vectors Moved to Entity

Thu, 09 Apr 2026 00:00:00 GMT

Custom mode vectors (custom_fan_modes, custom_presets for climate; preset_modes for fan) are now stored on the entity base class instead of being rebuilt inside traits on every call. The old ClimateTraits and FanTraits setter methods are deprecated.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15206: Climate — Store custom mode vectors on Climate entity
PR #15209: Fan — Store preset mode vector on Fan entity

ClimateTraits and FanTraits contained std::vector members that were reconstructed on every traits call. Climate uses traits() and Fan uses get_traits() — both are called during publish_state() and control(), the hottest paths in these components. This caused heap allocations on every state update. On long-running ESP devices, repeated allocations of different sizes fragment the heap and can lead to crashes.

Moving the vectors to the entity base class eliminates all heap allocation from traits copies.

What’s Changing

Climate

Custom fan modes and custom presets are now set directly on the Climate entity:

// Before — set on traits in traits() override
climate::ClimateTraits traits() override {
  auto traits = climate::ClimateTraits();
  traits.set_supported_custom_fan_modes({"Low", "Medium", "High"});
  traits.set_supported_custom_presets({"Eco", "Sleep"});
  return traits;
}

// After — set once during setup or codegen
void setup() override {
  this->set_supported_custom_fan_modes({"Low", "Medium", "High"});
  this->set_supported_custom_presets({"Eco", "Sleep"});
}

The old ClimateTraits::set_supported_custom_fan_modes() and ClimateTraits::set_supported_custom_presets() methods still work but are deprecated and will be removed in 2026.11.0.

Fan

Preset modes are now set directly on the Fan entity. Unlike Climate, Fan::get_traits() is the virtual method itself, so the get_traits() override must wire the stored preset modes into the returned traits via wire_preset_modes_():

// Before — set on traits in get_traits() override
fan::FanTraits get_traits() override {
  return fan::FanTraits(true, true, true, this->preset_modes_);
}

// After — set once during setup or codegen, wire into traits in get_traits()
void setup() override {
  this->set_supported_preset_modes({"Auto", "Sleep", "Nature"});
}

fan::FanTraits get_traits() override {
  fan::FanTraits traits(true, true, true);
  this->wire_preset_modes_(traits);
  return traits;
}

The old FanTraits::set_supported_preset_modes() methods still work but are deprecated and will be removed in 2026.11.0.

Who This Affects

External climate components (~35 affected) that call ClimateTraits::set_supported_custom_fan_modes() or ClimateTraits::set_supported_custom_presets().

External fan components (~15 affected) that pass preset modes through FanTraits constructors or call FanTraits::set_supported_preset_modes().

Migration Guide

Climate

// Before — in traits() override, called on every publish_state()
climate::ClimateTraits traits() override {
  auto traits = climate::ClimateTraits();
  traits.set_supported_custom_fan_modes({"Low", "Medium", "High"});
  traits.set_supported_custom_presets({"Eco", "Sleep"});
  // ... other traits
  return traits;
}

// After — set once, traits() gets them automatically
void setup() override {
  this->set_supported_custom_fan_modes({"Low", "Medium", "High"});
  this->set_supported_custom_presets({"Eco", "Sleep"});
}

climate::ClimateTraits traits() override {
  auto traits = climate::ClimateTraits();
  // custom_fan_modes and custom_presets are wired automatically
  // ... other traits
  return traits;
}

Fan

// Before
fan::FanTraits get_traits() override {
  return fan::FanTraits(true, true, true, this->preset_modes_);
}

// After — get_traits() override must call wire_preset_modes_() to expose them
void setup() override {
  this->set_supported_preset_modes({"Auto", "Sleep", "Nature"});
}

fan::FanTraits get_traits() override {
  fan::FanTraits traits(true, true, true);
  this->wire_preset_modes_(traits);
  return traits;
}

Note: Unlike Climate — where the base class’s non-virtual get_traits() wraps a virtual traits() and wires custom modes automatically — Fan::get_traits() is itself the virtual method overridden by components. The base class has no opportunity to inject preset modes, so each override must call wire_preset_modes_() explicitly. The internal speed, template, and hbridge fan components follow this pattern.

Python codegen

# Before — setting custom modes via traits in C++ generated code
cg.add(traits.set_supported_custom_fan_modes(modes))

# After — setting custom modes directly on the entity
cg.add(var.set_supported_custom_fan_modes(modes))

Timeline

ESPHome 2026.4.0 (April 2026): Old traits setters deprecated
ESPHome 2026.11.0 (November 2026): Deprecated setters removed, traits become trivially copyable

Finding Code That Needs Updates

# Climate — find traits-based custom mode setters
grep -rn 'set_supported_custom_fan_modes\|set_supported_custom_presets' your_component/

# Fan — find traits-based preset mode setters
grep -rn 'set_supported_preset_modes' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

FlushResult Renamed to UARTFlushResult

Thu, 09 Apr 2026 00:00:00 GMT

The FlushResult enum introduced in ESPHome 2026.3.0 has been renamed to UARTFlushResult with prefixed enum values to follow ESPHome’s naming conventions and avoid macro collisions.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15101: Rename FlushResult to UARTFlushResult with UART_FLUSH_RESULT_ prefix

The original FlushResult::SUCCESS value collided with the Realtek RTL SDK’s #define SUCCESS 0 macro, requiring ugly #pragma push_macro workarounds. Renaming to UARTFlushResult with UART_FLUSH_RESULT_ prefixed values follows ESPHome’s conventional component-prefix naming style (matching UARTParityOptions / UART_CONFIG_PARITY_NONE) and eliminates the collision entirely.

What’s Changing

Before	After
`FlushResult`	`UARTFlushResult`
`FlushResult::SUCCESS`	`UARTFlushResult::UART_FLUSH_RESULT_SUCCESS`
`FlushResult::TIMEOUT`	`UARTFlushResult::UART_FLUSH_RESULT_TIMEOUT`
`FlushResult::FAILED`	`UARTFlushResult::UART_FLUSH_RESULT_FAILED`
`FlushResult::ASSUMED_SUCCESS`	`UARTFlushResult::UART_FLUSH_RESULT_ASSUMED_SUCCESS`

Who This Affects

External components that implement UARTComponent::flush() and reference the FlushResult type or enum values.

This only affects components updated for the 2026.3.0 flush() return type change. If you haven’t updated your flush() override yet, see the 2026.3.0 UART flush blog post first.

Migration Guide

// Before (2026.3.0)
FlushResult flush() override {
  // ...
  return FlushResult::ASSUMED_SUCCESS;
}

// After (2026.4.0)
UARTFlushResult flush() override {
  // ...
  return UARTFlushResult::UART_FLUSH_RESULT_ASSUMED_SUCCESS;
}

Supporting Multiple ESPHome Versions

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 4, 0)
UARTFlushResult flush() override {
  // ...
  return UARTFlushResult::UART_FLUSH_RESULT_ASSUMED_SUCCESS;
}
#elif ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
FlushResult flush() override {
  // ...
  return FlushResult::ASSUMED_SUCCESS;
}
#else
void flush() override {
  // ...
}
#endif

Timeline

ESPHome 2026.3.0 (March 2026): FlushResult introduced
ESPHome 2026.4.0 (April 2026): Renamed to UARTFlushResult with prefixed values
No deprecation period — this is a rename of a type introduced one release ago

Finding Code That Needs Updates

# Find FlushResult references in your component
grep -rn 'FlushResult' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

Modbus Helper Functions Moved to modbus::helpers

Thu, 09 Apr 2026 00:00:00 GMT

Shared helper functions and types have been moved from modbus_controller to modbus::helpers to enable reuse by other modbus-based components. Deprecated shims keep the old names working until ESPHome 2026.10.0.

This is a developer breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15291: Share helper functions across modbus components — part A PR #14172: Share helper functions across modbus components — part B

These PRs are part of a series preparing for a new modbus_server component. Helper functions that were previously internal to modbus_controller are now in modbus::helpers so they can be shared across modbus_controller, modbus_server, and other modbus-based components.

What’s Changing

C++ symbols moved (Part A)

Old location	New location
`modbus_controller::SensorValueType`	`modbus::helpers::SensorValueType`
`modbus_controller::value_type_is_float()`	`modbus::helpers::value_type_is_float()`
`modbus_controller::modbus_register_read_function()`	`modbus::helpers::modbus_register_read_function()`
`modbus_controller::modbus_register_write_function()`	`modbus::helpers::modbus_register_write_function()`
`modbus_controller::c_to_hex()`	`modbus::helpers::c_to_hex()`
`modbus_controller::byte_from_hex_str()`	`modbus::helpers::byte_from_hex_str()`
`modbus_controller::word_from_hex_str()`	`modbus::helpers::word_from_hex_str()`
`modbus_controller::dword_from_hex_str()`	`modbus::helpers::dword_from_hex_str()`
`modbus_controller::qword_from_hex_str()`	`modbus::helpers::qword_from_hex_str()`

C++ symbols moved (Part B)

Old location	New location
`modbus_controller::number_to_payload()`	`modbus::helpers::number_to_payload()`
`modbus_controller::payload_to_number()`	`modbus::helpers::payload_to_number()`
`modbus_controller::get_data()`	`modbus::helpers::get_data()`
`modbus_controller::float_to_payload()`	`modbus::helpers::float_to_payload()`
`modbus_controller::coil_from_vector()`	`modbus::helpers::coil_from_vector()`
`modbus_controller::mask_and_shift_by_rightbit()`	`modbus::helpers::mask_and_shift_by_rightbit()`

Python symbols moved

The following Python symbols have moved from esphome.components.modbus_controller to esphome.components.modbus.helpers:

MODBUS_FUNCTION_CODE
MODBUS_REGISTER_TYPE
MODBUS_WRITE_REGISTER_TYPE
SENSOR_VALUE_TYPE
TYPE_REGISTER_MAP
CPP_TYPE_REGISTER_MAP
ModbusRegisterType

Who This Affects

External components that import helper functions from modbus_controller, either in C++ (modbus_controller::number_to_payload(), etc.) or Python (from esphome.components.modbus_controller import SENSOR_VALUE_TYPE, etc.).

Migration Guide

C++

Deprecated shims in modbus_controller.h forward to the new location — existing code continues to compile with deprecation warnings. A using declaration keeps modbus_controller::SensorValueType working without warnings.

To silence warnings, update the namespace:

// Before
#include "esphome/components/modbus_controller/modbus_controller.h"
auto result = modbus_controller::payload_to_number(data, offset, type);

// After
#include "esphome/components/modbus/helpers.h"
auto result = modbus::helpers::payload_to_number(data, offset, type);

Python

# Before
from esphome.components.modbus_controller import SENSOR_VALUE_TYPE

# After
from esphome.components.modbus.helpers import SENSOR_VALUE_TYPE

Timeline

ESPHome 2026.4.0 (April 2026): Functions moved, deprecated shims added
ESPHome 2026.10.0 (October 2026): Deprecated shims removed

Finding Code That Needs Updates

# C++ — find references to old namespace
grep -rn 'modbus_controller::number_to_payload\|modbus_controller::payload_to_number' your_component/
grep -rn 'modbus_controller::get_data\|modbus_controller::float_to_payload' your_component/
grep -rn 'modbus_controller::c_to_hex\|modbus_controller::byte_from_hex_str' your_component/
grep -rn 'modbus_controller::SensorValueType' your_component/

# Python — find old imports
grep -rn 'from esphome.components.modbus_controller import' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

Sensor .raw_state Deprecated in Favor of get_raw_state()

Thu, 09 Apr 2026 00:00:00 GMT

Direct access to the sensor .raw_state member is now deprecated. Use get_raw_state() instead. The .raw_state member will be removed in ESPHome 2026.10.0.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15094: Deprecate .raw_state, guard raw_callback_ behind USE_SENSOR_FILTER

This follows the same pattern as the text_sensor .raw_state deprecation. Accessor methods allow future optimizations to the internal storage without breaking callers.

Additionally, raw_callback_ is now guarded behind USE_SENSOR_FILTER, saving 4 bytes per sensor instance when no filters are configured.

What’s Changing

// Before
float raw = id(my_sensor).raw_state;

// After
float raw = id(my_sensor).get_raw_state();

The .state member is not deprecated — it remains a valid public member. However, examples in the docs now show get_state() to encourage the accessor pattern.

Who This Affects

External components and lambda users that directly access .raw_state on sensor instances.

The deprecated member still works but emits a compiler warning. It will be removed in 2026.10.0.

Migration Guide

Replace all direct .raw_state access with get_raw_state():

// Before
float raw = id(my_sensor).raw_state;
float current = this->raw_state;

// After
float raw = id(my_sensor).get_raw_state();
float current = this->get_raw_state();

Important: Nothing outside of Sensor::publish_state() should ever write to raw_state. If your component does this, it is a bug — use publish_state() instead.

Supporting Multiple ESPHome Versions

get_raw_state() has been available since before this deprecation (it was previously defined in .cpp), so you can simply switch to it without a version guard:

float raw = id(my_sensor).get_raw_state();

Timeline

ESPHome 2026.4.0 (April 2026): .raw_state deprecated with compiler warning
ESPHome 2026.10.0 (October 2026): .raw_state member removed

Finding Code That Needs Updates

# Find direct .raw_state access in your component
grep -rn '\.raw_state' your_component/
grep -rn '->raw_state' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15094: Deprecate .raw_state, guard raw_callback_ behind USE_SENSOR_FILTER

TemplatableFn: 4-Byte Templatable Storage for Trivially Copyable Types

Thu, 09 Apr 2026 00:00:00 GMT

The TEMPLATABLE_VALUE macro now uses TemplatableFn (4 bytes) instead of TemplatableValue (8 bytes) for trivially copyable types like float, uint32_t, bool, and enums. External components that call macro-generated setters with raw C++ constants instead of going through cg.templatable() will fail to compile.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15545: Add TemplatableFn for 4-byte function-pointer templatable storage

Every action in ESPHome uses TEMPLATABLE_VALUE to store values that can be either constants or lambdas. Previously, each field used TemplatableValue (8 bytes: a value slot + function pointer). For trivially copyable types, the value slot is unnecessary — a stateless lambda returning a constant compiles to a plain function pointer and costs only 4 bytes.

With ~340 TEMPLATABLE_VALUE fields across the codebase for trivially copyable types, this saves ~1,360 bytes of RAM.

Three-Tier Design

Type	Size (32-bit)	Use Case
`TemplatableFn<T, Ts...>`	4 bytes	Function pointer only. Used by `TEMPLATABLE_VALUE` macro for trivially copyable types.
`TemplatableValue<T, Ts...>`	8 bytes	Value OR function pointer. Full backward compat — accepts raw constants.
`TemplatableValue<std::string, Ts...>`	8 bytes	Full implementation with string paths, stateful lambdas. Unchanged.

The TEMPLATABLE_VALUE macro automatically selects the type via TemplatableStorage<T, Ts...>:

Trivially copyable types (float, uint32_t, bool, enums, pointers) → TemplatableFn (4 bytes)
Non-trivially copyable types (std::string, std::vector<uint8_t>) → TemplatableValue (8 bytes)

Who This Affects

1. External components calling TEMPLATABLE_VALUE setters with raw values

If your Python codegen calls a macro-generated setter directly with a raw C++ constant instead of going through cg.templatable(), it will fail to compile:

# This will fail — raw value passed to TemplatableFn setter
cg.add(action.set_brightness(0.5))

# This works — cg.templatable wraps constants in stateless lambdas
cg.add(action.set_brightness(await cg.templatable(config[CONF_BRIGHTNESS], [], float)))

2. External components using TemplatableValue for non-string types with stateful lambdas

TemplatableValue<T, Ts...> for non-string types no longer accepts stateful lambdas (lambdas with captures). A GitHub code search found no external components using this pattern. If needed, use std::function<T(Ts...)> directly.

Migration Guide

Fix codegen: route values through cg.templatable()

# Before — raw value passed to setter (broken)
cg.add(action.set_value(config[CONF_VALUE]))

# After — value wrapped via cg.templatable (correct)
# args is the list of template arguments, e.g. [(float, "x")] or []
template_ = await cg.templatable(config[CONF_VALUE], args, int)
cg.add(action.set_value(template_))

This was technically incorrect before — the setter is part of the codegen API and should only receive values produced by cg.templatable(). The fix is straightforward.

Optional: migrate direct TemplatableValue usage to TemplatableFn

If your component uses TemplatableValue directly (not via the macro), it continues to work without changes. To opt into the 4-byte savings:

// Before (8 bytes, still works)
TemplatableValue<float, float> min_{NAN};

// After (4 bytes)
TemplatableFn<float, float> min_{[](float) -> float { return NAN; }};

// Before (8 bytes, still works)
TemplatableValue<uint16_t> port_{80};

// After (4 bytes)
TemplatableFn<uint16_t> port_{[]() -> uint16_t { return 80; }};

TemplatableFn has the same API as TemplatableValue (has_value(), value(), optional_value(), value_or()), so no other code changes are needed.

Stateful lambdas on non-string types

// Before (hidden heap allocation via TemplatableValue)
int captured = 42;
TemplatableValue<int> val = [captured]() { return captured; };

// After (explicit about the allocation)
std::function<int()> val = [captured]() { return captured; };

TemplatableValue<std::string, Ts...> still supports stateful lambdas — no changes needed for string types.

Timeline

ESPHome 2026.4.0 (April 2026): TEMPLATABLE_VALUE macro uses TemplatableFn for trivially copyable types
No deprecation period for the macro change — TemplatableValue used directly is fully backward compatible

Finding Code That Needs Updates

# Find TEMPLATABLE_VALUE setters called without cg.templatable()
grep -rn 'cg.add.*set_.*config\[' your_component/__init__.py

# Find TemplatableValue usage that could migrate to TemplatableFn
grep -rn 'TemplatableValue' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

Implementing Automations covers the full TEMPLATABLE_VALUE / cg.templatable() pairing for actions
PR #15545: Add TemplatableFn for 4-byte function-pointer templatable storage

Trigger Trampolines Eliminated with build_callback_automation

Thu, 09 Apr 2026 00:00:00 GMT

Common entity trigger classes have been replaced with lightweight forwarder structs that fit inline in the callback system. The new build_callback_automation() API eliminates per-trigger object allocations. Several entity callback signatures have also changed to pass state as an argument.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15174: Eliminate trigger trampolines with deduplicated forwarder structs
PR #15198: alarm_control_panel — Migrate triggers to callback automation
PR #15199: lock — Migrate LockStateTrigger to callback automation
PR #15200: media_player — Migrate triggers to callback automation

Previously, each automation trigger created a separate C++ object that existed solely to forward a callback to an Automation. For example:

button press → callback → ButtonPressTrigger::trigger() → Automation::trigger()

Now a lightweight forwarder struct collapses this into the callback itself:

button press → callback → TriggerForwarder::operator()() → Automation::trigger()

The forwarder fits in the Callback::ctx_ field — no additional storage needed.

Memory savings

Config	Platform	RAM Saved	Flash Saved
ratgdo (garage door)	ESP8266	88 bytes	224 bytes
multi-sensor device	ESP32-IDF	208 bytes	280 bytes

What’s Changing

1. Callback signatures changed

Several entity callback signatures changed to pass state as an argument, enabling single-pointer forwarders:

// alarm_control_panel — Before
void add_on_state_callback(std::function<void()> &&callback);
// After
template<typename F> void add_on_state_callback(F &&callback);
// Callback signature: void(AlarmControlPanelState)

// lock — Before
void add_on_state_callback(std::function<void()> &&callback);
// After
template<typename F> void add_on_state_callback(F &&callback);
// Callback signature: void(LockState)

// media_player — Before
void add_on_state_callback(std::function<void()> &&callback);
// After
template<typename F> void add_on_state_callback(F &&callback);
// Callback signature: void(MediaPlayerState)

2. Automation::trigger_ field removed

The trigger_ protected field on Automation (set in constructor, never read) has been removed.

Who This Affects

External components registering callbacks on alarm_control_panel, lock, or media_player — must update callback signature to accept the state parameter
External components accessing Automation::trigger_ — this field no longer exists

Migration Guide

Callback signature changes

// alarm_control_panel — Before
this->parent_->add_on_state_callback([this]() {
  auto state = this->parent_->get_state();
  // ...
});

// After
this->parent_->add_on_state_callback([this](AlarmControlPanelState state) {
  // state is passed directly, no need to call get_state()
});

// lock — Before
this->parent_->add_on_state_callback([this]() {
  auto state = this->parent_->state;
  // ...
});

// After
this->parent_->add_on_state_callback([this](LockState state) {
  // state is passed directly
});

// media_player — Before
this->parent_->add_on_state_callback([this]() {
  auto state = this->parent_->state;
  // ...
});

// After
this->parent_->add_on_state_callback([this](MediaPlayerState state) {
  // state is passed directly
});

Python codegen migration

If your external component uses build_automation() with trigger classes, migrate to build_callback_automations() (PR #15246):

# Before
from esphome import automation

MyStateTrigger = my_ns.class_("MyStateTrigger", automation.Trigger.template(cg.bool_))
MyPressTrigger = my_ns.class_("MyPressTrigger", automation.Trigger.template())

CONFIG_SCHEMA = cv.Schema({
    cv.Optional(CONF_ON_STATE): automation.validate_automation(
        {cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(MyStateTrigger)}
    ),
    cv.Optional(CONF_ON_PRESS): automation.validate_automation(
        {cv.GenerateID(CONF_TRIGGER_ID): cv.declare_id(MyPressTrigger)}
    ),
})

async def to_code(config):
    for conf in config.get(CONF_ON_STATE, []):
        trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
        await automation.build_automation(trigger, [(bool, "x")], conf)
    for conf in config.get(CONF_ON_PRESS, []):
        trigger = cg.new_Pvariable(conf[CONF_TRIGGER_ID], var)
        await automation.build_automation(trigger, [], conf)

# After — no trigger classes needed, no CONF_TRIGGER_ID in schema
from esphome import automation

_CALLBACK_AUTOMATIONS = (
    automation.CallbackAutomation(CONF_ON_STATE, "add_on_state_callback", [(bool, "x")]),
    automation.CallbackAutomation(CONF_ON_PRESS, "add_on_press_callback"),
)

CONFIG_SCHEMA = cv.Schema({
    cv.Optional(CONF_ON_STATE): automation.validate_automation({}),
    cv.Optional(CONF_ON_PRESS): automation.validate_automation({}),
})

async def to_code(config):
    await automation.build_callback_automations(var, config, _CALLBACK_AUTOMATIONS)

build_automation() and all Trigger subclasses remain available for triggers that need mutable state beyond a single Automation* pointer.

Timeline

ESPHome 2026.4.0 (April 2026): Trigger classes removed, callback signatures changed
No deprecation period — these are signature changes and class removals

Finding Code That Needs Updates

# Find alarm_control_panel/lock/media_player callback registrations
grep -rn 'add_on_state_callback' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

wake_loop Moved from Socket Component into Core

Thu, 09 Apr 2026 00:00:00 GMT

wake_loop_threadsafe() and related wake primitives have moved from the socket component into core. The require_wake_loop_threadsafe() opt-in is deprecated (now a no-op) — wake works unconditionally on all platforms.

This is a breaking change for external components in ESPHome 2026.4.0 and later.

Background

PR #15446: Move wake_loop out of socket component into core

The wake mechanism originally lived in the socket component because the first implementation used a UDP loopback socket. Since then, every platform has moved to nearly-free primitives (FreeRTOS task notifications, esp_schedule(), ARM __sev()), and the socket dependency was unnecessary complexity: 12 components needed to call require_wake_loop_threadsafe(), #ifdef USE_WAKE_LOOP_THREADSAFE guards were needed at every call site, and platforms without networking had silent degradation (up to ~16ms latency).

Now it just works — no opt-in, no defines, no guards.

Platform wake mechanisms

Platform	Mechanism
ESP32	FreeRTOS task notifications (ISR-safe)
LibreTiny	FreeRTOS task notifications
ESP8266	`esp_schedule()` (IRAM-safe)
RP2040	`__sev()` / `__wfe()` (ARM CPU instructions)
Zephyr (nRF52)	`k_sem_give()` (ISR-safe) / `k_sem_take()`
Host	UDP loopback socket + `select()`

What’s Changing

Removed defines

USE_WAKE_LOOP_THREADSAFE — no longer needed, wake is always available
USE_SOCKET_SELECT_SUPPORT — replaced by USE_HOST where needed

Deprecated Python function

socket.require_wake_loop_threadsafe() (Python codegen helper) is deprecated (warns, no-op). Remove calls to it.

No more `#ifdef` guards

// Before
#if defined(USE_SOCKET_SELECT_SUPPORT) && defined(USE_WAKE_LOOP_THREADSAFE)
App.wake_loop_threadsafe();
#endif

// After
App.wake_loop_threadsafe();

Socket dependency no longer needed for wake

Components no longer need to declare socket as a dependency just for wake functionality:

# Before
AUTO_LOAD = ["socket"]  # just for wake_loop

# After — remove if socket was only needed for wake
# AUTO_LOAD = []

Who This Affects

External components calling socket.require_wake_loop_threadsafe() in Python codegen — remove the call
External components using #ifdef USE_WAKE_LOOP_THREADSAFE — remove the guard
External components with socket in AUTO_LOAD only for wake — remove it
External components checking USE_SOCKET_SELECT_SUPPORT — use USE_HOST instead

Migration Guide

C++ — remove `#ifdef` guards

// Before
void some_background_thread() {
#if defined(USE_SOCKET_SELECT_SUPPORT) && defined(USE_WAKE_LOOP_THREADSAFE)
  App.wake_loop_threadsafe();
#endif
}

// After
void some_background_thread() {
  App.wake_loop_threadsafe();
}

Python codegen — remove opt-in call and socket AUTO_LOAD

# Before
from esphome.components import socket

AUTO_LOAD = ["socket"]

async def to_code(config):
    socket.require_wake_loop_threadsafe()
    # ... rest of codegen

# After — remove socket AUTO_LOAD and require call
async def to_code(config):
    # ... rest of codegen (no wake opt-in needed)

Timeline

ESPHome 2026.4.0 (April 2026): Wake moved to core, require_wake_loop_threadsafe() deprecated
USE_WAKE_LOOP_THREADSAFE and USE_SOCKET_SELECT_SUPPORT defines removed immediately

Finding Code That Needs Updates

# Find require_wake_loop_threadsafe calls
grep -rn 'require_wake_loop_threadsafe' your_component/

# Find #ifdef guards
grep -rn 'USE_WAKE_LOOP_THREADSAFE' your_component/

# Find USE_SOCKET_SELECT_SUPPORT
grep -rn 'USE_SOCKET_SELECT_SUPPORT' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #15446: Move wake_loop out of socket component into core

Application Name and Friendly Name Now Return StringRef

Thu, 12 Mar 2026 00:00:00 GMT

App.get_name() and App.get_friendly_name() now return const StringRef & instead of const std::string &. Most code compiles unchanged because StringRef provides .c_str(), .size(), .empty(), and implicit conversion to std::string. However, binding the result to const std::string & silently creates a heap-allocated temporary — update these references to const auto & to avoid the allocation.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14532: Application name and friendly_name return StringRef

The application name and friendly name are set once at boot and never change. Storing them as std::string wastes heap memory for the string object overhead and its dynamic allocation. StringRef is a lightweight reference to a string with static lifetime — it avoids the heap allocation entirely.

Memory savings

Platform	Flash savings	RAM savings
ESP8266	752 bytes	176 bytes
RP2040	2,508 bytes	—

What’s Changing

// Before
const std::string &get_name() const;
const std::string &get_friendly_name() const;

// After
const StringRef &get_name() const;
const StringRef &get_friendly_name() const;

StringRef provides:

.c_str() — null-terminated C string pointer
.size() — string length
.empty() — true if empty
operator std::string() — implicit conversion to std::string
operator== — comparison with string literals and other strings

Most code compiles unchanged. The key issue is when the return value is bound to const std::string & — this triggers an implicit conversion that heap-allocates a temporary std::string.

Who This Affects

External components that:

Store App.get_name() or App.get_friendly_name() in a const std::string & variable
Pass the result to functions expecting const std::string & (triggers implicit conversion)

Standard YAML configurations are not affected.

Migration Guide

Fix silent heap allocation

// Before — compiles but silently heap-allocates a temporary:
const std::string &name = App.get_name();

// After — zero allocation:
const auto &name = App.get_name();

Passing to functions expecting std::string

If you need to pass the name to a function that takes const std::string &, the implicit conversion works but allocates. If the function also accepts const char *, prefer .c_str():

// Heap-allocates (implicit conversion to std::string)
some_function_taking_string(App.get_name());

// Zero allocation
some_function_taking_cstr(App.get_name().c_str());

Logging

// Works — c_str() returns null-terminated string
ESP_LOGD(TAG, "Name: %s", App.get_name().c_str());

Supporting Multiple ESPHome Versions

Using const auto & works on all versions — it binds to const std::string & on older versions and const StringRef & on 2026.3.0+:

// Safe on all versions
const auto &name = App.get_name();
ESP_LOGD(TAG, "Name: %s", name.c_str());

If you need to explicitly handle both:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  const StringRef &name = App.get_name();
#else
  const std::string &name = App.get_name();
#endif

Timeline

ESPHome 2026.3.0 (March 2026): Return type changed
No deprecation period — this is a signature change

Finding Code That Needs Updates

# Find std::string references to App.get_name()
grep -rn 'std::string.*get_name\|std::string.*get_friendly_name' your_component/

# Find any usage of App.get_name() or App.get_friendly_name()
grep -rn 'App\.get_name\|App\.get_friendly_name\|get_name()\.c_str\|get_friendly_name()\.c_str' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

call_loop(), mark_failed(), and call_dump_config() Are No Longer Virtual

Thu, 12 Mar 2026 00:00:00 GMT

Component::call_loop(), Component::mark_failed(), and Component::call_dump_config() are no longer virtual methods. External components that override any of these methods must remove them entirely and move logic to loop() or dump_config(). This saves 800+ bytes of flash globally from vtable elimination.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14083: Devirtualize call_loop() and mark_failed() in Component PR #14355: Devirtualize call_dump_config()

These methods were virtual since the original 2019 codebase, designed to let intermediate base classes inject behavior between the framework and the user’s loop() / dump_config() without requiring base class calls. The components that historically used these overrides have all been refactored:

MQTTComponent::call_loop() — removed in #13356 (Jan 2026) when MQTT was restructured
ESP32BLE::mark_failed() — removed in #4173 (Jan 2023) when BLE was refactored to use event handlers
MQTTComponent::call_dump_config() — removed in #14355; the override incorrectly skipped dump_config() for internal entities

After those architectural improvements, zero overrides remained. Making these methods non-virtual eliminates one vtable slot per method from every Component-derived class (~100+ vtables in a typical build), saving 800+ bytes of flash.

What’s Changing

// Before (virtual)
class Component {
 public:
  virtual void call_loop();
  virtual void mark_failed();
  virtual void call_dump_config();
};

// After (non-virtual)
class Component {
 public:
  void call_loop();
  void mark_failed();
  void call_dump_config();
};

Any class that declares call_loop() override, mark_failed() override, or call_dump_config() override will fail to compile.

Who This Affects

External components that override call_loop(), mark_failed(), or call_dump_config(). No known external components currently override any of these methods — they were virtual with zero overrides in the wild.

Standard YAML configurations are not affected.

Migration Guide

Remove overrides and move logic to loop()/dump_config()

Simply removing the override keyword is not enough — a same-named non-virtual method in a derived class will never be called by the framework (calls through Component* always dispatch to Component::call_loop()). You must remove the method entirely and move logic to the appropriate virtual hook.

// Before — fails to compile
class MyComponent : public Component {
 public:
  void call_loop() override {
    // Custom per-loop logic
  }
  void call_dump_config() override {
    // Custom config output
  }
  void mark_failed() override {
    // Custom failure handling
  }
};

// After — use loop(), dump_config(), and is_failed() instead
class MyComponent : public Component {
 public:
  void loop() override {
    // Former call_loop() logic goes here
    if (this->is_failed()) {
      // Former mark_failed() follow-up handling goes here
      return;
    }
  }
  void dump_config() override {
    // Former call_dump_config() logic goes here
  }
};

Supporting Multiple ESPHome Versions

Since override on a non-virtual method is a compile error, you need a version guard:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
// These methods are no longer virtual — do not override
#else
void call_loop() override { /* ... */ }
void mark_failed() override { /* ... */ }
void call_dump_config() override { /* ... */ }
#endif

Timeline

ESPHome 2026.3.0 (March 2026): call_loop(), mark_failed(), and call_dump_config() are no longer virtual — override keyword causes compile error

Finding Code That Needs Updates

# Find call_loop() overrides
grep -rn 'call_loop().*override' your_component/

# Find mark_failed() overrides
grep -rn 'mark_failed().*override' your_component/

# Find call_dump_config() overrides
grep -rn 'call_dump_config().*override' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

get_loop_priority() Now Conditionally Compiled with USE_LOOP_PRIORITY

Thu, 12 Mar 2026 00:00:00 GMT

The get_loop_priority() virtual method on Component is now only available when USE_LOOP_PRIORITY is defined. This define is only set on RP2040, the only platform where loop priority has an effect. External components that override get_loop_priority() must guard the override with #ifdef USE_LOOP_PRIORITY.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14210: Conditionally compile get_loop_priority with USE_LOOP_PRIORITY

The get_loop_priority() virtual method existed on all platforms, but only had an effect on RP2040 — it controls the order in which components’ loop() methods are called. On ESP32, ESP8266, and LibreTiny, WiFi and Ethernet no longer block during setup (since PR #9823), making loop priority ordering unnecessary. The method was dead code on those platforms but still consumed a vtable entry in every Component subclass.

By guarding the method behind #ifdef USE_LOOP_PRIORITY, non-RP2040 platforms eliminate one vtable entry per component and the insertion sort during Application::setup().

What’s Changing

The get_loop_priority() virtual method declaration and implementation are now guarded behind #ifdef USE_LOOP_PRIORITY. This define is only set on RP2040.

// In Component (esphome/core/component.h)
class Component {
 public:
#ifdef USE_LOOP_PRIORITY
  virtual float get_loop_priority() const;
#endif
};

On ESP32, ESP8266, and LibreTiny, the method does not exist at all. Overriding it without the guard produces a compile error.

Who This Affects

External components that override get_loop_priority().

The override was already a no-op on ESP32/ESP8266/LibreTiny — it only has a functional effect on RP2040. Adding the #ifdef guard makes this explicit.

Standard YAML configurations are not affected.

Migration Guide

// Before
class MyComponent : public Component {
 public:
  float get_loop_priority() const override { return 10.0f; }
};

// After
class MyComponent : public Component {
 public:
#ifdef USE_LOOP_PRIORITY
  float get_loop_priority() const override { return 10.0f; }
#endif
};

Supporting Multiple ESPHome Versions

The #ifdef guard alone is the simplest approach and works on all versions:

// Safe on all versions
#ifdef USE_LOOP_PRIORITY
  float get_loop_priority() const override { return 10.0f; }
#endif

On ESPHome < 2026.3.0, USE_LOOP_PRIORITY is not defined on any platform, so the #ifdef block is skipped. This is fine because the override was a no-op on non-RP2040 platforms anyway.

If you need the override to remain active on older ESPHome versions:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
#ifdef USE_LOOP_PRIORITY
  float get_loop_priority() const override { return 10.0f; }
#endif
#else
  float get_loop_priority() const override { return 10.0f; }
#endif

Timeline

ESPHome 2026.3.0 (March 2026): get_loop_priority() conditionally compiled
No deprecation period — the method was dead code on affected platforms

Finding Code That Needs Updates

# Find get_loop_priority overrides
grep -rn 'get_loop_priority' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #14210: Conditionally compile get_loop_priority

http_request API Modernization: Vector-Based Headers

Thu, 12 Mar 2026 00:00:00 GMT

The http_request component’s C++ API has been updated to use std::vector instead of std::map, std::list, and std::set for header handling. The get_response_headers() method (returning the full headers map) has been removed — use get_response_header(name) instead. Deprecated overloads using the old container types are provided until 2027.1.0.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14024: Modernize response header handling PR #14027: Modernize request header handling

The http_request API used heavyweight STL containers (std::map, std::list, std::set) for header storage. These containers pull in significant template code (red-black trees, linked lists) and allocate heavily on the heap. Replacing them with std::vector<Header> reduces flash usage and heap fragmentation.

What’s Changing

Response headers (PR #14024)

Before	After
`std::map<std::string, std::list<std::string>>`	`std::vector<Header>`
`std::set<std::string>` for collect_headers	`std::vector<std::string>` (pre-lowercased)
`get_response_headers()` returns full map	Removed — use `get_response_header(name)`
`collect_headers` parameter	Renamed to `lower_case_collect_headers`
`start()` with `std::set` overload	Deprecated (removal 2027.1.0)

Request headers (PR #14027)

Before	After
`std::list<Header>` in `perform()`, `start()`, `get()`, `post()`	`std::vector<Header>`
`std::list<Header>` overloads for `start()`, `get()`, `post()`	Deprecated (removal 2027.1.0)

Who This Affects

External components that:

Use http_request APIs to make HTTP requests
Access response headers via get_response_headers()
Pass request headers as std::list<Header>
Pass collect_headers as std::set<std::string>

Standard YAML configurations are not affected.

Migration Guide

Request headers — change one word

// Before
std::list<http_request::Header> headers;
headers.push_back({"Authorization", "Bearer token"});

// After
std::vector<http_request::Header> headers;
headers.push_back({"Authorization", "Bearer token"});

Response headers — use singular getter

// Before (removed)
auto headers_map = response->get_response_headers();
auto content_type_list = headers_map["content-type"];

// After
auto value = response->get_response_header("content-type");

Collect headers — use vector with lowercase names

// Before
std::set<std::string> collect = {"Content-Type", "X-Custom"};
client->start(url, method, body, headers, collect);

// After — names must be pre-lowercased
std::vector<std::string> collect = {"content-type", "x-custom"};
client->start(url, method, body, headers, collect);

The parameter has been renamed to lower_case_collect_headers to make the lowercase requirement explicit.

Supporting Multiple ESPHome Versions

The deprecated std::list<Header> overloads compile on 2026.3.0 with warnings, so existing code continues to work during the transition. To suppress warnings:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  std::vector<http_request::Header> headers;
#else
  std::list<http_request::Header> headers;
#endif
headers.push_back({"Authorization", "Bearer token"});

For response headers, get_response_header(name) is new in 2026.3.0:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  auto value = response->get_response_header("content-type");
#else
  auto headers = response->get_response_headers();
  auto it = headers.find("content-type");
  // ...
#endif

Timeline

ESPHome 2026.3.0 (March 2026): New vector-based API active, old overloads deprecated
ESPHome 2027.1.0 (January 2027): Deprecated std::list and std::set overloads removed

Finding Code That Needs Updates

# Find std::list<Header> usage
grep -rn 'std::list.*Header' your_component/

# Find get_response_headers() (plural — removed)
grep -rn 'get_response_headers' your_component/

# Find std::set for collect_headers
grep -rn 'std::set.*collect\|collect_headers' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

Icon and Device Class Getter Migration

Thu, 12 Mar 2026 00:00:00 GMT

The get_icon_ref(), get_icon(), get_device_class_ref(), and get_device_class() methods are deprecated on all platforms and replaced by new buffer-based APIs get_icon_to() and get_device_class_to(). On ESP8266, the old methods produce a static_assert error because the underlying strings have been moved to PROGMEM and cannot be accessed through normal C string pointers. On other platforms, the old methods continue to work but emit deprecation warnings and will be removed in 2026.9.0.

This is a breaking change for external components in ESPHome 2026.3.0 and later.

Background

PR #14171: Pack entity string properties into PROGMEM-indexed fields PR #14437: Move icon strings to PROGMEM on ESP8266 PR #14443: Move device class strings to PROGMEM on ESP8266

Icon and device class strings are set at compile time and never change. PR #14171 packed these properties into PROGMEM-indexed uint8_t fields on EntityBase, replacing per-entity const char* pointers and the EntityBase_DeviceClass/EntityBase_UnitOfMeasurement mixin classes. Most entity types already had device_class and unit_of_measurement on the entity itself — the exception was NumberTraits, which previously inherited the mixin classes. NumberTraits no longer provides these accessors; use number->get_device_class_ref() / number->get_unit_of_measurement_ref() instead of number->traits.get_*_ref().

The old getter methods returned references or pointers to these strings, which required them to be stored as regular C strings in RAM. The new buffer-based APIs copy the string into a caller-provided buffer, which works regardless of where the string is stored.

On ESP8266, PRs #14437 and #14443 also move the strings into PROGMEM (flash), freeing valuable heap RAM. Since PROGMEM strings cannot be accessed through normal C string pointers on ESP8266, the old methods produce a hard static_assert error on that platform rather than a deprecation warning.

What’s Changing

Deprecated methods (all platforms, removal 2026.9.0)

Method	Replacement
`get_icon_ref()`	`get_icon_to(buffer)`
`get_icon()`	`get_icon_to(buffer)`
`get_device_class_ref()`	`get_device_class_to(buffer)`
`get_device_class()`	`get_device_class_to(buffer)`

NumberTraits: device_class and unit_of_measurement moved to entity

NumberTraits no longer provides get_device_class(), get_device_class_ref(), or get_unit_of_measurement_ref(). These are now accessed directly on the Number entity, consistent with all other entity types:

Before	After
`number->traits.get_device_class()`	`number->get_device_class_to(buffer)`
`number->traits.get_device_class_ref()`	`number->get_device_class_to(buffer)`
`number->traits.get_unit_of_measurement_ref()`	`number->get_unit_of_measurement_ref()`

EntityBase setters removed and packed into configure_entity_()

The following EntityBase setters have been removed and packed into the existing configure_entity_() call:

set_name()
set_icon()
set_device_class()
set_unit_of_measurement()
set_internal()
set_disabled_by_default()
set_entity_category()

Additionally, set_device() has been renamed to set_device_() and made protected.

These were codegen-only setters — calling them at runtime was unsafe and could silently corrupt state or crash the device (undefined behavior). If you were calling set_icon() from lambdas to dynamically change icons at runtime, move the icon logic to the Home Assistant side (e.g., using template sensors with icon templates).

See PR #14171, PR #14437, PR #14443, and PR #14564.

ESP8266-specific

On ESP8266, using any of the deprecated methods produces a static_assert error at compile time — they cannot work because the underlying strings are in PROGMEM.

New APIs

// Icon — copies into buffer, returns pointer to buffer (or nullptr if no icon set)
char icon_buf[MAX_ICON_LENGTH];
const char *icon = entity->get_icon_to(icon_buf);

// Device class — same pattern
char dc_buf[MAX_DEVICE_CLASS_LENGTH];
const char *dc = entity->get_device_class_to(dc_buf);

MAX_ICON_LENGTH and MAX_DEVICE_CLASS_LENGTH are both 64 bytes (63 characters + null terminator). Strings longer than 63 characters will produce a compile-time error.

Who This Affects

External components that:

Call get_icon_ref(), get_icon(), get_device_class_ref(), or get_device_class() on any entity — deprecation warning on all platforms, hard compile error on ESP8266
Access device_class or unit_of_measurement through NumberTraits — moved to Number entity directly
Call set_icon(), set_device_class(), set_unit_of_measurement(), or other removed EntityBase setters at runtime

Standard YAML configurations are not affected.

Migration Guide

Entity base migration

// Before
const auto &icon = entity->get_icon_ref();
const auto &dc = entity->get_device_class_ref();

// After
char icon_buf[MAX_ICON_LENGTH];
const char *icon = entity->get_icon_to(icon_buf);

char dc_buf[MAX_DEVICE_CLASS_LENGTH];
const char *dc = entity->get_device_class_to(dc_buf);

NumberTraits migration

// Before — accessed through traits (only Number had this pattern)
auto dc = number->traits.get_device_class();       // or get_device_class_ref()
auto uom = number->traits.get_unit_of_measurement_ref();

// After — accessed directly on entity, consistent with all other entity types
char dc_buf[MAX_DEVICE_CLASS_LENGTH];
const char *dc = number->get_device_class_to(dc_buf);
const auto &uom = number->get_unit_of_measurement_ref();

Checking if icon/device class is set

// Before
const auto &icon = entity->get_icon_ref();
if (!icon.empty()) {
  // use icon
}

// After
char icon_buf[MAX_ICON_LENGTH];
const char *icon = entity->get_icon_to(icon_buf);
if (icon != nullptr) {
  // use icon
}

Supporting Multiple ESPHome Versions

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 3, 0)
  char icon_buf[MAX_ICON_LENGTH];
  const char *icon = entity->get_icon_to(icon_buf);
#else
  const auto &icon = entity->get_icon_ref();
#endif

Timeline

ESPHome 2026.3.0 (March 2026): Old methods deprecated, static_assert on ESP8266, new buffer APIs available
ESPHome 2026.9.0 (September 2026): Old methods removed on all platforms

Finding Code That Needs Updates

# Find deprecated method usage
grep -rn 'get_icon_ref\|get_icon()' your_component/
grep -rn 'get_device_class_ref\|get_device_class()' your_component/

# Find NumberTraits accessors that moved to entity
grep -rn 'traits\.get_device_class\|traits\.get_unit_of_measurement' your_component/

# Find removed EntityBase setters
grep -rn 'set_icon\|set_device_class\|set_unit_of_measurement\|set_internal\|set_disabled_by_default\|set_entity_category\|set_name(' your_component/

Questions?

If you have questions about migrating your external component, please ask in:

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

ESPHome Developer Documentation | Blog

ClimateTraits Boolean Accessors Removed in Favor of Feature Flags

Background

What’s Changing

Watch for two_point_target_temperature

Who This Affects

Migration Guide

Timeline

Finding Code That Needs Updates

Questions?

Related Documentation

Default-Constructed PollingComponent No Longer Polls

Background

What’s Changing

Who This Affects

Migration Guide

Finding Code That Needs Updates

Questions?

Related Documentation

FloatOutput Power Scaling Fields Gated Behind USE_OUTPUT_FLOAT_POWER_SCALING

Background

Measured savings

What’s Changing

Who This Affects

Migration Guide

YAML lambda users — add one line of YAML

External component authors — declare the define

Finding Code That Needs Updates

Questions?

Related Documentation

Main Loop Cadence Decoupled from Scheduler Wake Timing

Background

What was happening

Why it happened

What’s Changing

Who This Affects

Migration Guide

Finding Code That Needs Updates

Questions?

Related Documentation

Modbus Server Split Out of modbus_controller

Background

Flash savings (approximate)

What’s Changing

YAML keys moved

modbus_controller is now client-only

Who This Affects

Migration Guide

Timeline

Finding Code That Needs Updates

Questions?

Related Documentation

RingBuffer Moved Out of Core Into ring_buffer Helper Component

Background

What’s Changing

C++ include and namespace

Python codegen — declare AUTO_LOAD

Who This Affects

Migration Guide

Timeline

Finding Code That Needs Updates

Questions?

Related Documentation

BLE Event Handler Dispatch Devirtualized

Background

What’s Changing

Who This Affects

Migration Guide

C++ changes

Python codegen

Supporting Multiple ESPHome Versions

Timeline

Finding Code That Needs Updates

Questions?

Related Documentation

CallbackManager: std::function Replaced with Lightweight Callback

Background

Measured savings

What’s Changing

Who This Affects

Watch for `two_point_target_temperature`

`modbus_controller` is now client-only

Python codegen — declare `AUTO_LOAD`