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.

Standard event types

Some device classes define standard event types to ensure consistency across integrations, enabling generic automations that work regardless of the underlying integration.

Doorbell

• DoorbellEventType.RING: represents the standard "doorbell was pressed" event. This event type is mandatory.

Button

• ButtonEventType.PRESS_START: the button was pressed down.
• ButtonEventType.PRESS_END: the button was released after a brief press (the standard "click").
• ButtonEventType.LONG_PRESS_START: the button was held past a threshold.
• ButtonEventType.LONG_PRESS_END: the button was released after a long hold.
• ButtonEventType.MULTI_PRESS_ONGOING: an intermediate press in a multi-press sequence was detected.
• ButtonEventType.MULTI_PRESS_END: a multi-press sequence completed.

MULTI_PRESS_ONGOING and MULTI_PRESS_END include a multi_press_count attribute in event_data with the number of presses.

If a device only emits a single event per interaction, with no separate press and release, map it to the matching _end type (PRESS_END for short presses, LONG_PRESS_END for holds, and so on).

For a button that reports a direction from a single source (for example an up/down paddle), prefer exposing separate entities per direction. A non-standard direction attribute is an accepted alternative when splitting into multiple entities isn't practical.

Other non-standard event types are also allowed.