jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-11-09 10:59:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add blog post on deprecation of DeviceEntry.suggested_area (#2740)

Browse Source
This commit is contained in:
Erik Montnemery
2025-08-19 13:22:45 +02:00
committed by GitHub
parent 72c02f345e
commit da6574c0f5
2 changed files with 76 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
blog/2025-08-01-suggested-area-removed-from-deviceentry.md Normal file
View File

@@ -0,0 +1,16 @@
---
author: Erik Montnemery
authorURL: https://github.com/emontnemery
title: "The DeviceEntry.suggested_area attribute is deprecated and will be removed"
---
The `DeviceEntry.suggested_area` attribute is deprecated and will be removed in HA Core 2026.9. Also, `suggested_area` will no longer be present in `EVENT_DEVICE_REGISTRY_UPDATED` events when HA Core 2026.9 is released.
Note:
Setting `suggested_area` in `DeviceInfo`, and passing `suggested_area` to `DeviceRegistry.async_get_or_create` is still supported and influences the area of created devices, although that may change in the future.
Use `DeviceEntry.area_id` to determine a device’s area in custom integrations. Don’t access `DeviceEntry.suggested_area`.
During the deprecation period, accessing `DeviceEntry.suggested_area` will log a warning.
For more details, refer to the [DeviceEntry documentation](/docs/device_registry_index#device-properties) and core [PR 149730](https://github.com/home-assistant/core/pull/149730) which deprecated `DeviceEntry.suggested_area`.

61
docs/device_registry_index.md
View File

@@ -42,7 +42,6 @@ Although not currently available, we could consider offering an option to users
| model | The model name of the device. |
| model_id | The model identifier of the device. |
| serial_number | The serial number of the device. Unlike a serial number in the `identifiers` set, this does not need to be unique. |
| suggested_area | The suggested name for the area where the device is located. |
| sw_version | The firmware version of the device. |
| via_device | Identifier of a device that routes messages between this device and Home Assistant. Examples of such devices are hubs, or parent devices of a sub-device. This is used to show device topology in Home Assistant. |
@@ -56,6 +55,31 @@ Entity device info is only read if the entity is loaded via a [config entry](con
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 or connections, like serial numbers or MAC addresses. If identifiers and connections are provided, the device registry will first try to match by identifiers. Each identifier and each connection is matched individually (e.g. only one connection needs to match to be considered the same device).
```python
# Definition of DeviceInfo TypedDict
class DeviceInfo(TypedDict, total=False):
"""Entity device information for device registry."""
configuration_url: str | URL | None
connections: set[tuple[str, str]]
created_at: str
default_manufacturer: str
default_model: str
default_name: str
entry_type: DeviceEntryType | None
identifiers: set[tuple[str, str]]
manufacturer: str | None
model: str | None
model_id: str | None
modified_at: str
name: str | None
serial_number: str | None
suggested_area: str | None
sw_version: str | None
hw_version: str | None
translation_key: str | None
translation_placeholders: Mapping[str, str] | None
via_device: tuple[str, str]
# Inside a platform
class HueLight(LightEntity):
@property
@@ -82,6 +106,41 @@ Besides device properties, `device_info` can also include `default_manufacturer`
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.
```python
# Definition of DeviceRegistry.async_get_or_create:
class DeviceRegistry(BaseRegistry[dict[str, list[dict[str, Any]]]]):
...
@callback
def async_get_or_create(
self,
*,
config_entry_id: str,
config_subentry_id: str | None | UndefinedType = UNDEFINED,
configuration_url: str | URL | None | UndefinedType = UNDEFINED,
connections: set[tuple[str, str]] | None | UndefinedType = UNDEFINED,
created_at: str | datetime | UndefinedType = UNDEFINED, # will be ignored
default_manufacturer: str | None | UndefinedType = UNDEFINED,
default_model: str | None | UndefinedType = UNDEFINED,
default_name: str | None | UndefinedType = UNDEFINED,
# To disable a device if it gets created
disabled_by: DeviceEntryDisabler | None | UndefinedType = UNDEFINED,
entry_type: DeviceEntryType | None | UndefinedType = UNDEFINED,
hw_version: str | None | UndefinedType = UNDEFINED,
identifiers: set[tuple[str, str]] | None | UndefinedType = UNDEFINED,
manufacturer: str | None | UndefinedType = UNDEFINED,
model: str | None | UndefinedType = UNDEFINED,
model_id: str | None | UndefinedType = UNDEFINED,
modified_at: str | datetime | UndefinedType = UNDEFINED, # will be ignored
name: str | None | UndefinedType = UNDEFINED,
serial_number: str | None | UndefinedType = UNDEFINED,
suggested_area: str | None | UndefinedType = UNDEFINED,
sw_version: str | None | UndefinedType = UNDEFINED,
translation_key: str | None = None,
translation_placeholders: Mapping[str, str] | None = None,
via_device: tuple[str, str] | None | UndefinedType = UNDEFINED,
) -> DeviceEntry:
...
# Inside a component
from homeassistant.helpers import device_registry as dr