Repository navigation
Releases
2026.12.0-dev | ESPHome Runtime Controller
- Use ESPHome's bounded ring buffer for the pending event queues and store resolved activity indices in queued events. The measured event storage reduction on S3 and P4 is 1,280 bytes.
- Use native automation helpers for the existing controller actions and conditions and keep their YAML interfaces.
- Validate both supported native automation assembly forms in CI.
2026.11.1-dev: compact queues and payload reuse checks
Runtime Controller 2026.11.1-dev
Development preview from dev.
Compact configuration and queued events
This preview includes the compact runtime storage already present on dev.
Generated event rules use immutable indexed tables, mutable configuration is
sized to each expanded profile, and queued events store the payload needed for
their actual input kind. Event and action queues retain their established
capacities and FIFO semantics. Nested callbacks enqueue work for the main loop;
captured VoIP state changes retain their order.
Optional observers and output adapters remain compile gated. The reducer and
its normal voice, music, call and presentation policy owners are unchanged by
the latest test update. See the component guide.
FIFO payload reuse regression gate
The latest commit adds a host regression test for mixed named events, batched
activity updates and VoIP observations while reusing every queue slot. It
checks FIFO ordering, payload lifetime and the existing overflow boundary under
ASan/UBSan. The focused test passed with no failures or skips.
This last commit changes tests only. It introduces no new runtime behavior and
does not establish additional physical audio, wake-word or display qualification.
2026.11.0: ESPHome 2026.10 and native source observers
One device, fewer arguments between callbacks
Music is playing when a call arrives. The device shows the call, keeps track of
the music and returns to its music indication when you hang up. Add Assist,
timers and mute controls, and the same principle still applies.
This release makes that coordination much easier to configure: connect your
existing components, choose the indications you want and use ordinary ESPHome
actions. The LED can finally retire from middle management.
Observe your components and write normal automations
Use native source observation with presentation triggers such as on_music,
on_ringing, on_call, on_listening, on_responding, on_timer and on_idle.
Existing lights, effects, scripts and displays carry out the actions.
For a device that already has a media player named speaker_media_player and a
light named status_led with a Pulse effect:
runtime_controller:
id: runtime
observe:
media_player: speaker_media_player
on_music:
then:
- light.turn_on:
id: status_led
effect: Pulse
on_idle:
then:
- light.turn_off: status_ledThe example supplies its presentation activities and event mapping automatically.
Add your phone, assistant or other sources to the same controller as you need
them. Explicit activity graphs and existing outputs.led configurations remain
available for advanced setups.
A presentation trigger runs when that state becomes the selected indication.
If music is interrupted by a call and is still active afterwards, on_music
runs again when music becomes visible. The existing music activity supplies that return directly. The light component owns the effect; Runtime Controller chooses
when to request it.
Connect each source once
Direct observation now also covers Voice Assistant, Micro Wake Word, Assist
timers and HA API presence, alongside the existing VoIP, media, Wi-Fi and mute
connections.
| Source | Configuration |
|---|---|
| Phone | observe.voip_stack: phone |
| Media player | observe.media_player: speaker_media_player |
| Voice Assistant | observe.voice_assistant: va |
| Wake word | observe.micro_wake_word: mww |
| Assist timers | observe.timers: va |
| HA API connection | observe.api: true |
| Wi-Fi | observe.wifi: true |
| Mute switches | observe.microphone_mute and observe.speaker_mute |
Use the IDs already declared in your firmware. These bindings connect the components already declared in the firmware.
Voice, wake-word, timer and API observations join the source's official
automation chain while preserving your other actions and delays. Remove
callbacks that only forward the same state to this controller. Keep actions
that update text, operate hardware or do something else. In particular,
the observed mute switch retains its hardware mute action.
Media observation now ignores repeated publications of the same state. Volume and metadata updates preserve the current music/announcement action. The
initial state and real transitions are still delivered. API presence also
filters diagnostic clients and tolerates brief reconnects.
The controller and its observers activate their loops for pending work, then
yield when the event batch drains.
Set the presentation priorities
Optional presentation.priorities lets you decide which visible state wins.
Those overrides apply to presentation, LED and display decisions. Existing call
control and music-ducking priorities retain their own rules.
on_state_change provides the previous and current presentation names for
custom displays. Connectivity, microphone mute and speaker mute also have
named presentation triggers.
The simple presentation profile selects indications from the observed facts.
Maintained FULL
profiles continue to supply their existing coordination actions through the
same reducer. The audio components own playback and the SIP component owns the
call.
Presentation priorities and triggers
Your LED, your mappings
The optional none LED preset starts with an empty mapping for completely
custom light behavior. Existing presets keep their defaults.
Define the states you want and specify color, brightness and effect explicitly.
An unmapped state leaves the previous light state in place, so include an idle
mapping when the light should turn off. Effects must already exist on the
configured light.
Maintained devices need less assembly
The refreshed Intercom device packages select complete application bindings
from the board's existing firmware_features list. Voice, media, timer,
ringtone and presentation bindings now share their maintained implementation
with those packages.
For a maintained board, start from its updated YAML and edit that feature list.
The package assembles the application callbacks and controller bindings. Legacy runtime package paths remain compatibility entrypoints with their
documented prerequisites. Choose one complete device composition or its
individual adapters.
The controller's features setting selects coordination rules. The board's
firmware_features selects and compiles applications together with their bindings.
VoIP-only profiles use VoIP Stack callbacks directly, independent of Runtime
Controller.
Device packages and feature selection
Understand why a state won
Optional debug state dumps now name the activity that selected each policy.
When a device shows a call, a timer or an unavailable assistant, you can see
which active input produced that decision. The extra winner information is
included only when runtime debugging is enabled.
The guide now progresses from a music/call example to simulated button events,
real observers and finally custom policies and outputs. Maintained firmware starts from the board profile and feature list.
Progressive configuration guide
Changes since stable 2026.10.1
- Add native Voice Assistant, wake-word, timer and API observations while
preserving the sources' existing automation actions. - Add an observer-driven presentation profile, natural
on_<state>triggers,
previous/current state notifications and separate presentation priorities. - Prevent unchanged media-state publications from repeating controller actions.
- Share application bindings with the reorganized Intercom device packages and
preserve the documented legacy entrypoints. - Add the empty
noneLED preset for explicit custom state mappings. - Show policy-winning activities in optional debug dumps and expand the guide
with progressively more advanced examples. - Align component support and automation bindings with ESPHome 2026.10.0.
- Size the event-rule table after profile expansion instead of reserving all
64 entries for every configuration. On ESP32-S3, a 17-rule layout saves
about 12.5 KiB of payload and object storage; the maintained FULL profile
with 62 rules saves 536 bytes. Allocator overhead is excluded. Savings
depend on the profile, and a configuration using all 64 rules keeps the complete
table. Rule storage is allocated once during setup and reused during event
dispatch. Other tables and runtime queues are unchanged.
Breaking changes and migration from 2026.10.1
- ESPHome 2026.10.0 or newer is required. Rebuild with the coordinated firmware packages.
- When enabling native observers, remove callbacks that only forward those same source events to this controller. Duplicate forwarding is rejected; keep hardware actions, text updates and unrelated user automations.
- Start rewritten maintained FULL compositions from their current board YAML. Custom activity graphs and existing
outputs.ledbindings remain supported. VoIP-only device packages continue to use direct VoIP callbacks.
Compatibility and updating
ESPHome 2026.10.0 or newer is the minimum supported builder. Thank you to
the ESPHome team for the audio improvements, reviews and accepted contributions!
<3
The native observers work with the official ESPHome media player, Voice
Assistant, Micro Wake Word and API components. Each source retains ownership of its audio and hardware; Runtime Controller
observes its state and requests the configured ESPHome actions.
Use Runtime Controller with the matching Intercom release packages. The
package reorganization changes where application bindings come from, so the
recommended migration is to start from the updated YAML for your exact board
and carry over its identity, secrets, network settings and customizations.
When adopting an observer, remove duplicate state forwarding to that same
controller. Keep unrelated user automations and hardware actions. For custom
long-running scripts, use normal ESPHome stop/cancel actions when their
presentation is superseded.
Observation scope
A media player's announcement state describes its reported lifecycle. Acoustic
arrival requires a separate audio measurement. Observers report public source
phases and future wake-word events; past detections and unpublished assistant
phases remain outside their observation surface.
Rebuild and upload the firmware to install these changes. HA/HACS up...
2026.10.1: automatic phone binding in shared packages
ESPHome Runtime Controller 2026.10.1
Changes since stable 2026.10.0.
🧩 Your phone no longer needs to be named phone
The shared runtime packages now resolve the VoIP component automatically instead
of requiring its declaration to use id: phone.
This removes unnecessary coupling between the packages and the name chosen in a
firmware YAML. Explicit IDs remain available for custom configurations, and
lambdas that address a component by name still need that declared ID.
The change covers the full controller's VoIP observer and the shared ringtone
package. It builds on the component's existing automatic binding.
📦 Updating
Refresh the Runtime Controller component and packages from main, then rebuild
your firmware. The coordinated reference profiles use Runtime Controller
2026.10.1, ESP VoIP Stack 2026.10.1, and Audio Stack 2026.10.2.
Requires ESPHome 2026.9.0 or newer.
2026.10.0: more reliable voice controls and simpler YAML packages
Changes since stable 2026.9.2.
Voice responses, stop commands and timers
- Paused music no longer leaves the assistant stuck in "responding". If you
pause music, speak to the assistant and wait for its reply, the device returns
to idle when the reply finishes. The music stays paused. - Stopping the assistant cancels pending restarts. An older request to restart
listening can no longer take effect after a newer stop command. The controller
waits for confirmation that Voice Assistant has stopped; if it takes too long,
it reports a timeout instead of treating the stop as complete. - Reconnecting starts from a clean voice state. Losing the connection to the
Voice Assistant client clears the interrupted listening or responding state. - Stopping a timer alarm no longer cuts off another sound. The timer cleanup
checks whether an incoming-call ringtone or assistant response is using the
announcement player before stopping it.
More reliable handling of overlapping events
A call can start while music is playing, or end while the display is being
updated. The controller now completes each state update before handling events
raised by that update. LED, display and other output callbacks read the complete
new state, rather than a mixture of old and new values.
Rapid VoIP state changes are also kept in order. For example, a queued ringing
notification retains its ringing state even if the call has already been
answered by the time that notification is processed.
Less manual wiring in custom YAMLs
New observe bindings let the controller read Wi-Fi connectivity, media-player
state and microphone/speaker mute switches directly. You can remove the YAML
callbacks that only forward those same state changes to the controller. The
bindings also read the current state at startup.
Voice, media, timers, ringtone, display and LED configuration are now split into
separate packages. A custom device can include the parts it needs. The no-LED
preset uses these shared packages instead of maintaining a second copy of the
full configuration.
The new features setting selects which built-in voice, media and timer rules
to include. Unused VoIP, LED and output-script connections now exclude their stored state
as well as their code. LED-free builds omit the LED mapping table. Wi-Fi, media
and each mute observer are also compiled only when selected.
Updating an existing device
Use ESPHome 2026.9.0 or newer. Update the firmware packages from the Intercom
repository together with Runtime Controller. The Home Assistant integration does
not need the same version number as the ESP firmware.
The easiest option is to start from one of our updated
maintained YAML profiles
and reapply your board settings and customizations.
Alternatively, update your existing YAML:
- Remove
observe.voice_assistantandobserve.micro_wake_wordif present.
These settings previously accepted configuration but did nothing; they now
cause a validation error. Keep the shared Voice Assistant and wake-word
callback packages, which provide the actual connection to the controller. - Where you enable native Wi-Fi, media or mute observation, remove callbacks
that send duplicate state updates. Keep your hardware mute actions and other
user automations. - Follow the guides below to select individual packages or adapt custom
controller callbacks.
Rebuild and upload the firmware to apply these changes.
Runtime migration guide
| Intercom package guide
Earlier error detection and additional tests
Configuration validation now rejects more invalid combinations, such as two
mutually exclusive states both being active at startup. If memory allocation
for controller state fails, setup stops instead of continuing with incomplete
configuration.
New automated tests exercise overlapping events, rapid call-state changes,
full event queues, allocation failures and assistant replies with music idle,
playing or paused.
Thanks to everyone who donated to support the project.
ESPHome Runtime Controller 2026.9.2
ESPHome Runtime Controller 2026.9.2
This release identifies the Runtime Controller used by ESPHome Intercom 2026.9.2.
The runtime implementation is unchanged from 2026.9.1. Existing activities, priorities and policies remain compatible; no configuration migration is needed.
ESPHome Runtime Controller 2026.9.1
This release marks the Runtime Controller used by the stable ESPHome Intercom 2026.9.1 platform.
The component source is unchanged from v2026.9.0. Existing activity rules, priorities, runtime policies and YAML configuration remain compatible; no migration is required.
The version number is aligned with the coordinated platform release so users can identify the matching component set.
ESPHome Runtime Controller 2026.9.1
ESPHome Runtime Controller 2026.9.1
This release marks the Runtime Controller used by the stable ESPHome Intercom 2026.9.1 platform.
The component source is unchanged from v2026.9.0. Existing activity rules, priorities, runtime policies and YAML configuration remain compatible; no migration is required.
The version number is aligned with the coordinated platform release so users can identify the matching component set.
ESPHome Runtime Controller 2026.9.0
Changelog
2026.9.0, 2026-08-29
Existing runtime-controller YAML remains compatible. No migration is required.
Added
storage_in_psramcan place persistent reducer state in PSRAM on large voice
and display profiles. The option is disabled by default and requires the
ESPHomepsramcomponent when enabled.
Changed
- Activity matching and policy resolution share one implementation, removing
duplicate state checks from individual runtime features. - The component schema and tests are aligned with current ESPHome validation
and code-generation contracts.