Skip to main content
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)

Build docs developers (and LLMs) love

Get started for freeTalk to us