Skip to content

Commit da6574c

Browse files
emontnemeryemontnemery
authored
Add blog post on deprecation of DeviceEntry.suggested_area (#2740)
1 parent 72c02f3 commit da6574c

File tree

2 files changed

+76
-1
lines changed

2 files changed

+76
-1
lines changed

‎blog/2025-08-01-suggested-area-removed-from-deviceentry.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
author: Erik Montnemery
3+
authorURL: https://github.com/emontnemery
4+
title: "The DeviceEntry.suggested_area attribute is deprecated and will be removed"
5+
---
6+
7+
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.
8+
9+
Note:
10+
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.
11+
12+
Use `DeviceEntry.area_id` to determine a device’s area in custom integrations. Don’t access `DeviceEntry.suggested_area`.
13+
14+
During the deprecation period, accessing `DeviceEntry.suggested_area` will log a warning.
15+
16+
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`.

‎docs/device_registry_index.md

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,6 @@ Although not currently available, we could consider offering an option to users
4242
| model | The model name of the device. |
4343
| model_id | The model identifier of the device. |
4444
| serial_number | The serial number of the device. Unlike a serial number in the `identifiers` set, this does not need to be unique. |
45-
| suggested_area | The suggested name for the area where the device is located. |
4645
| sw_version | The firmware version of the device. |
4746
| 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. |
4847

@@ -56,6 +55,31 @@ Entity device info is only read if the entity is loaded via a [config entry](con
5655
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).
5756

5857
```python
58+
# Definition of DeviceInfo TypedDict
59+
class DeviceInfo(TypedDict, total=False):
60+
"""Entity device information for device registry."""
61+
62+
configuration_url: str | URL | None
63+
connections: set[tuple[str, str]]
64+
created_at: str
65+
default_manufacturer: str
66+
default_model: str
67+
default_name: str
68+
entry_type: DeviceEntryType | None
69+
identifiers: set[tuple[str, str]]
70+
manufacturer: str | None
71+
model: str | None
72+
model_id: str | None
73+
modified_at: str
74+
name: str | None
75+
serial_number: str | None
76+
suggested_area: str | None
77+
sw_version: str | None
78+
hw_version: str | None
79+
translation_key: str | None
80+
translation_placeholders: Mapping[str, str] | None
81+
via_device: tuple[str, str]
82+
5983
# Inside a platform
6084
class HueLight(LightEntity):
6185
@property
@@ -82,6 +106,41 @@ Besides device properties, `device_info` can also include `default_manufacturer`
82106
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.
83107

84108
```python
109+
# Definition of DeviceRegistry.async_get_or_create:
110+
class DeviceRegistry(BaseRegistry[dict[str, list[dict[str, Any]]]]):
111+
...
112+
113+
@callback
114+
def async_get_or_create(
115+
self,
116+
*,
117+
config_entry_id: str,
118+
config_subentry_id: str | None | UndefinedType = UNDEFINED,
119+
configuration_url: str | URL | None | UndefinedType = UNDEFINED,
120+
connections: set[tuple[str, str]] | None | UndefinedType = UNDEFINED,
121+
created_at: str | datetime | UndefinedType = UNDEFINED, # will be ignored
122+
default_manufacturer: str | None | UndefinedType = UNDEFINED,
123+
default_model: str | None | UndefinedType = UNDEFINED,
124+
default_name: str | None | UndefinedType = UNDEFINED,
125+
# To disable a device if it gets created
126+
disabled_by: DeviceEntryDisabler | None | UndefinedType = UNDEFINED,
127+
entry_type: DeviceEntryType | None | UndefinedType = UNDEFINED,
128+
hw_version: str | None | UndefinedType = UNDEFINED,
129+
identifiers: set[tuple[str, str]] | None | UndefinedType = UNDEFINED,
130+
manufacturer: str | None | UndefinedType = UNDEFINED,
131+
model: str | None | UndefinedType = UNDEFINED,
132+
model_id: str | None | UndefinedType = UNDEFINED,
133+
modified_at: str | datetime | UndefinedType = UNDEFINED, # will be ignored
134+
name: str | None | UndefinedType = UNDEFINED,
135+
serial_number: str | None | UndefinedType = UNDEFINED,
136+
suggested_area: str | None | UndefinedType = UNDEFINED,
137+
sw_version: str | None | UndefinedType = UNDEFINED,
138+
translation_key: str | None = None,
139+
translation_placeholders: Mapping[str, str] | None = None,
140+
via_device: tuple[str, str] | None | UndefinedType = UNDEFINED,
141+
) -> DeviceEntry:
142+
...
143+
85144
# Inside a component
86145
from homeassistant.helpers import device_registry as dr
87146

0 commit comments

Comments
 (0)