ESPHome Developer Documentation | Blog

remote_base Protocol Methods Are No Longer Virtual and Receiver Lists Are Sized From Codegen

Wed, 14 Oct 2026 00:00:00 GMT

RemoteProtocol<T> no longer declares encode(), decode() and dump() as virtual, the receiver’s listener and dumper lists are fixed size StaticVectors sized during code generation, and a protocol’s source file is only compiled when the configuration uses it. External components that derive from RemoteProtocol, that register listeners or dumpers from C++, or that use a protocol class from their own C++ need small changes.

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

Background

PR #19084: Make protocol methods non-virtual and size receiver lists from codegen

Every protocol class was derived from RemoteProtocol<T>, but nothing ever used one through a base pointer: dumpers, triggers, binary sensors and transmit actions are all templates on the concrete protocol type. The virtual methods only cost a vtable per protocol and kept the linker from dropping the encode(), decode() and dump() bodies a build never calls. The receiver kept its listeners and dumpers in std::vectors that grew on the heap during setup, even though code generation knows exactly how many there are. The CI memory report on the PR measured 14.6 KB less flash on the ESP8266 test build with a receiver and the ir_rf_proxy platforms, and 11.9 KB less on the ESP32 IDF build; the rc_switch protocol table also moves from RAM into flash.

Why a clean break

Every protocol added to remote_base has cost every user of the component, whether their configuration used it or not: with the methods virtual and every source file always compiled, each protocol’s vtable, its encode(), decode() and dump() bodies and its dumper and trigger instantiations all stayed in the image. There are 35 protocols in tree and more arrive most releases, so that per-protocol tax kept growing for every remote_receiver and remote_transmitter user, most of whom use one or two protocols. Making the methods non-virtual and compiling only the requested sources removes the tax. There is no way to keep override compiling on a method that is no longer virtual, so a deprecation window is not possible and the change lands as a clean break with this guide.

What’s Changing

Four things, each with its own migration step below:

RemoteProtocol<T> only supplies the ProtocolData alias and no longer declares the protocol methods. encode(), decode() and dump() are plain member functions, checked by C++20 concepts wherever a protocol is used.
RemoteReceiverBase::register_listener() and register_dumper() only accept a registration when code generation counted a slot for it; with no slot counted the call fails a static_assert. A registration from C++ setup() has no slot.
A protocol’s *_protocol.cpp in remote_base is only compiled when something in the configuration requests it: a dumper, a trigger, a binary sensor, a transmit action, or an explicit request from a component’s to_code(). A protocol that ships in your own component is compiled as before.
The protected call_listeners_() and call_dumpers_() on RemoteReceiverBase are merged into call_listeners_dumpers_(), which already existed.

Who This Affects

External components that:

derive a protocol class from remote_base::RemoteProtocol<T> and mark its methods override
call register_listener() or register_dumper() on a remote receiver from C++
use a protocol class bundled in remote_base, such as remote_base::NECProtocol, from their own C++ without a dumper, trigger, binary sensor or transmit action for it in the configuration
call encode(), decode() or dump() through a RemoteProtocol<T> pointer or reference; the base no longer declares them, so the error is no member named 'decode' rather than a message about override

Standard YAML configurations are not affected, with one exception: a lambda that calls id(tx).transmit<remote_base::NECProtocol>(data) needs that protocol referenced somewhere else in the configuration, see below.

Migration Guide

Protocol classes: drop `override`

The methods are no longer virtual, so the compiler reports each override:

// Before
class MyProtocol : public RemoteProtocol<MyData> {
 public:
  void encode(RemoteTransmitData *dst, const MyData &data) override;
  optional<MyData> decode(RemoteReceiveData src) override;
  void dump(const MyData &data) override;
};

// After
class MyProtocol : public RemoteProtocol<MyData> {
 public:
  void encode(RemoteTransmitData *dst, const MyData &data);
  optional<MyData> decode(RemoteReceiveData src);
  void dump(const MyData &data);
};

The signatures are unchanged. The RemoteProtocolDecoder, RemoteProtocolDumper and RemoteProtocolEncoder concepts check them wherever the protocol is used, so a mismatch is reported at the DECLARE_REMOTE_PROTOCOL(...) line, normally in the protocol’s own header; a protocol declared without that macro sees it at its first use.

Listeners and dumpers: register from Python

The receiver’s lists are sized during code generation. A component that registered itself from C++ has no slot:

// Before, in setup()
this->receiver_->register_listener(this);

