Device Registry

Registry for managing and tracking devices in Home Assistant.

The homeassistant.helpers.device_registry module provides a registry to track devices and their associations with config entries.

DeviceRegistry Class

The main class for managing device registration and lookup.

Key Methods

async_get

Get a device by device ID.

device_id · str · required

Device ID to retrieve

return · DeviceEntry | None

Device entry or None if not found

from homeassistant.helpers import device_registry as dr

dev_reg = dr.async_get(hass)
device = dev_reg.async_get(device_id)

async_get_device

Check if device is registered by identifiers or connections.

identifiers · set[tuple[str, str]] | None · default: "None"

Set of identifier tuples (domain, unique_id)

connections · set[tuple[str, str]] | None · default: "None"

Set of connection tuples (connection_type, connection_id)

return · DeviceEntry | None

Device entry or None if not found

device = dev_reg.async_get_device(
    identifiers={("hue", "00:11:22:33:44:55")}
)

async_get_or_create

Get device or create if it doesn’t exist.

config_entry_id · str · required

Config entry ID to link device to

config_subentry_id · str | None | UndefinedType · default: "UNDEFINED"

Config subentry ID

connections · set[tuple[str, str]] | None | UndefinedType · default: "UNDEFINED"

Device connections (e.g., MAC addresses)

identifiers · set[tuple[str, str]] | None | UndefinedType · default: "UNDEFINED"

Device identifiers

manufacturer · str | None | UndefinedType · default: "UNDEFINED"

Device manufacturer

model · str | None | UndefinedType · default: "UNDEFINED"

Device model

name · str | None | UndefinedType · default: "UNDEFINED"

Device name

sw_version · str | None | UndefinedType · default: "UNDEFINED"

Software version

hw_version · str | None | UndefinedType · default: "UNDEFINED"

Hardware version

configuration_url · str | URL | None | UndefinedType · default: "UNDEFINED"

URL for device configuration

entry_type · DeviceEntryType | None | UndefinedType · default: "UNDEFINED"

Device entry type (e.g., SERVICE)

via_device · tuple[str, str] | None | UndefinedType · default: "UNDEFINED"

Identifier of hub device

disabled_by · DeviceEntryDisabler | None | UndefinedType · default: "UNDEFINED"

What disabled the device (if creating)

return · DeviceEntry

Device entry (created or existing)

device = dev_reg.async_get_or_create(
    config_entry_id=entry.entry_id,
    connections={(dr.CONNECTION_NETWORK_MAC, "00:11:22:33:44:55")},
    identifiers={("hue", "bridge_id")},
    manufacturer="Philips",
    model="Hue Bridge",
    name="Hue Bridge",
    sw_version="1.50.0"
)

DeviceEntry

Frozen dataclass representing a device registry entry.

Properties

id · str

Unique device ID

config_entries · set[str]

Config entry IDs linked to this device

config_entries_subentries · dict[str, set[str | None]]

Subentries per config entry

connections · set[tuple[str, str]]

Device connections (normalized)

identifiers · set[tuple[str, str]]

Device identifiers

manufacturer · str | None

Device manufacturer

model · str | None

Device model

model_id · str | None

Device model ID

name · str | None

Device name

name_by_user · str | None

User-customized device name

sw_version · str | None

Software version

hw_version · str | None

Hardware version

serial_number · str | None

Device serial number

configuration_url · str | None

URL for device configuration

entry_type · DeviceEntryType | None

Type of device entry

disabled_by · DeviceEntryDisabler | None

What disabled the device (USER, INTEGRATION, CONFIG_ENTRY)

area_id · str | None

Area ID where device is located

labels · set[str]

Labels assigned to device

via_device_id · str | None

Device ID of hub device

primary_config_entry · str | None

Primary config entry ID

created_at · datetime

When device was created

modified_at · datetime

When device was last modified

Methods

disabled · bool

Whether the device is disabled

dict_repr · dict[str, Any]

Dictionary representation of the device

DeviceInfo TypedDict

Type definition for device information provided by integrations.

connections · set[tuple[str, str]]

Device connections (e.g., MAC addresses)

identifiers · set[tuple[str, str]]

Unique identifiers for the device

manufacturer · str | None

Manufacturer name

model · str | None

Model name

model_id · str | None

Model identifier

name · str | None

Device name

sw_version · str | None

Software/firmware version

hw_version · str | None

Hardware version

serial_number · str | None

Serial number

configuration_url · str | URL | None

URL to configure the device

suggested_area · str | None

Suggested area for the device

entry_type · DeviceEntryType | None

Type of entry (e.g., SERVICE)

via_device · tuple[str, str]

Device identifier of hub device

Connection Types

• CONNECTION_BLUETOOTH = "bluetooth" - Bluetooth connection
• CONNECTION_NETWORK_MAC = "mac" - MAC address connection
• CONNECTION_UPNP = "upnp" - UPnP connection
• CONNECTION_ZIGBEE = "zigbee" - Zigbee connection

Events

EVENT_DEVICE_REGISTRY_UPDATED

Fired when a device is created, updated, or removed.

from homeassistant.helpers.device_registry import EVENT_DEVICE_REGISTRY_UPDATED

@callback
def device_updated(event):
    action = event.data["action"]  # "create", "update", or "remove"
    device_id = event.data["device_id"]
    
hass.bus.async_listen(EVENT_DEVICE_REGISTRY_UPDATED, device_updated)

Helper Functions

format_mac

Format MAC address string for device registry entry.

mac · str · required

MAC address in any common format

return · str

Normalized MAC address (lowercase with colons)

from homeassistant.helpers.device_registry import format_mac

formatted = format_mac("00-11-22-33-44-55")
# Returns: "00:11:22:33:44:55"