From 740a98856cfdc2582eaef7cb3a9515a35c6e76c5 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 1 Aug 2025 09:03:02 +0200 Subject: [PATCH 1/5] Add blog post on deprecation of DeviceEntry.suggested_area --- ...08-01-suggested-area-removed-from-deviceentry.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 blog/2025-08-01-suggested-area-removed-from-deviceentry.md diff --git a/blog/2025-08-01-suggested-area-removed-from-deviceentry.md b/blog/2025-08-01-suggested-area-removed-from-deviceentry.md new file mode 100644 index 00000000000..03bb6fae05b --- /dev/null +++ b/blog/2025-08-01-suggested-area-removed-from-deviceentry.md @@ -0,0 +1,13 @@ +--- +author: Erik Montnemery +authorURL: https://github.com/emontnemery +title: "The DeviceEntry.suggested_area attribute has been deprecated and will be removed" +--- + +The `DeviceEntry.suggested_area` attribute has been 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. + +Custom integrations should not access `DeviceEntry.suggested_area`. If it's important to know which area a device is part of, use `DeviceEntry.area_id` instead. + +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`. From 24e95f98c61134024f6704f5a3825a406dfa0789 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 1 Aug 2025 09:03:59 +0200 Subject: [PATCH 2/5] Update deviceentry docs --- docs/device_registry_index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/device_registry_index.md b/docs/device_registry_index.md index 9e09f4054e4..da4020c1c14 100644 --- a/docs/device_registry_index.md +++ b/docs/device_registry_index.md @@ -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. | From 1b2cc74b43e4af1d9c3618ffd37301a3172bb0b8 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 1 Aug 2025 10:32:00 +0200 Subject: [PATCH 3/5] Adjust language --- ...2025-08-01-suggested-area-removed-from-deviceentry.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/blog/2025-08-01-suggested-area-removed-from-deviceentry.md b/blog/2025-08-01-suggested-area-removed-from-deviceentry.md index 03bb6fae05b..29139766140 100644 --- a/blog/2025-08-01-suggested-area-removed-from-deviceentry.md +++ b/blog/2025-08-01-suggested-area-removed-from-deviceentry.md @@ -1,12 +1,15 @@ --- author: Erik Montnemery authorURL: https://github.com/emontnemery -title: "The DeviceEntry.suggested_area attribute has been deprecated and will be removed" +title: "The DeviceEntry.suggested_area attribute is deprecated and will be removed" --- -The `DeviceEntry.suggested_area` attribute has been 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. +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. -Custom integrations should not access `DeviceEntry.suggested_area`. If it's important to know which area a device is part of, use `DeviceEntry.area_id` instead. +Note: +Setting `suggested_area` in `DeviceInfo`, and passing `suggested_area` to `DeviceRegistry.async_get_or_create` is still supported, 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. From 57e8d547bdec9553727196f2f207896b4f0ad2b1 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 1 Aug 2025 10:33:56 +0200 Subject: [PATCH 4/5] Adjust language --- blog/2025-08-01-suggested-area-removed-from-deviceentry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blog/2025-08-01-suggested-area-removed-from-deviceentry.md b/blog/2025-08-01-suggested-area-removed-from-deviceentry.md index 29139766140..9cddaa4fa0d 100644 --- a/blog/2025-08-01-suggested-area-removed-from-deviceentry.md +++ b/blog/2025-08-01-suggested-area-removed-from-deviceentry.md @@ -7,7 +7,7 @@ title: "The DeviceEntry.suggested_area attribute is deprecated and will be remov 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, although that may change in the future. +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`. From 57a70a9aafe405c65918dbfd7152fd3f579189dc Mon Sep 17 00:00:00 2001 From: Erik Date: Tue, 19 Aug 2025 09:28:16 +0200 Subject: [PATCH 5/5] Address review comment --- docs/device_registry_index.md | 60 +++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/docs/device_registry_index.md b/docs/device_registry_index.md index da4020c1c14..3630c9afb03 100644 --- a/docs/device_registry_index.md +++ b/docs/device_registry_index.md @@ -55,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 @@ -81,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