Register from to_code() instead, so the slot is counted. For a component whose schema uses CONF_RECEIVER_ID, one call does both halves:

from esphome.components import remote_base

async def to_code(config):
    var = cg.new_Pvariable(config[CONF_ID])
    await cg.register_component(var, config)
    # sets the receiver on the entity and registers it as a listener
    await remote_base.attach_receiver(var, config)

attach_receiver(var, config, key=...) accepts a different config key, remote_base.register_listener(var, config) registers without calling set_receiver(), and remote_base.add_listener(receiver, var) and remote_base.add_dumper(receiver, dumper) take the receiver object directly. The slot counting lives in these helpers: a hand written cg.add(receiver.register_listener(var)) emits the call but counts no slot, so it fails the same way the C++ registration does.

When a configuration counted no slot at all, a C++ registration fails the build with a message naming this fix; when the counted slots are already used, the registration is dropped and the same message is logged as an error at boot, so the listener or dumper never receives data. Check the boot log for No listener slot or No dumper slot after migrating.

Bundled protocols used from C++: request the source file

A component that uses one of the protocol classes bundled in remote_base directly in C++, with no dumper, trigger, binary sensor or transmit action for it in the configuration, must keep the source file in the build:

# in to_code()
remote_base.request_protocol("coolix")

The name is the protocol’s source file without the _protocol.cpp suffix: NECProtocol lives in nec_protocol.cpp, so it is "nec"; RCSwitchBase lives in rc_switch_protocol.cpp, so it is "rc_switch". Otherwise the protocol’s .cpp is filtered out and the link fails with an undefined reference to its encode(), decode() or dump(). Unknown names raise during code generation and list the valid ones.

A protocol that ships in your own component needs no request. Only the source files in remote_base are filtered, so registering your protocol with register_trigger, register_dumper, register_binary_sensor or register_action works as before, and request_protocol only accepts the bundled names.

The same applies to a YAML lambda that uses a protocol class, for example id(tx).transmit<remote_base::NECProtocol>(data): reference that protocol somewhere else in the configuration, with a dump entry, an on_nec trigger or a remote_transmitter.transmit_nec action.

Receiver platforms: one call for listeners and dumpers

A platform deriving from RemoteReceiverBase that called the protected call_listeners_() and call_dumpers_() separately now calls call_listeners_dumpers_(), which already existed as the combined entry point; the two were merged so each list can compile out on its own.

Supporting Multiple ESPHome Versions

override on a method that is no longer virtual is a compile error, so a component that has to build on 2026.9 and 2026.10 needs a version guard around the declarations:

#include "esphome/core/version.h"

class MyProtocol : public RemoteProtocol<MyData> {
 public:
#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 10, 0)
  void encode(RemoteTransmitData *dst, const MyData &data);
  optional<MyData> decode(RemoteReceiveData src);
  void dump(const MyData &data);
#else
  void encode(RemoteTransmitData *dst, const MyData &data) override;
  optional<MyData> decode(RemoteReceiveData src) override;
  void dump(const MyData &data) override;
#endif
};

For listeners, remote_base.register_listener(var, config) exists on both versions, so a component whose schema uses CONF_RECEIVER_ID can move the registration to Python once and drop the C++ call with no guard. The guard below is only for a component whose receiver option has another name, since attach_receiver, add_listener, add_dumper and request_protocol only exist from 2026.10.0; keep the C++ registration for older versions:

# in to_code()
try:
    from esphome.components.remote_base import attach_receiver
except ImportError:
    # ESPHome < 2026.10.0 registers the listener from setup()
    receiver = await cg.get_variable(config[CONF_REMOTE_RECEIVER_ID])
    cg.add(var.set_receiver(receiver))
else:
    await attach_receiver(var, config, key=CONF_REMOTE_RECEIVER_ID)

void MyComponent::setup() {
#if ESPHOME_VERSION_CODE < VERSION_CODE(2026, 10, 0)
  this->receiver_->register_listener(this);
#endif
}

request_protocol follows the same shape for a bundled protocol; before 2026.10.0 every protocol source file is compiled, so the failing import is safe to ignore.

Timeline

ESPHome 2026.10.0 (October 2026): protocol methods are no longer virtual, receiver lists are sized from codegen, unused protocol sources are not compiled. No deprecation period: override on a non-virtual method cannot be kept compiling.

Finding Code That Needs Updates

# Protocol classes that still mark the methods override
grep -rn 'RemoteProtocol<' your_component/
grep -rnE '(encode|decode|dump)\(.*\) override' your_component/

