0
# Registry System
1

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

4
## Capabilities
5

6
### Entity Registry
7

8
Central registry for managing entity metadata, customization, and persistence across Home Assistant restarts.
9

10
```python { .api }
11
class EntityRegistry:
12
    """Registry for entity metadata and configuration."""
13
    
14
    def __init__(self, hass: HomeAssistant):
15
        """Initialize entity registry.
16
        
17
        Args:
18
            hass: Home Assistant instance
19
        """
20
    
21
    async def async_get_or_create(self, domain: str, platform: str, unique_id: str,
22
                                 suggested_object_id: str = None, config_entry: ConfigEntry = None,
23
                                 device_id: str = None, known_object_ids: set[str] = None,
24
                                 disabled_by: str = None, capabilities: dict = None,
25
                                 supported_features: int = None, device_class: str = None,
26
                                 unit_of_measurement: str = None, original_name: str = None,
27
                                 original_icon: str = None) -> RegistryEntry:
28
        """Get or create entity registry entry.
29
        
30
        Args:
31
            domain: Entity domain
32
            platform: Entity platform
33
            unique_id: Unique identifier
34
            suggested_object_id: Suggested object ID
35
            config_entry: Associated config entry
36
            device_id: Associated device ID
37
            known_object_ids: Known object IDs to avoid
38
            disabled_by: Reason entity is disabled
39
            capabilities: Entity capabilities
40
            supported_features: Supported features bitmask
41
            device_class: Device class
42
            unit_of_measurement: Unit of measurement
43
            original_name: Original entity name
44
            original_icon: Original entity icon
45
            
46
        Returns:
47
            Registry entry
48
        """
49
    
50
    async def async_update_entity(self, entity_id: str, *, name: str = None,
51
                                 icon: str = None, area_id: str = None,
52
                                 device_class: str = None, disabled_by: str = None,
53
                                 entity_category: str = None, hidden_by: str = None,
54
                                 new_entity_id: str = None, new_unique_id: str = None,
55
                                 **kwargs) -> RegistryEntry:
56
        """Update entity registry entry.
57
        
58
        Args:
59
            entity_id: Entity ID to update
60
            name: New name
61
            icon: New icon
62
            area_id: New area ID
63
            device_class: New device class
64
            disabled_by: Disable reason
65
            entity_category: Entity category
66
            hidden_by: Hide reason
67
            new_entity_id: New entity ID
68
            new_unique_id: New unique ID
69
            **kwargs: Additional update parameters
70
            
71
        Returns:
72
            Updated registry entry
73
        """
74
    
75
    async def async_remove(self, entity_id: str) -> None:
76
        """Remove entity from registry.
77
        
78
        Args:
79
            entity_id: Entity ID to remove
80
        """
81
    
82
    def async_get_entity_id(self, domain: str, platform: str, unique_id: str) -> str:
83
        """Get entity ID for domain/platform/unique_id.
84
        
85
        Args:
86
            domain: Entity domain
87
            platform: Entity platform
88
            unique_id: Unique identifier
89
            
90
        Returns:
91
            Entity ID or None if not found
92
        """
93
    
94
    def async_get_device_class(self, entity_id: str) -> str:
95
        """Get device class for entity.
96
        
97
        Args:
98
            entity_id: Entity ID
99
            
100
        Returns:
101
            Device class or None
102
        """
103
    
104
    @property
105
    def entities(self) -> dict[str, RegistryEntry]:
106
        """Return all entities."""
107

108
class RegistryEntry:
109
    """Entity registry entry."""
110
    
111
    def __init__(self, entity_id: str, unique_id: str, platform: str, domain: str,
112
                 config_entry_id: str = None, device_id: str = None,
113
                 area_id: str = None, capabilities: dict = None,
114
                 supported_features: int = None, device_class: str = None,
115
                 unit_of_measurement: str = None, original_name: str = None,
116
                 original_icon: str = None, entity_category: str = None,
117
                 disabled_by: str = None, hidden_by: str = None,
118
                 icon: str = None, name: str = None):
119
        """Initialize registry entry.
120
        
121
        Args:
122
            entity_id: Entity ID
123
            unique_id: Unique identifier
124
            platform: Entity platform
125
            domain: Entity domain
126
            config_entry_id: Config entry ID
127
            device_id: Device ID
128
            area_id: Area ID
129
            capabilities: Entity capabilities
130
            supported_features: Supported features
131
            device_class: Device class
132
            unit_of_measurement: Unit of measurement
133
            original_name: Original name
134
            original_icon: Original icon
135
            entity_category: Entity category
136
            disabled_by: Disabled reason
137
            hidden_by: Hidden reason
138
            icon: Custom icon
139
            name: Custom name
140
        """
141
    
142
    @property
143
    def entity_id(self) -> str:
144
        """Return entity ID."""
145
        
146
    @property
147
    def unique_id(self) -> str:
148
        """Return unique ID."""
149
        
150
    @property
151
    def platform(self) -> str:
152
        """Return platform."""
153
        
154
    @property
155
    def domain(self) -> str:
156
        """Return domain."""
157
        
158
    @property
159
    def config_entry_id(self) -> str:
160
        """Return config entry ID."""
161
        
162
    @property
163
    def device_id(self) -> str:
164
        """Return device ID."""
165
        
166
    @property
167
    def area_id(self) -> str:
168
        """Return area ID."""
169
        
170
    @property
171
    def name(self) -> str:
172
        """Return entity name."""
173
        
174
    @property
175
    def icon(self) -> str:
176
        """Return entity icon."""
177
        
178
    @property
179
    def disabled(self) -> bool:
180
        """Return True if entity is disabled."""
181
        
182
    @property
183
    def hidden(self) -> bool:
184
        """Return True if entity is hidden."""
185
```
186

