Event components (#3722)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>

components/event/index.rst

@@ -0,0 +1,147 @@
+Event Component
+===============
+
+.. seo::
+    :description: Instructions for setting up event components in ESPHome.
+    :image: folder-open.svg
+
+ESPHome supports the creation of event entities in Home Assistant.
+These entities allow for the triggering of custom events within the Home Assistant ecosystem,
+enabling complex automations and integrations. An event entity is represented as a stateless
+entity associated with a device that has a pre-defined set of event types which can be
+triggered in Home Assistant via automations.
+
+.. note::
+
+    Events in ESPHome are designed to trigger an action in Home Assistant, and have a unidirectional flow from ESPHome to Home Assistant.
+    Home Assistant event entities are different from events on event bus. If you just want to trigger an event on the
+    Home Assistant event bus, you should use a :ref:`Home Assistant event <api-homeassistant_event_action>` instead.
+
+
+.. note::
+
+    Home Assistant Core 2024.5 or higher is required for ESPHome event entities to work.
+
+.. _config-event:
+
+Base Event Configuration
+------------------------
+
+Each event in ESPHome needs to be configured with a list of event types it can trigger and an optional device class.
+
+.. code-block:: yaml
+
+    # Example event configuration
+    event:
+      - platform: ...
+        name: Motion Detected Event
+        id: my_event
+
+        # Optional variables:
+        icon: "mdi:motion-sensor"
+        device_class: "motion"
+        on_event:
+          then:
+            - logger.log: "Event triggered"
+
+Configuration variables:
+
+One of ``id`` or ``name`` is required.
+
+- **id** (**Required**, :ref:`config-id`): Manually specify the ID used for code generation, allowing for further customization or interaction with this event within ESPHome scripts or lambda functions.
+- **name** (**Required**, string): The name for the event.
+
+  .. note::
+
+      If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
+      you want the event to use that name, you can set ``name: None``.
+
+- **icon** (*Optional*, icon): Manually set the icon to use for the event in the frontend.
+- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
+  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+  a ``name`` will implicitly set this to true.
+- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
+  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
+- **entity_category** (*Optional*, string): The category of the entity.
+  See https://developers.home-assistant.io/docs/core/entity/#generic-properties
+  for a list of available options. Set to ``""`` to remove the default entity category.
+- **device_class** (*Optional*, string): The device class for the event. The following device classes are supported by event entities:
+
+  - None: Generic event. This is the default and doesn't need to be set.
+  - ``button``: For remote control buttons.
+  - ``doorbell``: Specifically for buttons that are used as a doorbell.
+  - ``motion``: For motion events detected by a motion sensor.
+
+  See https://www.home-assistant.io/integrations/event/#device-class
+  for a list of available options.
+
+Automations:
+
+- **on_event** (*Optional*, :ref:`Automation <automation>`): An automation to perform when an event is triggered.
+
+MQTT options:
+
+- All other options from :ref:`MQTT Component <config-mqtt-component>`.
+
+Event Automation
+----------------
+
+.. _event-on_event:
+
+``on_event``
+************
+
+This automation will be triggered when an event of the specified types is triggered.
+
+.. code-block:: yaml
+
+    event:
+      - platform: template
+        # ...
+        on_event:
+          then:
+            - logger.log: "Event Triggered"
+
+Configuration variables: see :ref:`Automation <automation>`.
+
+``event.trigger`` Action
+************************
+
+This action allows for the triggering of an event from within an automation.
+
+.. code-block:: yaml
+
+    - event.trigger:
+        id: my_event
+        event_type: "custom_event"
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the event.
+- **event_type** (**Required**, string): The type of event to trigger.
+
+.. _event-lambda_calls:
+
+lambda Calls
+************
+
+From :ref:`lambdas <config-lambda>`, you can trigger an event.
+
+- ``trigger(std::string event_type)``: Trigger an event with the specified type.
+
+  .. code-block:: cpp
+
+      // Within lambda, trigger the event.
+      id(my_event).trigger("custom_event");
+
+See Also
+--------
+
+- :apiref:`event/event.h`
+- :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *

components/event/template.rst

@@ -0,0 +1,31 @@
+Template Event
+==============
+
+.. seo::
+    :description: Instructions for setting up template events that can trigger arbitrary automations when an event occurs.
+    :image: description.svg
+
+The ``template`` event platform enables you to define events that trigger specific automations or actions within Home Assistant. These custom events can be utilized to orchestrate complex behaviors across your smart home ecosystem based on conditions or sequences defined in your ESPHome configuration.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    event:
+      - platform: template
+        name: "Template Event"
+        event_types:
+          - "custom_event_1"
+          - "custom_event_2"
+
+Configuration variables:
+------------------------
+
+- **event_types** (**Required**, list): A list of custom event identifiers that this template event is capable of triggering. These identifiers can be used in Home Assistant automations or ESPHome scripts to perform actions when the event occurs.
+- All other options from :ref:`Event <config-event>`.
+
+See Also
+--------
+
+- :doc:`/guides/automations`
+- :doc:`/components/event/index`
+- :ghedit:`Edit`

components/index.rst

@@ -17,6 +17,7 @@ Components
     sensor/index
     switch/index
     button/index
+    event/index
     display/index
     text_sensor/index
     stepper/index

index.rst

@@ -719,6 +719,14 @@ Button Components
     UART Button, components/button/uart, uart.svg
     Wake-on-LAN, components/button/wake_on_lan, power_settings.svg, dark-invert
 
+Event Components
+-----------------
+
+.. imgtable::
+
+    Event Core, components/event/index, folder-open.svg, dark-invert
+    Template Event, components/event/template, description.svg, dark-invert
+
 Fan Components
 --------------
 

schema_doc.py

@@ -85,6 +85,7 @@ PLATFORMS_TITLES = {
     "Microphone": "microphone",
     "Speaker": "speaker",
     "Alarm Control Panel": "alarm_control_panel",
+    "Event": "event",
 }
 
 CUSTOM_DOCS = {