# Listener or dumper registration from C++
grep -rnE 'register_listener|register_dumper' your_component/

# Receiver platforms calling the split helpers
grep -rnE 'call_listeners_\(|call_dumpers_\(' your_component/

# Protocol classes used from C++ or lambdas
grep -rnE 'remote_base::([A-Za-z0-9]*Protocol|RCSwitchBase)' your_component/ your_configs/

Questions?

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

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

InternalGPIOPin Is the Platform Pin Class Instead of a Virtual Base

Fri, 09 Oct 2026 00:00:00 GMT

InternalGPIOPin is no longer an abstract class. It is now a type alias for the one pin class each platform provides (esp32::ESP32InternalGPIOPin, esp8266::ESP8266GPIOPin, rp2::RP2GPIOPin, libretiny::ArduinoInternalGPIOPin, zephyr::ZephyrGPIOPin or host::HostGPIOPin), so every call through an InternalGPIOPin * is a direct call. GPIOPin keeps its virtual interface.

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

Background

PR #20455: Bind InternalGPIOPin to the platform pin class instead of a virtual base

Every image contains exactly one internal pin implementation, chosen by the platform at build time. InternalGPIOPin was still an abstract class on top of it, so get_pin(), is_inverted(), to_isr(), attach_interrupt() and detach_interrupt() all went through a vtable for no reason, and the compiler could not inline the trivial getters. Preferences and the OTA backend had the same shape and were already converted to a concept-checked alias; this change applies the same pattern to pins.

GPIOPin is a different case and stays virtual. Which class sits behind a GPIOPin * is decided per configuration between the internal pin and the I/O expander pins (pcf8574, mcp23xxx, sx1509 and others), so that polymorphism is real.

Flash and RAM

Measured on esp32-idf builds of the test configurations, plus a timer-only deep_sleep configuration with no pins:

Configuration	Flash before	Flash after	RAM
gpio switch, output and binary sensor	200439	200375	unchanged
pulse_counter	197927	197867	unchanged
dht	199351	197819	8 bytes less
deep_sleep, timer only, no pins	198079	198131	unchanged

Components that drive a pin many times, like dht’s bit-banged read, gain the most. The last row is the one configuration that grows: ESP32 used to leave its pin source out of a build with no pins, and the direct calls now need those methods to link, so the file is always compiled and the linker keeps only what is referenced.

What’s Changing

esphome/core/gpio.h includes the platform’s pin header and declares using InternalGPIOPin = <platform class>;, checked by a static_assert on the new InternalGPIOPinContract concept.
GPIOPin, the gpio::Flags enum, ISRInternalGPIOPin and the concept live in the new esphome/core/gpio_pin.h. Including esphome/core/gpio.h or esphome/core/hal.h still gives you everything it did before.
The platform pin classes, which were already final, derive from GPIOPin directly. The protected hook that takes a void (*)(void *) callback is now named attach_interrupt_(); the public attach_interrupt<T>() template is unchanged.
GPIOPin::is_internal() now carries a rule: only the platform pin class behind the alias may return true, because callers static_cast to InternalGPIOPin on it.
The USE_ESP32_INTERNAL_GPIO define is gone.

Who This Affects

External components that:

Derive a class from InternalGPIOPin, for example a pin implementation for a platform ESPHome does not ship, or a dummy pin in a unit test.
Derive from InternalGPIOPin only to reach the protected attach_interrupt overload that takes a void (*)(void *).
Derive from GPIOPin and return true from is_internal().
Forward declare it with class InternalGPIOPin; instead of including esphome/core/gpio.h.

Components that take an InternalGPIOPin * or a GPIOPin * are not affected unless they forward declare it. Setters such as set_pin(InternalGPIOPin *pin), calls like pin->get_pin() or pin->attach_interrupt(...), and I/O expander pins that derive from GPIOPin compile unchanged. Standard YAML configurations are not affected.

Migration Guide

A subclass of InternalGPIOPin

Before, InternalGPIOPin was an abstract class and an external component could provide its own pin implementation behind it. The name now resolves to the platform’s pin class, which was already final, so a subclass fails with an error such as base 'HostGPIOPin' is marked 'final'. Such a pin can derive from GPIOPin instead, which works everywhere a component takes a GPIOPin * but offers no interrupt API. A project that already overrides a platform component through external_components can instead supply its class as that platform’s pin class, which the alias then picks up, or the platform can be contributed to ESPHome itself.

