Skip to main content
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"

Build docs developers (and LLMs) love

Get started for freeTalk to us