Skip to content

Standardized event entity support (Matter, ZHA) #30

Open
Open
Standardized event entity support (Matter, ZHA)#30
Assignees
arturpragacz

Description

@TheJulianJES
TheJulianJES
opened on Oct 7, 2026

This issue tracks blockers for implementing support for the new standardized event entity types (for buttons/remotes) (for ZHA + Matter).

Main blocker (since 2026-10-15): the approved proposal home-assistant/architecture#1502 has no implementation yet. No Core PR updates ButtonEventType, and the triggers, Matter, ZHA and docs all wait on that.

Note: ZHA progress is being tracked in this epic:

Tasks

More information/context – pasted from zigpy bot:

The press_end dispute that blocked this from 2026-08-03 is settled: arturpragacz's proposal home-assistant/architecture#1502, amending home-assistant/architecture#1377, was approved by the core meeting on 2026-10-15. The next step is the Core change that brings ButtonEventType in line with it. As of 2026-10-20 no PR for that exists.

What home-assistant/architecture#1502 decides (click to expand)
  • Two layers of event types. Physical: press_start (the button went down, declared only if reported for every press) and press_end (released after a press that wasn't long). Gesture: long_press_start (hold threshold reached, exactly once per hold), long_press_end, single_press (the device concluded exactly one short press happened) and multi_press (two or more presses, data press_count).
  • press_end is the physical release only. Resolved singles go to the new single_press. multi_press_end + multi_press_count is renamed to multi_press + press_count, now only for counts ≥ 2.
  • multi_press_ongoing is removed from the standard (Matter may keep it as an extra type). A count of 0 (aborted sequence) is dropped.
  • multi_press may only be declared together with single_press. A device that reports a double but never a resolved single, such as Lutron Caséta MultiTap, keeps the double as an extra type.
  • A single-event press maps by what the event is: press_start when sent at the down edge, press_end when sent on release, single_press for a completed press. A single-event hold maps by timing: long_press_start at the threshold, long_press_end after release.
  • Integrations map one native event to one standard event: no suppressing, delaying or synthesizing, and no timers. The only state allowed is one bit, to classify a release after a hold start and to send long_press_start only once when a device repeats it.
  • Triggers carry fallbacks and an event_types requirement. button.pressed fires on single_press, else press_end, else press_start. Also button.multi_pressed (press_count, default 2), button.held (long_press_start, else long_press_end), button.hold_ended and the condition button.is_held. button.being_held and button.pressed_down are deferred.
  • The frontend target selector needs "contains any of" / "contains all of" filtering on event_types.
  • Rotary input stays out of scope.

Still under discussion after approval: nielsrowinbik (2026-10-15, same day) prefers one button.pressed trigger with a count field over a separate multi_pressed, objects to the held / being_held naming, and wants being_held not deferred. abmantis' objections (2026-10-12) got a detailed reply from arturpragacz, but no follow-up. That reply also offered an optional variant, where the base entity derives single_press itself, which isn't part of the approved text. These affect the trigger surface, not the event mapping integrations implement.

What is waiting on this

Core (next step)

Matter

Matter mapping under home-assistant/architecture#1502 and changes needed in home-assistant/core#177101 (click to expand)

Switch cluster, Matter 1.6.0 §1.13.7–1.13.9:

  • Multi-press switches without the ActionSwitch feature (MSM & !AS) emit InitialPress at the start of every press and ShortRelease at the end of every press (if MSR). MultiPressOngoing(n) is emitted together with the n-th InitialPress, and MultiPressComplete(n) once the sequence ends, including n = 1 for a single press.
  • ActionSwitch devices (AS) never emit ShortRelease or MultiPressOngoing: a press is only InitialPress followed by MultiPressComplete(n).
  • LongPress is generated exactly once per hold (§1.13.7.1), so the one-bit repeat state isn't needed for Matter.

home-assistant/architecture#1502 mapping: InitialPress → press_start (not on ActionSwitch, which keeps initial_press as an extra type), ShortRelease → press_end, LongPress → long_press_start, LongRelease → long_press_end, MultiPressComplete(1) → single_press, MultiPressComplete(n ≥ 2) → multi_press with press_count, count 0 dropped, MultiPressOngoing as an extra type.

Changes needed in home-assistant/core#177101 (head 0d0c392, last pushed 2026-07-29): split MultiPressComplete into single_press / multi_press with press_count, drop count 0, demote multi_press_ongoing to an extra type, stop declaring press_start on ActionSwitch devices, and map InitialPress to press_start instead of press_end on switches without release support. Also update the PR body and tests.

ZHA

Other integrations

Done or no longer blocking (click to expand)

Users are stuck in between

Device automation triggers, which ZHA and Z2M remotes rely on today, are deprecated and intentionally hidden in the new automation editor (comment). Starting from the device ("By target", or "Create automation" on the device page) only shows entity triggers such as battery. The remote's button triggers are only under "By type" → "Generic" → "Device", and nothing in the docs explains this. Their replacement for ZHA and Matter, button event entities, is what's blocked here. Users regularly report this as "my remote has no triggers": home-assistant/frontend#53688, home-assistant/core#177053, home-assistant/core#175890. home-assistant/home-assistant.io#47222 (documenting raw zha_events as a workaround) was closed in favor of event entities.

If the ZHA/Matter follow-ups will take a few more releases, we should document how to find device automation triggers in the meantime: a short section on the device automation and ZHA (possibly Matter) docs pages, or a frontend hint. These are the old device automation triggers, not the new purpose-specific triggers. The Matter docs' "Automate on a button press" section also links to an anchor on the event integration page (/integrations/event/#automating-on-a-button-press) that no longer exists.

Activity

  1. TheJulianJES
    assigned
    arturpragacz
    on Oct 7, 2026

  2. arturpragacz commented on Oct 9, 2026

    @arturpragacz
    arturpragacz
    on Oct 9, 2026

    home-assistant/architecture#1502

  3. TheJulianJES commented on Oct 20, 2026

    @TheJulianJES
    TheJulianJES
    on Oct 20, 2026
    Author

    Update: The revised architecture proposal (home-assistant/architecture#1502) was approved, so I've updated the tasks at the top.

    The next step would be for Core's ButtonEventType to be updated and existing integrations to be migrated to the revised version (event entity support for isy994 was recently merged and uses the older standardized event types, so there'll be a breaking change there).

  4. TheJulianJES commented on Oct 20, 2026

    @TheJulianJES
    TheJulianJES
    on Oct 20, 2026
    Author

    Another thing specifically for Zigbee: Lots of devices can be reconfigured in which events they emit. So depending on their configuration (multi-press supported or instantly send one event on down press, and depending on rocker vs push down switch), the emitted events are different.

    We'll need to think of a good solution here. The simple/initial approach might be to have the event entity support all of the possible combinations, but a proper solution might be to replace the event entity when we have a possibility to detect that the device has changed modes.

  5. TheJulianJES commented on Oct 20, 2026

    @TheJulianJES
    TheJulianJES
    on Oct 20, 2026
    Author

    Tracking ZHA progress for event entities here:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions