Skip to main content

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.

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.

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



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

event_typeslist[str]RequiredA 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"]

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

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

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.


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.

EventDeviceClass.BUTTONA button of a remote control has been pressed.
EventDeviceClass.DOORBELLSpecifically for buttons that are used as a doorbell.
EventDeviceClass.MOTIONFor motion events detected by a motion sensor.