3.5 KiB
| title | sidebar_label |
|---|---|
| Device Registry | Introduction |
The device registry is a registry where Home Assistant keeps track of devices. A device is represented in Home Assistant via one or more entities. For example, a battery-powered temperature and a humidity sensor might expose entities for temperature, humidity and battery level.
What is a device?
A device in Home Assistant represents a physical device that has its own control unit. The control unit itself does not have to be smart, but it should be in control of what happens. For example, an Ecobee thermostat with 4 room sensors equals 5 devices in Home Assistant, one for the thermostat including all sensors inside it, and one for each sensor.
If you connect a sensor to another device to read some of its data, it should still be represented as two different devices. The reason for this is that the sensor could be moved to read the data of another device.
Although not currently available, we could consider offering an option to users to merge devices.
Device properties
| Attribute | Description |
|---|---|
| id | Unique ID of device (generated by Home Assistant) |
| name | Name of this device |
| connections | A set of tuples of (connection_type, connection identifier). Connection types are defined in the device registry module. |
| identifiers | Set of identifiers. They identify the device in the outside world. An example is a serial number. |
| manufacturer | The manufacturer of the device. |
| model | The model of the device. |
| config_entries | Config entries that are linked to this device. |
| sw_version | The firmware version of the device. |
| via_hub | Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs. This is used to show device topology in Home Assistant. |
| area_id | The Area which the device is placed in. |
Defining devices
Entity device info is only read if the entity is loaded via a config entry.
Each entity is able to define a device via the device_info property. This property is read when an entity is added to Home Assistant via a config entry. A device will be matched up with an existing device via supplied identifiers and connections, like serial numbers or MAC addresses.
# Inside a platform
class HueLight(LightEntity):
@property
def device_info(self):
return {
'identifiers': {
# Serial numbers are unique identifiers within a specific domain
(hue.DOMAIN, self.unique_id)
},
'name': self.name,
'manufacturer': self.light.manufacturername,
'model': self.light.productname,
'sw_version': self.light.swversion,
'via_hub': (hue.DOMAIN, self.api.bridgeid),
}
Components are also able to register devices in the case that there are no entities representing them. An example is a hub that communicates with the lights.
# Inside a component
from homeassistant.helpers import device_registry as dr
device_registry = await dr.async_get_registry(hass)
device_registry.async_get_or_create(
config_entry=entry.entry_id,
connections={
(dr.CONNECTION_NETWORK_MAC, config.mac)
},
identifiers={
(DOMAIN, config.bridgeid)
},
manufacturer='Signify',
name=config.name,
model=config.modelid,
sw_version=config.swversion,
)