0
# Entity Framework
1

2
Base classes and utilities for creating entities that represent devices, sensors, switches, and other controllable objects in Home Assistant. The entity framework provides standardized interfaces for state management, device information, and platform integration.
3

4
## Capabilities
5

6
### Base Entity
7

8
The fundamental base class that all Home Assistant entities inherit from, providing core functionality for state management, device integration, and entity lifecycle.
9

10
```python { .api }
11
class Entity:
12
    """Base class for all Home Assistant entities."""
13
    
14
    def __init__(self):
15
        """Initialize entity."""
16
    
17
    @property
18
    def entity_id(self) -> str:
19
        """Return entity ID."""
20
        
21
    @property
22
    def name(self) -> str:
23
        """Return name of entity."""
24
        
25
    @property
26
    def state(self) -> str:
27
        """Return state of the entity."""
28
        
29
    @property
30
    def should_poll(self) -> bool:
31
        """Return True if entity should be polled for updates."""
32
        
33
    @property
34
    def unique_id(self) -> str:
35
        """Return unique ID for entity."""
36
        
37
    @property
38
    def device_info(self) -> dict:
39
        """Return device information for entity."""
40
        
41
    @property
42
    def available(self) -> bool:
43
        """Return True if entity is available."""
44
        
45
    @property
46
    def assumed_state(self) -> bool:
47
        """Return True if unable to access real state of entity."""
48
        
49
    @property
50
    def force_update(self) -> bool:
51
        """Return True if state updates should be forced."""
52
        
53
    @property
54
    def supported_features(self) -> int:
55
        """Flag supported features."""
56
        
57
    @property
58
    def device_class(self) -> str:
59
        """Return device class of entity."""
60
        
61
    @property
62
    def unit_of_measurement(self) -> str:
63
        """Return unit of measurement of entity."""
64
        
65
    @property
66
    def icon(self) -> str:
67
        """Return icon to use in frontend."""
68
        
69
    @property
70
    def entity_picture(self) -> str:
71
        """Return picture to use for entity."""
72
        
73
    @property
74
    def hidden(self) -> bool:
75
        """Return True if entity should be hidden from UI."""
76
        
77
    @property
78
    def entity_registry_enabled_default(self) -> bool:
79
        """Return if entity should be enabled by default in entity registry."""
80
        
81
    @property
82
    def entity_category(self) -> str:
83
        """Return category of entity."""
84
        
85
    @property
86
    def extra_state_attributes(self) -> dict:
87
        """Return entity specific state attributes."""
88
        
89
    @property
90
    def state_attributes(self) -> dict:
91
        """Return state attributes."""
92
        
93
    async def async_added_to_hass(self) -> None:
94
        """Run when entity about to be added to hass."""
95
        
96
    async def async_will_remove_from_hass(self) -> None:
97
        """Run when entity will be removed from hass."""
98
        
99
    async def async_update(self) -> None:
100
        """Update the entity."""
101
        
102
    def update(self) -> None:
103
        """Update the entity (sync version)."""
104
        
105
    def schedule_update_ha_state(self, force_refresh: bool = False) -> None:
106
        """Schedule update of Home Assistant state.
107
        
108
        Args:
109
            force_refresh: Force entity to refresh
110
        """
111
        
112
    async def async_schedule_update_ha_state(self, force_refresh: bool = False) -> None:
113
        """Schedule async update of Home Assistant state.
114
        
115
        Args:
116
            force_refresh: Force entity to refresh
117
        """
118
```
119

120
### Toggle Entity
121

122
Base class for entities that can be turned on and off, such as switches, lights, and other controllable devices.
123

124
```python { .api }
125
class ToggleEntity(Entity):
126
    """Base class for entities that can be turned on/off."""
127
    
128
    @property
129
    def is_on(self) -> bool:
130
        """Return True if entity is on."""
131
        
132
    def turn_on(self, **kwargs) -> None:
133
        """Turn entity on."""
134
        
135
    def turn_off(self, **kwargs) -> None:
136
        """Turn entity off."""
137
        
138
    def toggle(self, **kwargs) -> None:
139
        """Toggle entity."""
140
        
141
    async def async_turn_on(self, **kwargs) -> None:
142
        """Turn entity on asynchronously."""
143
        
144
    async def async_turn_off(self, **kwargs) -> None:
145
        """Turn entity off asynchronously."""
146
        
147
    async def async_toggle(self, **kwargs) -> None:
148
        """Toggle entity asynchronously."""
149
```
150