Reaching the raw attach_interrupt

The public attach_interrupt<T>() template and the protected hook that takes a void (*)(void *) shared one name. A call with a plain void * callback picked the protected overload and failed to compile, so some components derived from InternalGPIOPin only to make it visible:

// Before
struct ExposeInternalPin : public InternalGPIOPin {
  using InternalGPIOPin::attach_interrupt;
};
static_cast<ExposeInternalPin *>(pin)->attach_interrupt(my_isr, arg, gpio::INTERRUPT_ANY_EDGE);

The hook is now attach_interrupt_(), so the template is the only attach_interrupt and takes the void * form as well (T deduces to void). Call it directly:

// After
pin->attach_interrupt(my_isr, arg, gpio::INTERRUPT_ANY_EDGE);

A forward declaration of InternalGPIOPin

A header that only holds pin pointers could declare the class instead of including its header. The name is now an alias, and declaring it as a class fails. On ESP8266, for example, GCC reports error: using typedef-name 'using InternalGPIOPin = class esphome::esp8266::ESP8266GPIOPin' after 'class' when esphome/core/gpio.h was already included, or error: conflicting declaration 'using InternalGPIOPin = class esphome::esp8266::ESP8266GPIOPin' in gpio.h when the forward declaration comes first:

// Before
namespace esphome {
class InternalGPIOPin;
}  // namespace esphome

Include the header instead; this works on every ESPHome version, so no version guard is needed:

// After
#include "esphome/core/gpio.h"

A GPIOPin subclass that returns true from is_internal()

Return false. Callers that see true cast the pointer to the platform pin class, so any other class returning true is undefined behavior.

Supporting Multiple ESPHome Versions

The raw attach_interrupt call is the one place a version guard is needed, and only when the callback must keep its void * signature:

#if ESPHOME_VERSION_CODE >= VERSION_CODE(2026, 11, 0)
pin->attach_interrupt(my_isr, arg, gpio::INTERRUPT_ANY_EDGE);
#else
struct ExposeInternalPin : public InternalGPIOPin {
  using InternalGPIOPin::attach_interrupt;
};
static_cast<ExposeInternalPin *>(pin)->attach_interrupt(my_isr, arg, gpio::INTERRUPT_ANY_EDGE);
#endif

A typed callback avoids the guard altogether, because the public template has accepted it on every version:

static void my_isr(MyComponent *self);
pin->attach_interrupt(my_isr, this, gpio::INTERRUPT_ANY_EDGE);

Timeline

ESPHome 2026.11.0 (November 2026): InternalGPIOPin becomes the platform pin class
No deprecation period: once the name refers to a final class, nothing can keep a subclass of it compiling

Finding Code That Needs Updates

# List every reference, then check the base lists: a class that names InternalGPIOPin
# as any of its bases is affected, as is a GPIOPin subclass whose is_internal() returns true
# and any `class InternalGPIOPin;` forward declaration
grep -rn 'InternalGPIOPin\|is_internal() override' your_component/

Questions?

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

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

PR #20455: Bind InternalGPIOPin to the platform pin class instead of a virtual base

Select Options and Light Effects Move to ConstVector

Mon, 05 Oct 2026 00:00:00 GMT

ESPHome 2026.10.0 stores select options and light effects in flash tables generated at build time instead of copying them onto the heap at boot. The getters now return a ConstVector view instead of a FixedVector. Code that binds the result with auto and uses the common read only members keeps working; code that names the old type, or calls front(), back(), capacity() or full(), needs a small change.

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

Background

Select options and light effects are fixed when the firmware is built, but both were copied into a heap FixedVector during setup(). On ESP8266 the list literal that codegen passed in also sat in .rodata, which is RAM there, so each list cost RAM twice. The API also built a temporary heap vector of effect names every time Home Assistant listed a light.

Codegen now emits each list as a table in flash, and the entity keeps a small ConstVector view of it (a pointer and a size). Selects with identical option lists share one table.

Changes

PR #20117: select options are stored in a shared flash table; adds the core ConstVector<T, Owning> type.
PR #20204: light effects are stored in a flash table, and the API lists effect names straight from it.

What’s Changing

Select

// OLD
const FixedVector<const char *> &get_options() const;

// NEW
const SelectOptions &get_options() const;  // SelectOptions = ConstVector<const char *, true>

All set_options(...) overloads keep their behavior: they copy the list you pass, so runtime option lists from lambdas or external components work exactly as before. SelectTraits stays non copyable, as it was with FixedVector. A new set_options_static(table, count) is used by generated code only.

