148 lines
4.6 KiB
ReStructuredText
148 lines
4.6 KiB
ReStructuredText
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:
|
|
|
|
*
|