ESPHome Developer Documentation

Modbus Server Split Out of modbus_controller

J. Nick Koston — Wed, 03 Jun 2026 22:11:30 +0000

Modbus Server Split Out of modbus_controller

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.

Main Loop Cadence Decoupled from Scheduler Wake Timing

J. Nick Koston — Wed, 03 Jun 2026 22:11:25 +0000

Main Loop Cadence Decoupled from Scheduler Wake Timing

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.

ClimateTraits Boolean Accessors Removed in Favor of Feature Flags

J. Nick Koston — Wed, 03 Jun 2026 22:08:56 +0000

ClimateTraits Boolean Accessors Removed in Favor of Feature Flags

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.

FloatOutput Power Scaling Fields Gated Behind USE_OUTPUT_FLOAT_POWER_SCALING

J. Nick Koston — Wed, 03 Jun 2026 22:08:41 +0000

FloatOutput Power Scaling Fields Gated Behind USE_OUTPUT_FLOAT_POWER_SCALING

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.

Default-Constructed PollingComponent No Longer Polls

J. Nick Koston — Wed, 03 Jun 2026 22:08:33 +0000

Default-Constructed PollingComponent No Longer Polls

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.

RingBuffer Moved Out of Core Into ring_buffer Helper Component

J. Nick Koston — Mon, 18 May 2026 13:33:48 +0000

RingBuffer Moved Out of Core Into ring_buffer Helper Component

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.

TemplatableFn: 4-Byte Templatable Storage for Trivially Copyable Types

J. Nick Koston — Thu, 09 Apr 2026 23:59:26 +0000

TemplatableFn: 4-Byte Templatable Storage for Trivially Copyable Types

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.

wake_loop Moved from Socket Component into Core

J. Nick Koston — Thu, 09 Apr 2026 23:24:44 +0000

wake_loop Moved from Socket Component into Core

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.

BLE Event Handler Dispatch Devirtualized

J. Nick Koston — Thu, 09 Apr 2026 23:19:12 +0000

BLE Event Handler Dispatch Devirtualized

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.

Climate and Fan Custom Mode Vectors Moved to Entity

J. Nick Koston — Thu, 09 Apr 2026 23:17:33 +0000

Climate and Fan Custom Mode Vectors Moved to Entity

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.

Modbus Helper Functions Moved to modbus::helpers

J. Nick Koston — Thu, 09 Apr 2026 23:17:23 +0000

Modbus Helper Functions Moved to modbus::helpers

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.

Trigger Trampolines Eliminated with build_callback_automation

J. Nick Koston — Thu, 09 Apr 2026 23:16:35 +0000

Trigger Trampolines Eliminated with build_callback_automation

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.

Sensor .raw_state Deprecated in Favor of get_raw_state()

J. Nick Koston — Thu, 09 Apr 2026 23:13:12 +0000

Sensor .raw_state Deprecated in Favor of get_raw_state()

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.

FlushResult Renamed to UARTFlushResult

J. Nick Koston — Thu, 09 Apr 2026 22:14:54 +0000

FlushResult Renamed to UARTFlushResult

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.

CallbackManager: std::function Replaced with Lightweight Callback

J. Nick Koston — Thu, 09 Apr 2026 22:08:33 +0000

CallbackManager: std::function Replaced with Lightweight Callback

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.

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

J. Nick Koston — Fri, 27 Mar 2026 18:18:45 +0000

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

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

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

UART flush() Now Returns FlushResult

J. Nick Koston — Fri, 27 Mar 2026 18:18:35 +0000

UART flush() Now Returns FlushResult

The UARTComponent::flush() method return type has changed from void to FlushResult. External components that subclass UARTComponent and override flush() must update their override to return a FlushResult value.

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

register_action Now Requires Explicit synchronous= Parameter

J. Nick Koston — Fri, 27 Mar 2026 18:18:25 +0000

register_action Now Requires Explicit synchronous= Parameter

All register_action() calls now require an explicit synchronous=True or synchronous=False parameter. This enables the StringRef optimization for synchronous actions (zero-copy string argument passing) while ensuring asynchronous actions safely use owning std::string to prevent dangling references. Existing external components will continue to work but will see a warning at config time until updated.

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

Socket Abstraction Layer Devirtualized

J. Nick Koston — Fri, 27 Mar 2026 18:18:12 +0000

Socket Abstraction Layer Devirtualized

The socket::Socket and socket::ListenSocket types have been changed from virtual base classes to concrete type aliases. Listen sockets now use the ListenSocket type instead of Socket. These changes save 1,020–3,228 bytes of flash across platforms by eliminating virtual dispatch overhead.

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

get_loop_priority() Now Conditionally Compiled with USE_LOOP_PRIORITY

J. Nick Koston — Fri, 27 Mar 2026 18:17:58 +0000

get_loop_priority() Now Conditionally Compiled with USE_LOOP_PRIORITY

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

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