Event Helpers

Helper functions for listening to and tracking events in Home Assistant.

The homeassistant.helpers.event module provides utilities for listening to events, tracking state changes, and managing time-based operations.

Key Functions

async_track_state_change_event

Track specific state change events indexed by entity_id.

hass · HomeAssistant · required

Home Assistant instance

entity_ids · str | Iterable[str] · required

Entity IDs to track (automatically lowercased)

action · Callable[[Event[EventStateChangedData]], Any] · required

Callback function to execute when state changes

job_type · HassJobType | None · default: "None"

Job type for the callback

return · CALLBACK_TYPE

Function to call to remove the listener

from homeassistant.helpers.event import async_track_state_change_event

def my_callback(event):
    print(f"State changed: {event.data['entity_id']}")

remove_listener = async_track_state_change_event(
    hass,
    ["light.living_room", "light.bedroom"],
    my_callback
)

async_track_state_report_event

Track EVENT_STATE_REPORTED by entity_ids. This fires when state is updated but not changed.

hass · HomeAssistant · required

Home Assistant instance

entity_ids · str | Iterable[str] · required

Entity IDs to track

action · Callable[[Event[EventStateReportedData]], Any] · required

Callback function to execute

job_type · HassJobType | None · default: "None"

Job type for the callback

async_track_point_in_time

Add a listener that fires once at or after a specific point in time.

hass · HomeAssistant · required

Home Assistant instance

action · HassJob[[datetime], Coroutine] | Callable[[datetime], Coroutine] · required

Callback to execute (passed the time it fires in local time)

point_in_time · datetime · required

Point in time to fire the callback

async_track_template_result

Add a listener that fires when the result of a template changes.

hass · HomeAssistant · required

Home Assistant instance

track_templates · Sequence[TrackTemplate] · required

List of templates to track

action · TrackTemplateResultListener · required

Callback to call with results

strict · bool · default: "False"

When True, raise on undefined variables

log_fn · Callable[[int, str], None] | None · default: "None"

Optional custom logging function for template errors

has_super_template · bool · default: "False"

When True, first template blocks rendering of others if it doesn’t render as True

return · TrackTemplateResultInfo

Object used to unregister the listener and refresh the template

Data Classes

TrackStates

Class for keeping track of states being tracked.

all_states · bool

Whether all states on the system are being tracked

entities · set[str]

Lowercased entities to track

domains · set[str]

Lowercased domains to track

TrackTemplate

Class for keeping track of a template with variables.

template · Template

Template to calculate

variables · TemplateVarsType

Variables to pass to the template

rate_limit · float | None · default: "None"

Rate limit on how often the template is re-rendered

TrackTemplateResult

Class for result of template tracking.

template · Template

The template that has changed

last_result · Any

Output from the template on the last successful run (None if no previous run)

result · Any

Result from the template run (string or TemplateError if template errored)

Device and Entity Registry Tracking

async_track_entity_registry_updated_event

Track specific entity registry updated events indexed by entity_id.

hass · HomeAssistant · required

Home Assistant instance

entity_ids · str | Iterable[str] · required

Entity IDs to track (must be lowercase)

action · Callable[[Event[EventEntityRegistryUpdatedData]], Any] · required

Callback function

job_type · HassJobType | None · default: "None"

Job type for the callback

async_track_device_registry_updated_event

Track specific device registry updated events indexed by device_id.

hass · HomeAssistant · required

Home Assistant instance

device_ids · str | Iterable[str] · required

Device IDs to track

action · Callable[[Event[EventDeviceRegistryUpdatedData]], Any] · required

Callback function

job_type · HassJobType | None · default: "None"

Job type for the callback

Constants

• RANDOM_MICROSECOND_MIN = 50000 - Minimum microseconds for spreading listeners
• RANDOM_MICROSECOND_MAX = 500000 - Maximum microseconds for spreading listeners
• EVENT_STATE_CHANGED - Event type for state changes
• EVENT_STATE_REPORTED - Event type for state reports (update without change)