151
### Platform Entities
152

153
Specialized entity base classes for different device types and platforms.
154

155
```python { .api }
156
# Sensor entities
157
class SensorEntity(Entity):
158
    """Base class for sensor entities."""
159
    
160
    @property
161
    def native_value(self) -> Union[str, int, float, None]:
162
        """Return native value of sensor."""
163
        
164
    @property
165
    def native_unit_of_measurement(self) -> str:
166
        """Return native unit of measurement."""
167

168
class BinarySensorEntity(Entity):
169
    """Base class for binary sensor entities."""
170
    
171
    @property
172
    def is_on(self) -> bool:
173
        """Return True if binary sensor is on."""
174

175
# Control entities  
176
class SwitchEntity(ToggleEntity):
177
    """Base class for switch entities."""
178

179
class LightEntity(ToggleEntity):
180
    """Base class for light entities."""
181
    
182
    @property
183
    def brightness(self) -> int:
184
        """Return brightness of light (0-255)."""
185
        
186
    @property
187
    def hs_color(self) -> tuple[float, float]:
188
        """Return hue and saturation color value."""
189
        
190
    @property
191
    def color_temp(self) -> int:
192
        """Return color temperature in mireds."""
193

194
class FanEntity(ToggleEntity):
195
    """Base class for fan entities."""
196
    
197
    @property
198
    def speed(self) -> str:
199
        """Return current speed."""
200
        
201
    @property
202
    def speed_list(self) -> list[str]:
203
        """Return list of available speeds."""
204

205
class CoverEntity(Entity):
206
    """Base class for cover entities."""
207
    
208
    @property
209
    def current_cover_position(self) -> int:
210
        """Return current position (0-100)."""
211
        
212
    @property
213
    def is_closed(self) -> bool:
214
        """Return True if cover is closed."""
215
        
216
    def open_cover(self, **kwargs) -> None:
217
        """Open cover."""
218
        
219
    def close_cover(self, **kwargs) -> None:
220
        """Close cover."""
221
        
222
    def stop_cover(self, **kwargs) -> None:
223
        """Stop cover."""
224

225
class ClimateEntity(Entity):
226
    """Base class for climate entities."""
227
    
228
    @property
229
    def current_temperature(self) -> float:
230
        """Return current temperature."""
231
        
232
    @property
233
    def target_temperature(self) -> float:
234
        """Return target temperature."""
235
        
236
    @property
237
    def hvac_mode(self) -> str:
238
        """Return current operation mode."""
239
        
240
    @property
241
    def hvac_modes(self) -> list[str]:
242
        """Return available operation modes."""
243
```
244

245
### Entity Generation
246

247
Utilities for generating and managing entity IDs and entity creation.
248

249
```python { .api }
250
def generate_entity_id(entity_id_format: str, name: str, 
251
                      current_ids: list[str] = None, hass: HomeAssistant = None) -> str:
252
    """Generate unique entity ID.
253
    
254
    Args:
255
        entity_id_format: Format string for entity ID (e.g., 'sensor.{}')
256
        name: Name to base entity ID on
257
        current_ids: List of existing entity IDs
258
        hass: Home Assistant instance
259
        
260
    Returns:
261
        Generated entity ID
262
    """
263

264
async def async_generate_entity_id(entity_id_format: str, name: str,
265
                                  current_ids: list[str] = None, 
266
                                  hass: HomeAssistant = None) -> str:
267
    """Generate unique entity ID asynchronously.
268
    
269
    Args:
270
        entity_id_format: Format string for entity ID (e.g., 'sensor.{}')
271
        name: Name to base entity ID on
272
        current_ids: List of existing entity IDs
273
        hass: Home Assistant instance
274
        
275
    Returns:
276
        Generated entity ID
277
    """
278

279
def get_capability(hass: HomeAssistant, entity_id: str, capability: str) -> Any:
280
    """Get capability of an entity.
281
    
282
    Args:
283
        hass: Home Assistant instance
284
        entity_id: Entity ID
285
        capability: Capability name
286
        
287
    Returns:
288
        Capability value or None
289
    """
290

291
def get_device_class(hass: HomeAssistant, entity_id: str) -> str:
292
    """Get device class of an entity.
293
    
294
    Args:
295
        hass: Home Assistant instance
296
        entity_id: Entity ID
297
        
298
    Returns:
299
        Device class or None
300
    """
301

302
def get_supported_features(hass: HomeAssistant, entity_id: str) -> int:
303
    """Get supported features of an entity.
304
    
305
    Args:
306
        hass: Home Assistant instance
307
        entity_id: Entity ID
308
        
309
    Returns:
310
        Supported features bitmask
311
    """
312
```
313

