Event entity

Events are signals that are emitted when something happens, for example, when a user presses a physical button like a doorbell or when a button on a remote control is pressed. The event entity captures these events in the physical world and makes them available in Home Assistant as an entity.

An event entity is derived from the homeassistant.components.event.EventEntity.

States

The event entity is stateless, meaning you don't have to maintain a state. Instead, you can trigger an event when something in the physical world happens. Home Assistant will keep track of the last event that was emitted and will show that as the current state of the entity.

The main state of the entity is the timestamp of when the last event was emitted, additionally the type of the event and optionally extra state data that was provided with the event are also kept track of.

Properties

tip

Properties should always only return information from memory and not do I/O (like network requests). Implement update() or async_update() to fetch data.

Name	Type	Default	Description
event_types	list[str]	Required	A list of possible event types this entity can fire.

Other properties that are common to all entities such as device_class, icon, name etc are also applicable.

Firing events

The event entity is a little different compared to other entities. Home Assistant manages the state, but the integration is responsible for firing the events. This is done by calling the _trigger_event method on the event entity.

This method takes the event type as the first argument and optionally extra state data as the second argument.

class MyEvent(EventEntity):

    _attr_device_class = EventDeviceClass.BUTTON
    _attr_event_types = ["single_press", "double_press"]

    @callback
    def _async_handle_event(self, event: str) -> None:
        """Handle the demo button event."""
        self._trigger_event(event, {"extra_data": 123})
        self.async_write_ha_state()

    async def async_added_to_hass(self) -> None:
        """Register callbacks with your device API/library."""
        my_device_api.listen(self._async_handle_event)

Only event types that are defined in the event_types property can be fired. If an event type is fired that is not defined in the event_types property, a ValueError will be raised.

tip

Be sure to deregister any callbacks when the entity is removed from Home Assistant.

Available device classes

Optionally specifies what type of entity it is.

Constant	Description
EventDeviceClass.BUTTON	A button of a remote control has been pressed.
EventDeviceClass.DOORBELL	Specifically for buttons that are used as a doorbell.
EventDeviceClass.MOTION	For motion events detected by a motion sensor.