187
### Device Registry
188

189
Central registry for managing device information, connections, and relationships with entities.
190

191
```python { .api }
192
class DeviceRegistry:
193
    """Registry for device information and configuration."""
194
    
195
    def __init__(self, hass: HomeAssistant):
196
        """Initialize device registry.
197
        
198
        Args:
199
            hass: Home Assistant instance
200
        """
201
    
202
    async def async_get_or_create(self, *, config_entry_id: str, connections: set = None,
203
                                 identifiers: set = None, manufacturer: str = None,
204
                                 model: str = None, name: str = None, 
205
                                 sw_version: str = None, hw_version: str = None,
206
                                 entry_type: str = None, via_device: tuple = None,
207
                                 area_id: str = None, name_by_user: str = None,
208
                                 suggested_area: str = None, disabled_by: str = None,
209
                                 configuration_url: str = None) -> DeviceEntry:
210
        """Get or create device registry entry.
211
        
212
        Args:
213
            config_entry_id: Config entry ID
214
            connections: Device connections
215
            identifiers: Device identifiers
216
            manufacturer: Device manufacturer
217
            model: Device model
218
            name: Device name
219
            sw_version: Software version
220
            hw_version: Hardware version
221
            entry_type: Entry type
222
            via_device: Parent device
223
            area_id: Area ID
224
            name_by_user: User-defined name
225
            suggested_area: Suggested area
226
            disabled_by: Disable reason
227
            configuration_url: Configuration URL
228
            
229
        Returns:
230
            Device entry
231
        """
232
    
233
    async def async_update_device(self, device_id: str, *, area_id: str = None,
234
                                 manufacturer: str = None, model: str = None,
235
                                 name: str = None, name_by_user: str = None,
236
                                 sw_version: str = None, hw_version: str = None,
237
                                 disabled_by: str = None, new_identifiers: set = None,
238
                                 merge_identifiers: set = None, merge_connections: set = None,
239
                                 configuration_url: str = None, **kwargs) -> DeviceEntry:
240
        """Update device registry entry.
241
        
242
        Args:
243
            device_id: Device ID to update
244
            area_id: New area ID
245
            manufacturer: New manufacturer
246
            model: New model
247
            name: New name
248
            name_by_user: User-defined name
249
            sw_version: Software version
250
            hw_version: Hardware version
251
            disabled_by: Disable reason
252
            new_identifiers: New identifiers
253
            merge_identifiers: Identifiers to merge
254
            merge_connections: Connections to merge
255
            configuration_url: Configuration URL
256
            **kwargs: Additional update parameters
257
            
258
        Returns:
259
            Updated device entry
260
        """
261
    
262
    async def async_remove_device(self, device_id: str) -> None:
263
        """Remove device from registry.
264
        
265
        Args:
266
            device_id: Device ID to remove
267
        """
268
    
269
    def async_get_device(self, identifiers: set = None, connections: set = None) -> DeviceEntry:
270
        """Get device by identifiers or connections.
271
        
272
        Args:
273
            identifiers: Device identifiers
274
            connections: Device connections
275
            
276
        Returns:
277
            Device entry or None
278
        """
279
    
280
    @property
281
    def devices(self) -> dict[str, DeviceEntry]:
282
        """Return all devices."""
283

284
class DeviceEntry:
285
    """Device registry entry."""
286
    
287
    def __init__(self, id: str, config_entries: set[str], connections: set,
288
                 identifiers: set, manufacturer: str = None, model: str = None,
289
                 name: str = None, sw_version: str = None, hw_version: str = None,
290
                 entry_type: str = None, via_device_id: str = None,
291
                 area_id: str = None, name_by_user: str = None,
292
                 disabled_by: str = None, configuration_url: str = None):
293
        """Initialize device entry.
294
        
295
        Args:
296
            id: Device ID
297
            config_entries: Associated config entries
298
            connections: Device connections
299
            identifiers: Device identifiers
300
            manufacturer: Device manufacturer
301
            model: Device model
302
            name: Device name
303
            sw_version: Software version
304
            hw_version: Hardware version
305
            entry_type: Entry type
306
            via_device_id: Parent device ID
307
            area_id: Area ID
308
            name_by_user: User-defined name
309
            disabled_by: Disabled reason
310
            configuration_url: Configuration URL
311
        """
312
    
313
    @property
314
    def id(self) -> str:
315
        """Return device ID."""
316
        
317
    @property
318
    def identifiers(self) -> set:
319
        """Return device identifiers."""
320
        
321
    @property
322
    def connections(self) -> set:
323
        """Return device connections."""
324
        
325
    @property
326
    def manufacturer(self) -> str:
327
        """Return device manufacturer."""
328
        
329
    @property
330
    def model(self) -> str:
331
        """Return device model."""
332
        
333
    @property
334
    def name(self) -> str:
335
        """Return device name."""
336
        
337
    @property
338
    def name_by_user(self) -> str:
339
        """Return user-defined name."""
340
        
341
    @property
342
    def sw_version(self) -> str:
343
        """Return software version."""
344
        
345
    @property
346
    def hw_version(self) -> str:
347
        """Return hardware version."""
348
        
349
    @property
350
    def via_device_id(self) -> str:
351
        """Return parent device ID."""
352
        
353
    @property
354
    def area_id(self) -> str:
355
        """Return area ID."""
356
        
357
    @property
358
    def disabled(self) -> bool:
359
        """Return True if device is disabled."""
360
        
361
    @property
362
    def configuration_url(self) -> str:
363
        """Return configuration URL."""
364
```
365

