0
# Home Assistant
1

2
Home Assistant is a comprehensive open-source home automation platform that provides local control and privacy-focused smart home management. Built in Python 3, it supports over 1,370 integrations for connecting and controlling various smart devices, sensors, and services. The platform features a modular architecture with components for authentication, configuration management, data flow handling, and extensive helper utilities.
3

4
## Package Information
5

6
- **Package Name**: homeassistant
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install homeassistant`
10
- **License**: Apache-2.0
11
- **Documentation**: https://www.home-assistant.io/docs/
12

13
## Core Imports
14

15
```python
16
import homeassistant
17
```
18

19
For core functionality:
20

21
```python
22
from homeassistant.core import HomeAssistant, Event, State, ServiceCall, callback
23
from homeassistant.config_entries import ConfigEntry
24
from homeassistant.helpers.entity import Entity
25
```
26

27
For integration development:
28

29
```python
30
from homeassistant.helpers.config_validation import PLATFORM_SCHEMA
31
from homeassistant.const import CONF_NAME, STATE_ON, STATE_OFF
32
```
33

34
## Basic Usage
35

36
```python
37
import asyncio
38
from homeassistant.core import HomeAssistant
39
from homeassistant.helpers.service import async_register_admin_service
40

41
# Create Home Assistant instance
42
hass = HomeAssistant('/path/to/config')
43

44
# Register a simple service
45
async def handle_hello_service(call):
46
    """Handle the hello service call."""
47
    name = call.data.get('name', 'World')
48
    hass.states.async_set('sensor.hello', f'Hello {name}!')
49

50
# Register the service
51
hass.services.async_register('example', 'hello', handle_hello_service)
52

53
# Set up entity state
54
hass.states.async_set('sensor.temperature', '23.5', {
55
    'unit_of_measurement': '°C',
56
    'friendly_name': 'Temperature'
57
})
58

59
# Listen for state changes
60
@callback
61
def state_changed_listener(event):
62
    """Handle state changed events."""
63
    old_state = event.data.get('old_state')
64
    new_state = event.data.get('new_state')
65
    print(f"State changed: {old_state.state} -> {new_state.state}")
66

67
hass.bus.async_listen('state_changed', state_changed_listener)
68
```
69

70
## Architecture
71

72
Home Assistant uses a modular, async-first architecture built around several core concepts:
73

74
- **HomeAssistant Instance**: Central coordinator managing all platform components and services
75
- **Entity System**: Object model for devices, sensors, and controls with standardized interfaces
76
- **Integration Framework**: Plugin system supporting 1300+ device and service integrations
77
- **Configuration System**: YAML-based configuration with UI-driven setup flows
78
- **Event System**: Pub/sub architecture for real-time communication between components
79
- **State Machine**: Centralized state management with persistence and change tracking
80
- **Helper Libraries**: Extensive utilities for validation, templating, networking, and async operations
81

82
## Capabilities
83

84
### Core System
85

86
Central Home Assistant runtime providing the foundation for all automation and integration functionality. Includes the main HomeAssistant instance, event system, state management, and service registry.
87

88
```python { .api }
89
class HomeAssistant:
90
    def __init__(self, config_dir: str = None): ...
91
    async def async_start(self) -> None: ...
92
    async def async_stop(self, exit_code: int = 0) -> None: ...
93
    async def async_run(self, *, attach_signals: bool = True) -> int: ...
94
    
95
    # Core properties
96
    states: StateMachine
97
    services: ServiceRegistry  
98
    bus: EventBus
99
    config: Config
100
```
101

102
[Core System](./core-system.md)
103

104
### Entity Framework
105

106
Base classes and utilities for creating entities that represent devices, sensors, switches, and other controllable objects in Home Assistant. Provides standardized interfaces for state management, device information, and platform integration.
107

108
```python { .api }
109
class Entity:
110
    def __init__(self): ...
111
    @property
112
    def entity_id(self) -> str: ...
113
    @property 
114
    def name(self) -> str: ...
115
    @property
116
    def state(self) -> str: ...
117
    async def async_added_to_hass(self) -> None: ...
118
```
119

120
[Entity Framework](./entity-framework.md)
121

122
### Configuration Management
123

124
Configuration loading, validation, and management system supporting both YAML files and UI-driven configuration flows. Handles integration discovery, dependency resolution, and configuration entry lifecycle.
125

126
```python { .api }
127
class ConfigEntry:
128
    @property
129
    def entry_id(self) -> str: ...
130
    @property
131
    def domain(self) -> str: ...
132
    @property 
133
    def data(self) -> dict: ...
134
    async def async_setup(self, hass: HomeAssistant) -> bool: ...