314
### Entity Platform
315

316
Base class for entity platforms that manage collections of related entities.
317

318
```python { .api }
319
class EntityPlatform:
320
    """Platform for managing a group of entities."""
321
    
322
    def __init__(self, hass: HomeAssistant, logger: logging.Logger, domain: str,
323
                 platform_name: str, platform: Any, scan_interval: timedelta,
324
                 entity_namespace: str):
325
        """Initialize entity platform.
326
        
327
        Args:
328
            hass: Home Assistant instance
329
            logger: Logger for platform
330
            domain: Entity domain
331
            platform_name: Platform name
332
            platform: Platform module
333
            scan_interval: Update scan interval
334
            entity_namespace: Entity namespace
335
        """
336
    
337
    async def async_setup(self, platform_config: dict, 
338
                         discovery_info: dict = None) -> None:
339
        """Set up entity platform.
340
        
341
        Args:
342
            platform_config: Platform configuration
343
            discovery_info: Discovery information
344
        """
345
    
346
    async def async_reset(self) -> None:
347
        """Reset platform."""
348
    
349
    async def async_shutdown(self) -> None:
350
        """Shutdown platform."""
351
    
352
    async def async_add_entities(self, new_entities: list[Entity], 
353
                               update_before_add: bool = False) -> None:
354
        """Add entities to platform.
355
        
356
        Args:
357
            new_entities: List of entities to add
358
            update_before_add: Update entities before adding
359
        """
360
    
361
    async def async_remove_entity(self, entity_id: str) -> None:
362
        """Remove entity from platform.
363
        
364
        Args:
365
            entity_id: Entity ID to remove
366
        """
367
```
368

369
## Types
370

371
```python { .api }
372
from typing import Any, Dict, List, Optional, Union
373
from enum import Enum
374

375
# Entity categories
376
class EntityCategory(Enum):
377
    """Category of entity."""
378
    CONFIG = "config"
379
    DIAGNOSTIC = "diagnostic"
380

381
# Device classes (examples for major domains)
382
class SensorDeviceClass(Enum):
383
    """Device class for sensors."""
384
    TEMPERATURE = "temperature"
385
    HUMIDITY = "humidity"
386
    PRESSURE = "pressure"
387
    BATTERY = "battery"
388
    ENERGY = "energy"
389
    POWER = "power"
390

391
class BinarySensorDeviceClass(Enum):
392
    """Device class for binary sensors."""
393
    BATTERY = "battery"
394
    COLD = "cold"
395
    CONNECTIVITY = "connectivity"
396
    DOOR = "door"
397
    GARAGE_DOOR = "garage_door"
398
    HEAT = "heat"
399
    LIGHT = "light"
400
    LOCK = "lock"
401
    MOISTURE = "moisture"
402
    MOTION = "motion"
403
    MOVING = "moving"
404
    OCCUPANCY = "occupancy"
405
    OPENING = "opening"
406
    PLUG = "plug"
407
    POWER = "power"
408
    PRESENCE = "presence"
409
    PROBLEM = "problem"
410
    RUNNING = "running"
411
    SAFETY = "safety"
412
    SMOKE = "smoke"
413
    SOUND = "sound"
414
    UPDATE = "update"
415
    VIBRATION = "vibration"
416
    WINDOW = "window"
417

418
# Type aliases
419
EntityIdType = str
420
StateType = Union[None, str, int, float, bool]
421
AttributesType = Dict[str, Any]
422
DeviceInfoType = Dict[str, Any]
423
SupportedFeaturesType = int
424
```