366
### Area Registry
367

368
Registry for managing logical areas and organizing entities and devices into rooms or zones.
369

370
```python { .api }
371
class AreaRegistry:
372
    """Registry for area information and configuration."""
373
    
374
    def __init__(self, hass: HomeAssistant):
375
        """Initialize area registry.
376
        
377
        Args:
378
            hass: Home Assistant instance
379
        """
380
    
381
    async def async_create(self, name: str, *, normalized_name: str = None,
382
                          picture: str = None) -> AreaEntry:
383
        """Create area registry entry.
384
        
385
        Args:
386
            name: Area name
387
            normalized_name: Normalized name
388
            picture: Area picture
389
            
390
        Returns:
391
            Created area entry
392
        """
393
    
394
    async def async_update(self, area_id: str, *, name: str = None,
395
                          picture: str = None) -> AreaEntry:
396
        """Update area registry entry.
397
        
398
        Args:
399
            area_id: Area ID to update
400
            name: New name
401
            picture: New picture
402
            
403
        Returns:
404
            Updated area entry
405
        """
406
    
407
    async def async_delete(self, area_id: str) -> None:
408
        """Delete area from registry.
409
        
410
        Args:
411
            area_id: Area ID to delete
412
        """
413
    
414
    def async_get_area(self, area_id: str) -> AreaEntry:
415
        """Get area by ID.
416
        
417
        Args:
418
            area_id: Area ID
419
            
420
        Returns:
421
            Area entry or None
422
        """
423
    
424
    def async_get_area_by_name(self, name: str) -> AreaEntry:
425
        """Get area by name.
426
        
427
        Args:
428
            name: Area name
429
            
430
        Returns:
431
            Area entry or None
432
        """
433
    
434
    @property
435
    def areas(self) -> dict[str, AreaEntry]:
436
        """Return all areas."""
437

438
class AreaEntry:
439
    """Area registry entry."""
440
    
441
    def __init__(self, id: str, name: str, normalized_name: str, 
442
                 picture: str = None):
443
        """Initialize area entry.
444
        
445
        Args:
446
            id: Area ID
447
            name: Area name
448
            normalized_name: Normalized name
449
            picture: Area picture
450
        """
451
    
452
    @property
453
    def id(self) -> str:
454
        """Return area ID."""
455
        
456
    @property
457
    def name(self) -> str:
458
        """Return area name."""
459
        
460
    @property
461
    def normalized_name(self) -> str:
462
        """Return normalized name."""
463
        
464
    @property
465
    def picture(self) -> str:
466
        """Return area picture."""
467
```
468

