Skip to content

2026.11.0: ESPHome 2026.10 and native source observers

Latest

Choose a tag to compare

@n-IA-hane n-IA-hane released this 27 Oct 21:36
· 1 commit to main since this release

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 updates install the integration separately.

Migration guide
| Firmware migration checklist

Thanks to @Gafielt for proposing and contributing the empty none LED preset in #1, together with a custom listening-effect example. The change was adapted into this release with co-author credit, following the original PR's closure. Thanks also to everyone sharing configurations and feedback.

All changes since 2026.10.1