> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Home Assistant Core

> Learn about Home Assistant Core, an open-source home automation platform built on Python 3.

Home Assistant Core is an open-source home automation platform that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts, it's designed to be the central hub for all your smart home devices.

## What is Home Assistant Core?

Home Assistant Core is the Python-based foundation of Home Assistant. It provides a robust framework for:

* **Observing** the state of entities across your home
* **Controlling** devices through a unified interface
* **Automating** tasks based on state changes and events
* **Integrating** thousands of different devices and services

<Info>
  Home Assistant Core is a **production-ready platform** currently at version **2026.4.0.dev0**. It requires Python **3.14.2 or later**.
</Info>

## Key Features

<Card title="Local Control" icon="house">
  All processing happens on your local hardware. Your data stays in your home, ensuring privacy and reducing cloud dependencies.
</Card>

<Card title="Modular Architecture" icon="puzzle-piece">
  Built on a modular integration system that makes it easy to add support for new devices and services. Each integration runs independently.
</Card>

<Card title="Event-Driven System" icon="bolt">
  Home Assistant uses an event bus architecture where components communicate through events, enabling powerful automation capabilities.
</Card>

<Card title="Extensive Integration Library" icon="plug">
  Supports thousands of integrations for devices from major manufacturers and DIY solutions.
</Card>

## Architecture Overview

Home Assistant Core is built around several fundamental concepts:

### The HomeAssistant Core Object

At the heart of the system is the `HomeAssistant` class (defined in `homeassistant/core.py`), which serves as the central coordinator:

```python theme={null}
class HomeAssistant:
    """Central object for Home Assistant.
    
    The HomeAssistant object coordinates:
    - Event bus for inter-component communication
    - State machine for tracking entity states
    - Service registry for callable actions
    - Configuration management
    - Component lifecycle
    """
```

### Core Components

<Steps>
  <Step title="Event Bus">
    The event bus enables asynchronous communication between components. Events like `state_changed`, `service_registered`, and custom events flow through this system.
  </Step>

  <Step title="State Machine">
    Maintains the current state of all entities (sensors, lights, switches, etc.). Each state includes attributes, timestamps, and context.
  </Step>

  <Step title="Service Registry">
    Services are callable actions that components expose (e.g., `light.turn_on`, `climate.set_temperature`). The registry manages service registration and invocation.
  </Step>

  <Step title="Integration Loader">
    Dynamically loads and manages integrations, handling dependencies and ensuring proper initialization order.
  </Step>
</Steps>

### Key Constants

Home Assistant defines important constants in `homeassistant/const.py`:

```python theme={null}
# Version information
MAJOR_VERSION: Final = 2026
MINOR_VERSION: Final = 4
PATCH_VERSION: Final = "0.dev0"
REQUIRED_PYTHON_VER: Final[tuple[int, int, int]] = (3, 14, 2)

# Core events
EVENT_STATE_CHANGED = "state_changed"
EVENT_HOMEASSISTANT_START = "homeassistant_start"
EVENT_HOMEASSISTANT_STOP = "homeassistant_stop"
EVENT_SERVICE_REGISTERED = "service_registered"
```

## Platform Support

Home Assistant Core runs on:

* **Linux** (recommended for production)
* **macOS** (Darwin)
* **Windows** (via WSL - Windows Subsystem for Linux)

<Warning>
  Native Windows is not supported. You must use WSL on Windows systems.
</Warning>

## Component Lifecycle

Integrations follow a standardized lifecycle:

1. **Discovery** - Integration is discovered through configuration or config entries
2. **Dependency Resolution** - Required dependencies and other integrations are identified
3. **Setup** - The integration's `async_setup` or `async_setup_entry` is called
4. **Platform Loading** - Entity platforms (sensor, switch, etc.) are loaded
5. **Runtime** - Integration responds to events and provides services
6. **Shutdown** - Graceful cleanup when Home Assistant stops

## Event-Driven Architecture

Home Assistant's event-driven design enables loose coupling between components:

```python theme={null}
# Components listen for events
@callback
def handle_state_change(event: Event) -> None:
    """Handle state change events."""
    entity_id = event.data["entity_id"]
    new_state = event.data["new_state"]
    # React to state changes

hass.bus.async_listen(EVENT_STATE_CHANGED, handle_state_change)

# Components fire events
hass.bus.async_fire("custom_event", {"key": "value"})
```

## Asyncio-Based

Home Assistant Core is built on Python's `asyncio` library, enabling:

* **Non-blocking I/O** - Thousands of devices can be managed concurrently
* **Efficient resource usage** - Single-threaded event loop with minimal overhead
* **Responsive UI** - The web interface remains responsive during heavy operations

<Tip>
  Understanding asyncio is essential for Home Assistant development. Most integration code should be async and use `await` for I/O operations.
</Tip>

## Configuration Management

Home Assistant uses YAML for configuration, with the main configuration file at `configuration.yaml`:

```yaml theme={null}
# Example configuration
homeassistant:
  name: Home
  latitude: 37.7749
  longitude: -122.4194
  elevation: 0
  unit_system: metric
  time_zone: America/Los_Angeles

# Load integrations
http:
api:
automation: !include automations.yaml
```

## Next Steps

Now that you understand what Home Assistant Core is, you can:

* Follow the [Quickstart](/quickstart) guide to get up and running quickly
* Read the [Installation](/installation) guide for detailed setup instructions
* Learn about [Configuration](/configuration) options

## Additional Resources

* [Official Home Assistant Website](https://www.home-assistant.io/)
* [Developer Documentation](https://developers.home-assistant.io/)
* [Source Code on GitHub](https://github.com/home-assistant/core)
* [Community Forum](https://community.home-assistant.io/)