469
### Registry Utilities
470

471
Utility functions for working with registries and managing entity relationships.
472

473
```python { .api }
474
async def async_get_registry(hass: HomeAssistant, registry_type: str) -> Union[EntityRegistry, DeviceRegistry, AreaRegistry]:
475
    """Get registry instance.
476
    
477
    Args:
478
        hass: Home Assistant instance
479
        registry_type: Registry type ('entity', 'device', 'area')
480
        
481
    Returns:
482
        Registry instance
483
    """
484

485
def async_entries_for_device(registry: EntityRegistry, device_id: str, 
486
                            include_disabled_entities: bool = False) -> list[RegistryEntry]:
487
    """Get entity entries for device.
488
    
489
    Args:
490
        registry: Entity registry
491
        device_id: Device ID
492
        include_disabled_entities: Include disabled entities
493
        
494
    Returns:
495
        List of entity entries
496
    """
497

498
def async_entries_for_area(registry: EntityRegistry, area_id: str) -> list[RegistryEntry]:
499
    """Get entity entries for area.
500
    
501
    Args:
502
        registry: Entity registry
503
        area_id: Area ID
504
        
505
    Returns:
506
        List of entity entries
507
    """
508

509
def async_entries_for_config_entry(registry: EntityRegistry, 
510
                                  config_entry_id: str) -> list[RegistryEntry]:
511
    """Get entity entries for config entry.
512
    
513
    Args:
514
        registry: Entity registry
515
        config_entry_id: Config entry ID
516
        
517
    Returns:
518
        List of entity entries
519
    """
520

521
async def async_migrate_entries(hass: HomeAssistant, config_entry_id: str,
522
                               entity_migration: dict[str, str]) -> None:
523
    """Migrate entity registry entries.
524
    
525
    Args:
526
        hass: Home Assistant instance
527
        config_entry_id: Config entry ID
528
        entity_migration: Migration mapping
529
    """
530
```
531

532
## Registry Constants
533

534
```python { .api }
535
# Entity registry disabled reasons
536
DISABLED_USER = "user"
537
DISABLED_DEVICE = "device"
538
DISABLED_CONFIG_ENTRY = "config_entry"
539
DISABLED_INTEGRATION = "integration"
540

541
# Entity registry hidden reasons  
542
HIDDEN_USER = "user"
543
HIDDEN_INTEGRATION = "integration"
544

545
# Device registry entry types
546
ENTRY_TYPE_SERVICE = "service"
547

548
# Device registry disabled reasons
549
DISABLED_USER = "user"
550
DISABLED_CONFIG_ENTRY = "config_entry"
551
DISABLED_INTEGRATION = "integration"
552

553
# Device connection types
554
CONNECTION_NETWORK_MAC = "mac"
555
CONNECTION_UPNP = "upnp"
556
CONNECTION_ZIGBEE = "zigbee"
557
CONNECTION_BLUETOOTH = "bluetooth"
558

559
# Entity categories
560
ENTITY_CATEGORY_CONFIG = "config"
561
ENTITY_CATEGORY_DIAGNOSTIC = "diagnostic"
562
```
563

564
## Types
565

566
```python { .api }
567
from typing import Any, Dict, List, Optional, Set, Union
568

569
# Registry entry types
570
RegistryEntryType = Dict[str, Any]
571
DeviceEntryType = Dict[str, Any]  
572
AreaEntryType = Dict[str, Any]
573

574
# Registry data types
575
EntityRegistryType = Dict[str, RegistryEntry]
576
DeviceRegistryType = Dict[str, DeviceEntry]
577
AreaRegistryType = Dict[str, AreaEntry]
578

579
# Device connection/identifier types
580
DeviceConnectionType = tuple[str, str]
581
DeviceIdentifierType = tuple[str, str]
582
DeviceConnectionsType = Set[DeviceConnectionType]
583
DeviceIdentifiersType = Set[DeviceIdentifierType]
584

585
# Registry ID types
586
EntityIdType = str
587
DeviceIdType = str
588
AreaIdType = str
589
ConfigEntryIdType = str
590
```