Skip to content

Releases

2026.12.0-dev | ESPHome Runtime Controller

Choose a tag to compare

@n-IA-hane n-IA-hane released this 19 Nov 20:16
  • 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.

Changelog

2026.11.1-dev: compact queues and payload reuse checks

Choose a tag to compare

@n-IA-hane n-IA-hane released this 04 Nov 19:59

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

Choose a tag to compare

@n-IA-hane n-IA-hane released this 27 Oct 21:36

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_led

The 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.

Start with an existing player

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.

Source observation guide

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.

Custom LED mappings

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 none LED 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.led bindings remain supported. VoIP-only device packages continue to use direct VoIP callbacks.

Migration guide

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...

Read more

2026.10.1: automatic phone binding in shared packages

Choose a tag to compare

@n-IA-hane n-IA-hane released this 04 Oct 10:11

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.

Configuration guide

2026.10.0: more reliable voice controls and simpler YAML packages

Choose a tag to compare

@n-IA-hane n-IA-hane released this 26 Sep 23:50

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_assistant and observe.micro_wake_word if 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

Choose a tag to compare

@n-IA-hane n-IA-hane released this 12 Sep 18:49

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.

Platform release notes and update instructions

ESPHome Runtime Controller 2026.9.1

Choose a tag to compare

@n-IA-hane n-IA-hane released this 08 Sep 13:02

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.

Platform release notes and update instructions

ESPHome Runtime Controller 2026.9.0

Choose a tag to compare

@n-IA-hane n-IA-hane released this 29 Aug 02:58

Changelog

2026.9.0, 2026-08-29

Existing runtime-controller YAML remains compatible. No migration is required.

Added

  • storage_in_psram can place persistent reducer state in PSRAM on large voice
    and display profiles. The option is disabled by default and requires the
    ESPHome psram component 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.