> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="device_id" type="str" required>
  Device ID to retrieve
</ParamField>

<ResponseField name="return" type="DeviceEntry | None">
  Device entry or None if not found
</ResponseField>

```python theme={null}
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.

<ParamField path="identifiers" type="set[tuple[str, str]] | None" default="None">
  Set of identifier tuples (domain, unique\_id)
</ParamField>

<ParamField path="connections" type="set[tuple[str, str]] | None" default="None">
  Set of connection tuples (connection\_type, connection\_id)
</ParamField>

<ResponseField name="return" type="DeviceEntry | None">
  Device entry or None if not found
</ResponseField>

```python theme={null}
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.

<ParamField path="config_entry_id" type="str" required>
  Config entry ID to link device to
</ParamField>

<ParamField path="config_subentry_id" type="str | None | UndefinedType" default="UNDEFINED">
  Config subentry ID
</ParamField>

<ParamField path="connections" type="set[tuple[str, str]] | None | UndefinedType" default="UNDEFINED">
  Device connections (e.g., MAC addresses)
</ParamField>

<ParamField path="identifiers" type="set[tuple[str, str]] | None | UndefinedType" default="UNDEFINED">
  Device identifiers
</ParamField>

<ParamField path="manufacturer" type="str | None | UndefinedType" default="UNDEFINED">
  Device manufacturer
</ParamField>

<ParamField path="model" type="str | None | UndefinedType" default="UNDEFINED">
  Device model
</ParamField>

<ParamField path="name" type="str | None | UndefinedType" default="UNDEFINED">
  Device name
</ParamField>

<ParamField path="sw_version" type="str | None | UndefinedType" default="UNDEFINED">
  Software version
</ParamField>

<ParamField path="hw_version" type="str | None | UndefinedType" default="UNDEFINED">
  Hardware version
</ParamField>

<ParamField path="configuration_url" type="str | URL | None | UndefinedType" default="UNDEFINED">
  URL for device configuration
</ParamField>

<ParamField path="entry_type" type="DeviceEntryType | None | UndefinedType" default="UNDEFINED">
  Device entry type (e.g., SERVICE)
</ParamField>

<ParamField path="via_device" type="tuple[str, str] | None | UndefinedType" default="UNDEFINED">
  Identifier of hub device
</ParamField>

<ParamField path="disabled_by" type="DeviceEntryDisabler | None | UndefinedType" default="UNDEFINED">
  What disabled the device (if creating)
</ParamField>

<ResponseField name="return" type="DeviceEntry">
  Device entry (created or existing)
</ResponseField>

```python theme={null}
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

<ParamField path="id" type="str">
  Unique device ID
</ParamField>

<ParamField path="config_entries" type="set[str]">
  Config entry IDs linked to this device
</ParamField>

<ParamField path="config_entries_subentries" type="dict[str, set[str | None]]">
  Subentries per config entry
</ParamField>

<ParamField path="connections" type="set[tuple[str, str]]">
  Device connections (normalized)
</ParamField>

<ParamField path="identifiers" type="set[tuple[str, str]]">
  Device identifiers
</ParamField>

<ParamField path="manufacturer" type="str | None">
  Device manufacturer
</ParamField>

<ParamField path="model" type="str | None">
  Device model
</ParamField>

<ParamField path="model_id" type="str | None">
  Device model ID
</ParamField>

<ParamField path="name" type="str | None">
  Device name
</ParamField>

<ParamField path="name_by_user" type="str | None">
  User-customized device name
</ParamField>

<ParamField path="sw_version" type="str | None">
  Software version
</ParamField>

<ParamField path="hw_version" type="str | None">
  Hardware version
</ParamField>

<ParamField path="serial_number" type="str | None">
  Device serial number
</ParamField>

<ParamField path="configuration_url" type="str | None">
  URL for device configuration
</ParamField>

<ParamField path="entry_type" type="DeviceEntryType | None">
  Type of device entry
</ParamField>

<ParamField path="disabled_by" type="DeviceEntryDisabler | None">
  What disabled the device (USER, INTEGRATION, CONFIG\_ENTRY)
</ParamField>

<ParamField path="area_id" type="str | None">
  Area ID where device is located
</ParamField>

<ParamField path="labels" type="set[str]">
  Labels assigned to device
</ParamField>

<ParamField path="via_device_id" type="str | None">
  Device ID of hub device
</ParamField>

<ParamField path="primary_config_entry" type="str | None">
  Primary config entry ID
</ParamField>

<ParamField path="created_at" type="datetime">
  When device was created
</ParamField>

<ParamField path="modified_at" type="datetime">
  When device was last modified
</ParamField>

### Methods

<ResponseField name="disabled" type="bool">
  Whether the device is disabled
</ResponseField>

<ResponseField name="dict_repr" type="dict[str, Any]">
  Dictionary representation of the device
</ResponseField>

## DeviceInfo TypedDict

Type definition for device information provided by integrations.

<ParamField path="connections" type="set[tuple[str, str]]">
  Device connections (e.g., MAC addresses)
</ParamField>

<ParamField path="identifiers" type="set[tuple[str, str]]">
  Unique identifiers for the device
</ParamField>

<ParamField path="manufacturer" type="str | None">
  Manufacturer name
</ParamField>

<ParamField path="model" type="str | None">
  Model name
</ParamField>

<ParamField path="model_id" type="str | None">
  Model identifier
</ParamField>

<ParamField path="name" type="str | None">
  Device name
</ParamField>

<ParamField path="sw_version" type="str | None">
  Software/firmware version
</ParamField>

<ParamField path="hw_version" type="str | None">
  Hardware version
</ParamField>

<ParamField path="serial_number" type="str | None">
  Serial number
</ParamField>

<ParamField path="configuration_url" type="str | URL | None">
  URL to configure the device
</ParamField>

<ParamField path="suggested_area" type="str | None">
  Suggested area for the device
</ParamField>

<ParamField path="entry_type" type="DeviceEntryType | None">
  Type of entry (e.g., SERVICE)
</ParamField>

<ParamField path="via_device" type="tuple[str, str]">
  Device identifier of hub device
</ParamField>

## 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.

```python theme={null}
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.

<ParamField path="mac" type="str" required>
  MAC address in any common format
</ParamField>

<ResponseField name="return" type="str">
  Normalized MAC address (lowercase with colons)
</ResponseField>

```python theme={null}
from homeassistant.helpers.device_registry import format_mac

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