Event entity support

[nohat]

What does this implement/fix?

Event entities were introduced in Home Assistant 2023.8:

Events are signals that are emitted when something happens, for example, when someone presses a physical button like a doorbell or when a button on a remote control is pressed.

This PR introduces support in ESPHome for Home Assistant "Event Entities" as a new component. In addition to an implementation of event entities in the template platform for integration into config YAMLs, it adds support for exposing event entities and events in the API, via MQTT, and in the web server.

Besides this PR, there are also necessary changes to aioesphomeapi as well as the esphome home-assistant/core:

• Support for Event entity messages aioesphomeapi#853
• Add Event support to ESPHome components home-assistant/core#116061

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Other

Related issue or feature (if applicable):

• This implements Adding support for Home Assistant event entity feature-requests#2433

Pull request in esphome-docs with documentation:

• Event components esphome-docs#3722

Test Environment

• ESP32
• ESP32 IDF
• ESP8266
• RP2040
• BK72xx
• RTL87xx

Example entry for config.yaml:

# Example config.yaml
button:
  - platform: template
    name: Emit example_event_type1
    on_press: 
      then:
        - event.fire:
            id: example_event
            event_type: example_event_type1
  - platform: template
    name: Emit example_event_type2
    on_press: 
      then:
        - event.fire:
            id: example_event
            event_type: example_event_type2
event:
  - platform: template
    id: example_event
    name: Example Event
    event_types:
      - example_event_type1
      - example_event_type2

Checklist:

• The code change is tested and works locally.
• Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in esphome-docs.

Config YAML

• platform: Specifies the platform type, in this PR, only template events are supported. Future improvements may provide direct support of e.g. GPIO or Tuya MCU events without an underlying binary_sensor component to trigger the events.
• name: A friendly name for the event entity, appearing in Home Assistant.
• id: A unique identifier for this event entity within ESPHome.
• event_types (Mandatory): A list of the event types this entity can emit. Each type is a distinct string identifier, facilitating specific event differentiation in Home Assistant.
• on_event: Defines automation actions to execute when the event is fired. Conditions can be used to perform actions based on the event_type.

event.fire Action

This action is used in automations to fire an event.

Example use in a button:

button:
  - platform: template
    name: "Emit example_event_type1"
    on_press:
      then:
        - event.fire:
            id: example_event
            event_type: example_event_type1

event:
  - platform: template
    id: example_event
    name: Example Event
    event_types:
      - example_event_type1
      - example_event_type2

Limitations

Although the Home Assistant documentations allows it, this implementation does not support sending any attributes with events, only the mandatory "event_type" string.

Summary of changes by file

esphome/components/event/__init__.py:

• Specification of YAML config for event components
• Validate device class
• Validate presence of event_types

esphome/components/event/event.{h,cpp}:

• Implementation of the base event component.
• Public interface provides fire_event(), has_event_type(), set_event_types(), get_event_types(), and add_on_event_fired_callback() methods.

esphome/components/event/automation.h:

• event.fire action
• on_event trigger

esphome/components/template/event/__init__.py,
esphome/components/template/event/template_event.h:

• Implementation in the template platform for event components in YAMLs.

esphome/components/api/api.proto:

• Specification of the protobuf message format for announcing event entities and firing events

esphome/components/api/api_connection.{h,cpp},
esphome/components/api/api_pb2_service.{h,cpp},
esphome/components/api/subscribe_state.h,
esphome/components/api/api_server.cpp,
esphome/components/api/list_entities.{h,cpp}:

• Implement packing, unpacking, logging, and sending protobuf API messages for events:
  • Announcing event entities
  • When events are fired

esphome/components/mqtt/__init__.py,
esphome/components/mqtt/mqtt_event.h,
esphome/components/mqtt/mqtt_event.{h,cpp}:

• Support for event components over MQTT:
  • Pursuant to the Home Assistant documentation for MQTT Event entities https://www.home-assistant.io/integrations/event.mqtt/.
  • Home Assistant discovery messages
  • Messages when events are fired

esphome/components/mqtt/mqtt_const.h

• Constants for "event_type" and "event_types".
• Alphabetized contents, which were partially-sorted.

esphome/components/web_server/web_server.cpp,
esphome/components/web_server/list_entities.{h,cpp}:

• Emit event component configuration info on server startup.
• Emit JSON event stream "state" events when events fire.

esphome/core/application.h:

• Global support for event components:
  • Global storage of component objects
  • Callback handlers
  • Introspection

esphome/const.py:

• Event-specific constants for configuration YAML files:
  • event_type, event_types, on_event
  • Device classes for button and doorbell

esphome/core/controller.{h,cpp}:

• Ensure that web server is set up to handle event entities.

esphome/core/component_iterator.{h,cpp}

• Ensure component iterators (used in API, MQTT, and web server) can find event entities.

[probot-esphome]

Hey there @OttoWinter, mind taking a look at this pull request as it has been labeled with an integration (api) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[probot-esphome]

Hey there @nohat,
Thanks for submitting this pull request! Can you add yourself as a codeowner for this integration? This way we can notify you if a bug report for this integration is reported.
In __init__.py of the integration, please add:

CODEOWNERS = ["@nohat"]

And run script/build_codeowners.py

_{^{(message by NeedsCodeownersLabel)}}

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 53.45%. Comparing base (4d8b5ed) to head (76494fe).
Report is 463 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #6451      +/-   ##
==========================================
- Coverage   53.70%   53.45%   -0.26%     
==========================================
  Files          50       50              
  Lines        9408     9543     +135     
  Branches     1654     1685      +31     
==========================================
+ Hits         5053     5101      +48     
- Misses       4056     4131      +75     
- Partials      299      311      +12     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[probot-esphome]

Hey there @jesserockz, mind taking a look at this pull request as it has been labeled with an integration (i2s_audio) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[probot-esphome]

Hey there @esphome/core, mind taking a look at this pull request as it has been labeled with an integration (network) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[probot-esphome]

Hey there @Azimath, mind taking a look at this pull request as it has been labeled with an integration (tmp117) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[jesserockz]

This has to be the most detailed PR description I have ever seen. Very nice.

I have rebased your changes on top of the latest time additions and will try to do an actual review soon.

[jesserockz]

For future reference, if you want to alphabetise a file, please do it in its own PR. =)
#6619

[Robbe-B]

@jesserockz,
Feature request esphome/feature-requests#2433 can probably be closed now.
Thanks for the efforts !