Light

// OLD
const FixedVector<LightEffect *> &get_effects() const;
void add_effects(const std::initializer_list<LightEffect *> &effects);

// NEW
const ConstVector<LightEffect *> &get_effects() const;
void add_effects(LightEffect *const *effects, size_t count);  // generated code only

add_effects() is only called by generated code; no external callers were found.

Who This Affects

Standard YAML configurations need no changes.

Lambdas and external components keep working if they use any of these, which covers every use found in a GitHub code search:

const auto &opts = id(my_select).traits.get_options(); and const auto &effects = id(my_light).get_effects();
range based for, size(), empty(), [], at(), data()
std::find(list.begin(), list.end(), value), including const auto *it = std::find(...): the iterators are raw pointers, as they were with FixedVector

Code that breaks is code that spells out the old type:

// OLD - no longer compiles
const FixedVector<const char *> &opts = id(my_select).traits.get_options();
const FixedVector<LightEffect *> &effects = id(my_light).get_effects();

// NEW - let the compiler pick the type
const auto &opts = id(my_select).traits.get_options();
const auto &effects = id(my_light).get_effects();

ConstVector also drops the front(), back(), capacity() and full() members that FixedVector had, so calls to them fail even when the result is bound with auto. For a non empty list, use list[0] instead of front() and list[list.size() - 1] instead of back(). The list never grows after it is set, so capacity() is the same as size() and full() is always true.

// OLD - no longer compiles
const char *first = id(my_select).traits.get_options().front();

// NEW
const auto &opts = id(my_select).traits.get_options();
const char *first = opts[0];  // check opts.empty() first if the list can be empty

Copying the light effect list into a local variable (const auto effects = id(my_light).get_effects();) failed to compile since FixedVector was introduced; it compiles again now, because the light effect view is a cheap, non owning copy of a flash table. Copying a select’s options is still not allowed, since a select may own a runtime copy.

ConstVector

ConstVector<T> in esphome/core/helpers.h is a read only view of a table: a pointer and a size, with raw pointer iterators. The owning variant, ConstVector<T, true>, can also hold a heap copy for lists set at runtime; it marks ownership in the top bit of the size, so it stays a pointer and a size (8 bytes on 32 bit targets). Element types must be whole words (pointers or other 32 bit values), because ESP8266 can only read flash with aligned 32 bit loads.

Other entity lists set at build time can move to ConstVector the same way.

Finding Code That Needs Updates

grep -rnE 'FixedVector<[[:space:]]*(const char|LightEffect)[[:space:]]*\*[[:space:]]*>|get_(options|effects)\(\)\.(front|back|capacity|full)\(' --include='*.cpp' --include='*.h' --include='*.yaml'

The pattern also matches FixedVector<const char *> uses unrelated to selects, such as event types; only the ones holding select options need changing. It does not catch front() or back() called on a variable that holds the list, so check those by hand.

Timeline

ESPHome 2026.10.0: select options (#20117) and light effects (#20204) use ConstVector.

Questions?

If you have questions about these changes or need help migrating your external component, please ask in the ESPHome Discord or open a discussion on GitHub.

nRF52: nRF Connect SDK Projects Fetched Only When Needed

Sat, 26 Sep 2026 00:00:00 GMT

nRF52 builds with the native sdk-nrf toolchain now download only the nRF Connect SDK west projects a build needs, instead of all of them. External components that use an SDK module outside the default set must request it with include_west_project().

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

Background

PR #19735: Fetch only the nRF Connect SDK projects a build needs

The nRF Connect SDK manifest lists about 50 west projects, 2.2 GB on disk, and most of them serve features ESPHome never uses (Matter, TF-M, WiFi, LoRaWAN, Azure IoT and more). Matter and cmock also pull git submodules with their full history. The first nRF52 build downloaded all of it.

A fresh install now fetches four projects (five from SDK 3.1), about 1 GB on disk instead of 2.2 GB and roughly a third of the previous download, and a component adds whatever else it needs.

What’s Changing

These west projects are always fetched:

Project	Provides
`zephyr`	Zephyr RTOS
`hal_nordic`	nrfx drivers and the MDK
`nrfxlib`	SoftDevice Controller, MPSL, ZBOSS and other Nordic libraries
`cmsis`	Arm CMSIS headers
`cmsis_6`	Arm CMSIS 6 core headers, SDK 3.1 and later

Every other project in the manifest is left out unless a component asks for it. The install is shared by every config on the machine, so a later build that needs another project fetches only what is missing; nothing is removed again.

ESPHome’s built-in components already request what they use:

Project	Requested by
`tinycrypt` up to SDK 3.1, `mbedtls` and `oberon-psa-crypto` from 3.2	`zephyr_ble_server` (and `ble_nus` through it)
`segger`	`debug` (RTT logging)
`openthread` and `mbedtls`; `oberon-psa-crypto` too from SDK 2.7	`openthread`
`zcbor`, `mcuboot`	`zephyr_mcumgr` OTA
`mcuboot`	any build with sysbuild on

An SDK installed before this change keeps every project and is not touched.

Who This Affects

External components that use a Zephyr or nRF Connect SDK module from a project outside the default set, for example CMSIS DSP, LittleFS or FatFs, without one of the built-in components above pulling it in.

Standard YAML configurations are not affected; the built-in components request the projects they need.

There is no YAML override for users: an external component that needs another project has to be updated to request it.

Migration Guide

Call include_west_project() from your component’s to_code() with the west project name from the SDK manifest (nrf/west.yml, or the zephyr/west.yml it imports):

# In your component's __init__.py
from esphome.components.nrf52.framework import include_west_project


async def to_code(config):
    include_west_project("cmsis-dsp")
    # ... rest of to_code

The call only records the project; the download happens when the build installs the SDK. Project names change between SDK versions (TinyCrypt left the manifest in SDK 3.2, for example), so check CORE.data[KEY_CORE][KEY_FRAMEWORK_VERSION] when a project only exists in some of them. A name the manifest does not have fails the build with a message listing the requested projects.

Supporting Multiple ESPHome Versions

async def to_code(config):
    try:
        from esphome.components.nrf52.framework import include_west_project
    except ImportError:
        # ESPHome < 2026.10.0 fetches every project
        pass
    else:
        include_west_project("cmsis-dsp")

Build Errors

A missing project shows up as a Kconfig symbol that cannot be enabled or a header that cannot be found:

warning: TINYCRYPT (defined at modules/Kconfig.tinycrypt:9) has direct dependencies ... with value n
fatal error: zcbor_common.h: No such file or directory

The fix is to add the matching include_west_project() call. To see every project and which ones were left out, run west list -a -f "{name} {active}" in the SDK folder, frameworks/<version> under ~/Library/Caches/esphome/sdk-nrf on macOS, ~/.cache/esphome/sdk-nrf on Linux and %LOCALAPPDATA%\esphome\Cache\sdk-nrf on Windows, or under ESPHOME_SDK_NRF_PREFIX when that is set. The west module lives in the matching penvs/<version> Python environment next to it.

Timeline

ESPHome 2026.10.0 (October 2026): only the default projects are fetched
No deprecation period; behavior changed directly

Questions?

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

ESPHome Discord - #devs channel
ESPHome GitHub Discussions

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

ESPHome Developer Documentation | Blog

remote_base Protocol Methods Are No Longer Virtual and Receiver Lists Are Sized From Codegen

Background

Why a clean break

What’s Changing

Who This Affects

Migration Guide

Protocol classes: drop override

Listeners and dumpers: register from Python

Bundled protocols used from C++: request the source file

Receiver platforms: one call for listeners and dumpers

Supporting Multiple ESPHome Versions

Timeline

Finding Code That Needs Updates

Questions?

Related Documentation

InternalGPIOPin Is the Platform Pin Class Instead of a Virtual Base

Background

Flash and RAM

What’s Changing

Who This Affects

Migration Guide

A subclass of InternalGPIOPin

Reaching the raw attach_interrupt

A forward declaration of InternalGPIOPin

A GPIOPin subclass that returns true from is_internal()

Supporting Multiple ESPHome Versions

Timeline

Finding Code That Needs Updates

Questions?

Related Documentation

Select Options and Light Effects Move to ConstVector

Background

Changes

What’s Changing

Select

Light

Who This Affects

ConstVector

Finding Code That Needs Updates

Timeline

Questions?

nRF52: nRF Connect SDK Projects Fetched Only When Needed

Background

What’s Changing

Who This Affects

Migration Guide

Supporting Multiple ESPHome Versions

Build Errors

Timeline

Questions?

Related Documentation

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?

Protocol classes: drop `override`

Watch for `two_point_target_temperature`

`modbus_controller` is now client-only

Python codegen — declare `AUTO_LOAD`