135
```
136

137
[Configuration Management](./configuration.md)
138

139
### Helper Utilities
140

141
Comprehensive collection of utility functions and classes for common Home Assistant development tasks including validation, templating, event handling, service management, and async operations.
142

143
```python { .api }
144
def callback(func: Callable) -> Callable: ...
145
def split_entity_id(entity_id: str) -> tuple[str, str]: ...
146
def valid_entity_id(entity_id: str) -> bool: ...
147

148
# Validation utilities
149
import homeassistant.helpers.config_validation as cv
150
def entity_id(value: Any) -> str: ...
151
def positive_int(value: Any) -> int: ...
152
```
153

154
[Helper Utilities](./helpers.md)
155

156
### Integration Framework
157

158
System for loading, managing, and configuring integrations that connect Home Assistant to external devices, services, and platforms. Supports dynamic loading, dependency management, and platform-specific setup.
159

160
```python { .api }
161
class Integration:
162
    @property
163
    def domain(self) -> str: ...
164
    @property
165
    def name(self) -> str: ...
166
    @property
167
    def requirements(self) -> list[str]: ...
168
    
169
async def async_get_integration(hass: HomeAssistant, domain: str) -> Integration: ...
170
```
171

172
[Integration Framework](./integration-framework.md)
173

174
### Registry System
175

176
Central registries for managing entities, devices, and areas within Home Assistant. Provides persistent storage, relationship tracking, and metadata management for the entity ecosystem.
177

178
```python { .api }
179
class EntityRegistry:
180
    async def async_get_or_create(
181
        self, domain: str, platform: str, unique_id: str, **kwargs
182
    ) -> RegistryEntry: ...
183
    
184
class DeviceRegistry:
185
    async def async_get_or_create(
186
        self, *, config_entry_id: str, identifiers: set, **kwargs  
187
    ) -> DeviceEntry: ...
188
```
189

190
[Registry System](./registries.md)
191

192
### Authentication & Authorization
193

194
Security framework providing user management, OAuth token handling, multi-factor authentication, and permission-based access control for Home Assistant instances.
195

196
```python { .api }
197
class AuthManager:
198
    async def async_create_system_user(self, name: str) -> User: ...
199
    async def async_validate_access_token(self, token: str) -> AccessToken: ...
200
    
201
class User:
202
    @property
203
    def id(self) -> str: ...
204
    @property
205
    def is_owner(self) -> bool: ...
206
```
207

208
[Authentication & Authorization](./auth.md)
209

210
## Constants and Enums
211

212
```python { .api }
213
# Platform types
214
ALARM_CONTROL_PANEL = "alarm_control_panel"
215
BINARY_SENSOR = "binary_sensor" 
216
BUTTON = "button"
217
CAMERA = "camera"
218
CLIMATE = "climate"
219
COVER = "cover"
220
DEVICE_TRACKER = "device_tracker"
221
FAN = "fan"
222
LIGHT = "light"
223
LOCK = "lock"
224
MEDIA_PLAYER = "media_player"
225
SENSOR = "sensor"
226
SWITCH = "switch"
227
VACUUM = "vacuum"
228

229
# Configuration keys
230
CONF_NAME = "name"
231
CONF_HOST = "host"
232
CONF_PORT = "port"
233
CONF_USERNAME = "username"
234
CONF_PASSWORD = "password"
235
CONF_API_KEY = "api_key"
236

237
# State values
238
STATE_ON = "on"  
239
STATE_OFF = "off"
240
STATE_OPEN = "open"
241
STATE_CLOSED = "closed"
242
STATE_UNKNOWN = "unknown"
243
STATE_UNAVAILABLE = "unavailable"
244

245
# Service names
246
SERVICE_TURN_ON = "turn_on"
247
SERVICE_TURN_OFF = "turn_off"
248
SERVICE_TOGGLE = "toggle"
249
SERVICE_RELOAD = "reload"
250

251
# Event types
252
EVENT_HOMEASSISTANT_START = "homeassistant_start"
253
EVENT_HOMEASSISTANT_STOP = "homeassistant_stop"
254
EVENT_STATE_CHANGED = "state_changed"
255
EVENT_SERVICE_REGISTERED = "service_registered"
256
```
257

258
## Types
259

260
```python { .api }
261
from typing import Any, Callable, Dict, List, Optional, Union
262
from homeassistant.core import HomeAssistant
263

264
# Core types
265
EventType = str
266
StateType = Union[None, str, int, float, bool]
267
ServiceDataType = Dict[str, Any]
268
ConfigType = Dict[str, Any]
269
CallbackType = Callable[[], None]
270

271
# Entity ID validation
272
EntityIdValidatorType = Callable[[str], str]
273

274
# Template types  
275
TemplateType = Union[str, None]
276
```