Home Assistant Core Config Update Mechanism and Event System Explained

Home Assistant propagates core configuration changes via the Config.async_update() method in homeassistant/core_config.py, which fires the internal core_config_updated event through the EventBus to notify all registered listeners across integrations.

Home Assistant's architecture relies on a centralized configuration management system to handle critical settings like latitude, longitude, time zone, and unit system. The core config update mechanism ensures that when these values change, every component that depends on them receives immediate notification through the internal event system. This implementation resides primarily in the home-assistant/core repository, specifically within the homeassistant/core_config.py and homeassistant/core.py modules.

How Home Assistant Stores Core Configuration

The foundation of the core config update mechanism is the Config class defined in homeassistant/core_config.py. This class acts as the single source of truth for system-wide settings including language, currency, country, time zone, elevation, and the unit system (metric or imperial).

When Home Assistant starts, it instantiates this Config object and loads values from persistent storage. The class provides the async_update() method (lines 69-74) as the exclusive entry point for modifying these values at runtime, ensuring that all changes are validated, persisted, and broadcast consistently.

The Config Update Flow

When an integration or the frontend requests a configuration change, the system executes a precise sequence to ensure data integrity and event propagation.

Step 1: Persist and Fire the Event

The Config.async_update() method handles the entire transaction:

# homeassistant/core_config.py (lines 69-74)

async def async_update(self, **kwargs: Any) -> None:
    """Update the configuration from a dictionary."""
    await self._async_update(source=ConfigSource.STORAGE, **kwargs)
    await self._async_store()
    # Fire internal event to notify all listeners

    self.hass.bus.async_fire_internal(EVENT_CORE_CONFIG_UPDATE, kwargs)

The kwargs dictionary contains only the changed keys, such as {"latitude": 51.5, "unit_system": "metric"}. The call to self.hass.bus.async_fire_internal() creates an internal event that bypasses the public event service, keeping the notification lightweight and internal-only.

Step 2: EventBus Dispatch

The EventBus class in homeassistant/core.py (line 1422) implements the async_fire_internal method:

# homeassistant/core.py

class EventBus:
    def async_fire_internal(self, event_type: str, event_data: Any = None) -> None:
        """Fire an internal event (no public service exposure)."""
        self._async_process_event(
            Event(event_type, data=event_data, event_id=self._next_event_id()),
            internal=True,
        )

This method constructs an Event object using the constant EVENT_CORE_CONFIG_UPDATE (defined in homeassistant/const.py, line 263) and delivers it to all registered internal listeners without exposing it to external automation triggers.

How Components Listen for Config Changes

Integrations that depend on core configuration—such as sun, time_date, zone, and utility_meter—register listeners during their setup phase to react to EVENT_CORE_CONFIG_UPDATE.

Registration Pattern

Components typically register in their async_setup_entry or initialization code:

# homeassistant/components/sun/entity.py

async def async_setup_entry(hass, entry):
    hass.bus.async_listen(EVENT_CORE_CONFIG_UPDATE, self.update_location)

# homeassistant/components/time_date/sensor.py

self.hass.bus.async_listen(EVENT_CORE_CONFIG_UPDATE, async_update_config)

Callback Execution

When the event fires, the callback receives the event data dictionary containing the changed configuration keys. The component can then recompute values—such as recalculating sunrise times when latitude changes or reformatting time displays when the time zone updates.

Practical Implementation Examples

Manually Triggering a Core Config Change

Custom components or automations can programmatically update core settings:

# Update location and unit system

await hass.config.async_update(
    latitude=52.5200,
    longitude=13.4050,
    unit_system="metric",
)

# All listeners to EVENT_CORE_CONFIG_UPDATE receive notification automatically

Building a Custom Listener

To react to configuration changes in a custom integration:

import homeassistant.const as ha_const
from homeassistant.core import HomeAssistant, callback

class MyIntegration:
    def __init__(self, hass: HomeAssistant):
        self.hass = hass
        self.hass.bus.async_listen(
            ha_const.EVENT_CORE_CONFIG_UPDATE, 
            self._handle_core_change
        )

    @callback
    def _handle_core_change(self, event):
        """Re-evaluate configuration-dependent logic."""
        new_tz = event.data.get("time_zone")
        if new_tz:
            self._apply_time_zone(new_tz)

Summary

• Core configuration is managed by the Config class in homeassistant/core_config.py, which handles settings like location, time zone, and unit system.
• Updates propagate via Config.async_update(), which persists changes to storage and immediately fires the EVENT_CORE_CONFIG_UPDATE internal event.
• The EventBus in homeassistant/core.py dispatches events through async_fire_internal, ensuring internal-only delivery without public service overhead.
• Integrations register listeners using hass.bus.async_listen(EVENT_CORE_CONFIG_UPDATE, callback) to recompute state when core settings change, as seen in the sun, time_date, and zone components.

Frequently Asked Questions

How do I listen for core configuration changes in a custom component?

Register a listener using hass.bus.async_listen with the EVENT_CORE_CONFIG_UPDATE constant from homeassistant.const. Your callback function will receive an event object containing the changed configuration keys in event.data, allowing you to update your component's internal state accordingly.

What is the difference between async_fire and async_fire_internal in the Home Assistant EventBus?

async_fire_internal creates and dispatches events that bypass the public event service and external automation triggers, making it suitable for internal system notifications like configuration updates. The standard async_fire method exposes events to the public API, allowing automations and external systems to react to them.

Which Home Assistant components typically react to EVENT_CORE_CONFIG_UPDATE?

Components that depend on location, time, or measurement units register for this event, including the sun integration (recalculates sunrise/sunset), time_date sensors (reformats display), zone (updates geofencing), and utility_meter (adjusts unit conversions). Any integration accessing hass.config values should consider listening for these updates.

Can I manually trigger a core configuration update from an automation or script?

Yes, you can call hass.config.async_update() from a custom component or Python script, passing the configuration keys you want to change such as latitude, longitude, time_zone, or unit_system. This will persist the changes to storage and automatically notify all registered listeners via the internal event system.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}