Since Home Assistant Core 2026.9, schema validation runs on Probatio instead of voluptuous. This went in quietly because it was meant to change nothing, and for most integrations it changed nothing. That is worth saying out loud anyway, along with what it does change and what you can now reach for.
\nProbatio is a clean-room reimplementation of voluptuous with the same public API. import voluptuous as vol still works: Home Assistant aliases the name in sys.modules at startup, so the import resolves to Probatio. Custom integrations need no changes, and voluptuous is no longer installed at all.
Core itself has moved to importing Probatio directly, and import voluptuous is now banned there by a lint rule. That ban applies to our own source. Your integration can keep the old import for as long as you like.
voluptuous has been effectively unmaintained for a long time, and it sits under every integration in Home Assistant. Probatio is maintained, MIT licensed, pure Python, and holds behavioral compatibility with voluptuous as its primary correctness target.
\nIt is also quicker. The project measures the interpreted engine at roughly 2.3 to 3.4 times voluptuous, and an optional compiled path at roughly 6.7 to 7.4 times, on its own benchmarks. Those are single-machine numbers and the project says not to treat them as guarantees, so take them as a direction rather than a promise. Home Assistant builds a great many schemas and validates a fraction of them per run, so we set a lazy build policy: a schema compiles when it is first validated, not when it is constructed.
\nTwo things are worth knowing, because both produced real issues after 2026.9.
\nError messages are worded differently. If your tests assert on validation error text, they may need updating. Probatio also suggests a close match for an unknown key, and 2026.9.1 raised the bar for when it offers one, so weak guesses no longer appear.
\nValidation is stricter in a few places, which surfaced data that was quietly wrong before. The clearest case was the KNX config store, which was validated before writing but not on load. Entries written by hand or by third-party tooling had been passed through untouched for years, and started failing at setup. The data was always invalid. Nothing told anyone until something checked.
\nIf your integration stores structured data and only validates it on the way in, this is worth a look.
\nThe compatibility layer only exposes voluptuous's surface, so reaching any of this means importing probatio directly.
Typing that survives the call. Validators that hand their input back keep the caller's type, so probatio.EnsureList()(names) on a list[str] gives you a list[str] rather than a list[Any].
Dataclass and TypedDict schemas. Build schemas from annotations. DataclassSchema returns a typed dataclass instance, while TypedDictSchema returns a validated dict typed as the TypedDict:
from dataclasses import dataclass
import probatio
@dataclass
class Server:
host: str
port: int = 80
schema = probatio.DataclassSchema(Server)
schema({\"host\": \"nas\", \"port\": 8080}) # Server(host=\"nas\", port=8080)
Markers voluptuous never had. Secret redacts a key's value from error output, which matters when a schema holds a password. Forbidden requires a key's absence, Alias accepts a value under an old name and emits it under the canonical one, and TaggedUnion routes on one key's value instead of trying every branch and reporting all of them.
probatio.Schema(
{
probatio.Required(probatio.Secret(CONF_PASSWORD)): str,
}
)
Structured errors, including translation keys. Every Invalid carries a stable code, a translation_key, placeholders for interpolation, the path to the offending value, and a secret flag. as_dict() serializes the lot. That means a validation failure can be branched on programmatically and rendered in the user's language, rather than parsed out of an English sentence.
{
\"code\": \"length\",
\"message\": \"length of value must be at least 12\",
\"path\": [\"password\"],
\"secret\": True,
\"context\": {},
\"translation_key\": \"length_min\",
\"placeholders\": {\"min\": 12},
}
Cross-field rules, like AtLeastOne, ExactlyOne, AllOrNone, RequiredWith and RequiredIf, which previously had to be hand-rolled per integration.
Codecs. to_json_schema, to_openapi and from_openapi convert between a schema and a document, which is how we describe LLM tools.
The full documentation lives at probatio.frenck.dev, including a compatibility matrix listing everything Probatio adds beyond voluptuous.
\nThe site also publishes llms.txt, a machine-readable index of the documentation. If you use an AI assistant while working on an integration, pointing it at that file is worth doing. Probatio is newer than most model training data, so an assistant left to its own devices will write voluptuous, guess at the API, or invent a validator that does not exist. There are abridged and complete variants alongside it, plus separate indexes for the guides, the recipes and the API reference.
", "url": "https://developers.home-assistant.io/blog/2026/09/30/probatio-validation-engine", "title": "Probatio is our validation engine", "summary": "Since Home Assistant Core 2026.9, schema validation runs on Probatio instead of voluptuous. This went in quietly because it was meant to change nothing, and for most integrations it changed nothing. That is worth saying out loud anyway, along with what it does change and what you can now reach for.", "date_modified": "2026-09-30T00:00:00.000Z", "author": { "name": "Franck Nijhof", "url": "https://twitter.com/frenck" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/09/28/central-config-flow-abort-reasons", "content_html": "As of Home Assistant Core 2026.10, the homeassistant integration can translate abort reasons that every integration words the same way. If you're today linking from a local translation key, for an abort reason, to a shared translation key under the homeassistant integration, you can instead just rely on the shared translation key under the homeassistant domain directly. This is done by default in some helpers and can also be done explicitly by setting the translation_domain parameter when aborting the flow.
abort sections of strings.json, including those under config_subentries, only when the abort uses the homeassistant translation domain.async_abort or AbortFlow, pass the homeassistant translation domain before deleting the local key. Without that domain, retain the local key. See Raise one yourself.When an abort uses the central translation domain, the frontend resolves the reason from that domain and does not use a local key.
\n| Reason | Raised by |
|---|---|
already_in_progress | async_set_unique_id, discovery without a unique ID |
single_instance_allowed | single_config_entry, DiscoveryFlowHandler, WebhookFlowHandler |
no_devices_found | DiscoveryFlowHandler |
cloud_not_connected | WebhookFlowHandler |
reauth_successful | async_update_reload_and_abort, async_update_and_abort |
reconfigure_successful | async_update_reload_and_abort, async_update_and_abort, also for subentries |
authorize_url_timeout | AbstractOAuth2FlowHandler |
missing_credentials | AbstractOAuth2FlowHandler |
no_url_available | AbstractOAuth2FlowHandler |
oauth_error | AbstractOAuth2FlowHandler |
oauth_failed | AbstractOAuth2FlowHandler |
oauth_implementation_unavailable | AbstractOAuth2FlowHandler |
oauth_timeout | AbstractOAuth2FlowHandler |
oauth_unauthorized | AbstractOAuth2FlowHandler |
user_rejected_authorize | AbstractOAuth2FlowHandler |
Pass the domain that owns the string. Both async_abort and AbortFlow accept it.
from homeassistant.core import DOMAIN as HOMEASSISTANT_DOMAIN
return self.async_abort(
reason=\"no_devices_found\",
translation_domain=HOMEASSISTANT_DOMAIN,
)
This works in config flows and subentry flows. Options flows look in the options section, which the homeassistant integration does not have.
Only needed if you word a reason differently on purpose:
\nreason to async_update_reload_and_abort or async_update_and_abort, even with the default name.translation_domain=DOMAIN.Aborts that core raises by itself, like already_in_progress, always use the central string, to keep a customized string there, overwrite the steps that produce the strings upstream.
As of Home Assistant Core 2026.10, an LLM tool returns an llm.ToolResult instead of a plain JSON object. ToolResult carries the tool's data and an error flag that says whether the call failed. On the chat log side, ToolResultContent.tool_result is replaced by ToolResultContent.result, which holds the ToolResult.
Returning a plain JSON object from a tool, reading ToolResultContent.tool_result, and setting tool_result on a tool result delta are deprecated. They keep working for custom integrations with a warning in the log until Home Assistant Core 2027.11, and stop working after that.
The release also adds metadata to llm.Tool. A tool now has a title for people to read, annotations that describe how it behaves, and an integration that records which integration provides it. The MCP Server integration serves the title and the annotations to MCP clients.
The annotations are an llm.ToolAnnotations with four flags: read_only, destructive, idempotent and open_world. The defaults describe the least safe case, so a tool that declares nothing is taken to write, to be destructive, and to reach outside Home Assistant.
Creating a tool without an integration is deprecated. A core integration raises an error. A custom integration gets a warning in the log until Home Assistant Core 2027.10, and stops working after that.
Both changes together look like this:
\nfrom homeassistant.core import HomeAssistant
from homeassistant.helpers import llm
from .const import DOMAIN
class GetItemsTool(llm.Tool):
\"\"\"Tool to read the items on a list.\"\"\"
name = \"my_integration__get_items\"
title = \"Get list items\"
description = \"Read the items on a list.\"
integration = DOMAIN
annotations = llm.ToolAnnotations(
read_only=True, destructive=False, idempotent=True, open_world=False
)
async def async_call(
self,
hass: HomeAssistant,
tool_input: llm.ToolInput,
llm_context: llm.LLMContext,
) -> llm.ToolResult:
\"\"\"Call the tool.\"\"\"
return llm.ToolResult(data={\"items\": [\"Milk\", \"Bread\"]})
Integration migration async_migrate_entry method can now raise config entry exceptions instead of only being limited to return False. This is preferred to provide more context and being translatable.
Integrations that fetch data from other services during migration can raise ConfigEntryNotReady to have the migration retried automatically later (as during setup), which helps with timeouts and other errors that may resolve on their own.
By returning False or raising any other exception than ConfigEntryNotReady the migration stops and the config entry state is set to migration_error which is a non-recoverable state.\nThis previously required the user to restart Home Assistant to retry the migration.\nThe new correct way to handle it is to create a repair issue. After the user fixes the issue, call hass.config_entries.async_retry_migration(entry_id) to retry the migration.
More info in the config flow documentation.
\nThe migration function lives in the integration's __init__.py.
from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
async def async_migrate_entry(hass, config_entry: ConfigEntry):
\"\"\"Migrate old entry.\"\"\"
_LOGGER.debug(\"Migrating configuration from version %s.%s\",
config_entry.version, config_entry.minor_version
)
if config_entry.version == 1:
try:
new_info = await client.get_info()
except ConnectionError as exc:
raise ConfigEntryNotReady(
translation_key=\"key\",
translation_domain=DOMAIN,
) from exc
except AuthenticationError as exc:
async_create_issue(
hass,
DOMAIN,
f\"migrate_could_not_auth_{config_entry.entry_id}\",
is_fixable=True,
is_persistent=False,
severity=IssueSeverity.ERROR,
translation_key=\"migrate_could_not_auth\",
translation_placeholders={\"title\": config_entry.title},
data={\"entry_id\": config_entry.entry_id},
)
raise ConfigEntryError(translation_key=\"migrate_could_not_auth\") from exc
new_data = {**config_entry.data, \"some_data\": new_info[\"some_data\"]}
hass.config_entries.async_update_entry(
config_entry, data=new_data, version=2
)
_LOGGER.debug(\"Migration to configuration version %s.%s successful\",
config_entry.version, config_entry.minor_version,
)
return True
The repair flow lives in the integration's repairs.py.
class MigrationRepairFlow(RepairsFlow):
\"\"\"Handler for a migration repair flow.\"\"\"
def __init__(self, entry_id: str) -> None:
\"\"\"Initialize the flow.\"\"\"
self.entry_id = entry_id
async def async_step_init(
self, user_input: dict[str, Any] | None = None
) -> RepairsFlowResult:
\"\"\"Fix the issue and retry the migration.\"\"\"
if user_input is not None:
# TODO: Do whatever is necessary to fix the issue,
# for example update the config entry data
await self.hass.config_entries.async_retry_migration(self.entry_id)
return self.async_create_entry(data={})
return self.async_show_form(
step_id=\"init\",
data_schema=probatio.Schema({}),
)
async def async_create_fix_flow(
hass: HomeAssistant,
issue_id: str,
data: dict[str, str | int | float | None] | None,
) -> RepairsFlow:
\"\"\"Create flow.\"\"\"
if issue_id.startswith(\"migrate_could_not_auth_\"):
return MigrationRepairFlow(data[\"entry_id\"])
The device registry's multi-config-entry compatibility properties — DeviceEntry.config_entries, DeviceEntry.config_entries_subentries and DeviceEntry.primary_config_entry — were announced as deprecated in Devices are restricted to a single config entry and at most one subentry, but reading them was still silent. They now report at runtime: core and core integrations raise RuntimeError, custom integrations log a warning.
Use DeviceEntry.config_entry_id and DeviceEntry.config_subentry_id instead. The properties remain available to custom integrations until Home Assistant Core 2027.10, two releases later than the 2027.8 given in the earlier post.
Reading the properties on a synthesized composite device is not deprecated and does not report, because such a device really does span several config entries.
\nMost integrations don't read these properties and don't need any changes. Read on if your integration inspects a device's config entries, or accesses them on a deleted or child device.
\nThis is implemented in core PR #181949 and lands in Home Assistant Core 2026.10.
\n| Deprecated | Replacement |
|---|---|
DeviceEntry.config_entries | DeviceEntry.config_entry_id |
DeviceEntry.config_entries_subentries | DeviceEntry.config_entry_id and DeviceEntry.config_subentry_id |
DeviceEntry.primary_config_entry | DeviceEntry.config_entry_id |
As with the other device registry deprecations, the enforcement is stricter inside core: a core or core integration caller raises RuntimeError immediately, while a custom integration keeps working with a logged warning until Home Assistant Core 2027.10.
A device belongs to exactly one config entry and at most one config subentry, so each of the shims collapses to a plain attribute read:
\n# Before
entry_id = device.primary_config_entry
# After
entry_id = device.config_entry_id
# Before
if config_entry.entry_id in device.config_entries:
...
# After
if device.config_entry_id == config_entry.entry_id:
...
# Before
for entry_id, subentry_ids in device.config_entries_subentries.items():
for subentry_id in subentry_ids:
...
# After
entry_id = device.config_entry_id
subentry_id = device.config_subentry_id
If you loop over a device's config entries to find the one belonging to your integration, use the async_get_device_and_config_entry_for_domain() helper introduced in More device registry deprecations, new helpers and validation instead:
device, config_entry = dr.async_get_device_and_config_entry_for_domain(
hass, device_id, domain=DOMAIN
)
Core's own test suite was migrated off the properties in core PR #181945, which can serve as a set of examples.
\nThe properties are not deprecated for a synthesized composite device — the read-only device DeviceRegistry.async_get() returns for a pre-migration composite device id, as described in Backwards compatibility. Such a device spans several config entries, which config_entry_id and config_subentry_id can't represent, so the three properties are the correct API for it and reading them does not report, for any caller.
The exemption is keyed on DeviceEntry.is_composite_device, which code handling both kinds of device can branch on. Core's device_automation integration is a genuine example: the device ids passed to async_get_device_automations() come from automations, scripts and the frontend, so they can still be pre-migration composite ids, and listing a device's automations needs the domain of every config entry owning it:
# homeassistant/components/device_automation/__init__.py
if (device := device_registry.async_get(device_id)) is None:
raise DeviceNotFound
if device.is_composite_device:
entry_ids = device.config_entries
else:
entry_ids = {device.config_entry_id}
for entry_id in entry_ids:
if config_entry := hass.config_entries.async_get_entry(entry_id):
domain_devices.setdefault(config_entry.domain, set()).add(device_id)
Note that this is only needed for code which deliberately accepts a stored device id that may predate the migration. Code that only ever handles devices it registered itself should read config_entry_id unconditionally.
DeletedDeviceEntry.config_entries and DeletedDeviceEntry.config_entries_subentries are deprecated and report on the same terms. A deleted device is never a composite, so there is no exemption — every read reports.
Use DeletedDeviceEntry.config_entry_id and DeletedDeviceEntry.config_subentry_id. Both are None for an orphaned deleted device, that is, one whose owning config entry has been removed; the deprecated properties represented that case as an empty set and an empty dict.
ChildDeviceEntry inherits the three properties, and a child device is never a composite either, so reading them on a child device always reports. A child device belongs to the same config entry and subentry as its parent, both available as config_entry_id and config_subentry_id.
This change only concerns the Python properties. A regular device is serialized as before — config/device_registry/list, the EVENT_DEVICE_REGISTRY_UPDATED payload and the device registry storage still carry the config_entries, config_entries_subentries and primary_config_entry fields, computed internally without reporting — so WebSocket clients are not affected and see no new warnings. Child devices never carried these fields in the first place.
Those fields are deprecated on their own schedule, described in Device registry WebSocket API changes.
", "url": "https://developers.home-assistant.io/blog/2026/09/15/device-entry-config-entries-deprecation", "title": "`DeviceEntry.config_entries` deprecation is now enforced", "summary": "Summary", "date_modified": "2026-09-15T00:00:00.000Z", "author": { "name": "Erik Montnemery", "url": "https://github.com/emontnemery" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/09/11/lawn-mower-stop-action-idle-activity", "content_html": "As of Home Assistant Core 2026.10, LawnMowerEntity supports a stop action and an IDLE activity.
stop cancels the current mowing task without returning the mower to the dock. It differs from pause, which keeps the task so it can be resumed, and from dock, which sends the mower home. To support it, add LawnMowerEntityFeature.STOP to the supported features and implement stop or async_stop.
LawnMowerActivity.IDLE describes a mower that is stopped, but neither docked nor paused. Integrations that mapped such a state to PAUSED or ERROR should now use IDLE.
More details can be found in the documentation.
\nclass MyLawnMower(LawnMowerEntity):
_attr_supported_features = (
LawnMowerEntityFeature.START_MOWING
| LawnMowerEntityFeature.DOCK
| LawnMowerEntityFeature.STOP
)
async def async_stop(self) -> None:
\"\"\"Stop the mower and cancel the current task.\"\"\"
await self.mower.stop()
self._attr_activity = LawnMowerActivity.IDLE
self.async_write_ha_state()
As of Home Assistant Core 2026.10, the OAuth2 helper raises exceptions that config entry setup already understands, so integrations no longer translate OAuth2 failures themselves.
\nThe OAuth2 exceptions now inherit from the config entry exception that describes what should happen, and carry a translated message from the homeassistant integration.
| Exception | Also a | Result when uncaught |
|---|---|---|
ImplementationUnavailableError | ConfigEntryNotReady | Setup is retried |
UnknownImplementationError | ConfigEntryAuthFailed | Reauth flow starts |
OAuth2TokenRequestError | ConfigEntryNotReady | Setup is retried |
OAuth2TokenRequestTransientError | ConfigEntryNotReady | Setup is retried |
OAuth2TokenRequestConnectionError | ConfigEntryNotReady | Setup is retried |
OAuth2TokenRequestReauthError | ConfigEntryAuthFailed | Reauth flow starts |
All of them are importable from homeassistant.exceptions and carry a translated user-facing message, so the integration does not need a strings.json entry for them.
- try:
- implementation = await async_get_config_entry_implementation(hass, entry)
- except ImplementationUnavailableError as err:
- raise ConfigEntryNotReady(
- translation_domain=DOMAIN,
- translation_key=\"oauth2_implementation_unavailable\",
- ) from err
+ implementation = await async_get_config_entry_implementation(hass, entry)
Also remove the now-unused oauth2_implementation_unavailable entry from the exceptions section of strings.json.
Catching ValueError around this call can go as well. UnknownImplementationError subclasses ValueError for backwards compatibility, so a ValueError handler silently downgrades it and discards the translated message.
- try:
- await auth.async_get_access_token()
- except OAuth2TokenRequestReauthError as err:
- raise ConfigEntryAuthFailed from err
- except OAuth2TokenRequestError as err:
- raise ConfigEntryNotReady from err
+ await auth.async_get_access_token()
The same applies to await session.async_ensure_token_valid().
The test-before-setup rule accepts await session.async_ensure_token_valid() in async_setup_entry as satisfying the rule, alongside await coordinator.async_config_entry_first_refresh(). Both raise the appropriate config entry exception on the integration's behalf.
Central handling is a default, not a restriction. Keep an explicit handler when the integration genuinely needs different behavior, for example:
\nConfigEntryError instead of retrying.In those cases, catch the most specific exception that applies and let the rest propagate.
", "url": "https://developers.home-assistant.io/blog/2026/09/07/oauth2-central-error-handling", "title": "OAuth2 error handling moved into the helper", "summary": "As of Home Assistant Core 2026.10, the OAuth2 helper raises exceptions that config entry setup already understands, so integrations no longer translate OAuth2 failures themselves.", "date_modified": "2026-09-07T00:00:00.000Z", "author": { "name": "Josef Zweck", "url": "https://github.com/zweckj" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/09/04/device-and-state-class-selectors", "content_html": "New selectors are available to choose a device class or sensor state class.
\nThese selectors can be used in config flows and blueprints when requesting a device or state class from the user.
\nThe new DeviceClassSelector is available for selecting device classes in config flows and blueprints. It supports device classes for the following platforms:
Platform.BINARY_SENSOR: BinarySensorDeviceClass
Platform.BUTTON: ButtonDeviceClass
Platform.COVER: CoverDeviceClass
Platform.EVENT: EventDeviceClass
Platform.HUMIDIFIER: HumidifierDeviceClass
Platform.INFRARED: InfraredDeviceClass
Platform.MEDIA_PLAYER: MediaPlayerDeviceClass
Platform.NUMBER: NumberDeviceClass
Platform.SENSOR: SensorDeviceClass
Platform.SWITCH: SwitchDeviceClass
Platform.UPDATE: UpdateDeviceClass
Platform.VALVE: ValveDeviceClass
Example of a device class selector that returns a single device class:
\nvol.Schema(
{
vol.Optional(CONF_DEVICE_CLASS): DeviceClassSelector(
DeviceClassSelectorConfig(domain=Platform.SENSOR)
),
}
)
Example of a device class selector that returns multiple device classes as a list:
\nvol.Schema(
{
vol.Optional(CONF_DEVICE_CLASS): DeviceClassSelector(
DeviceClassSelectorConfig(
domain=Platform.BINARY_SENSOR,
multiple=True,
)
),
}
)
The new StateClassSelector is available for selecting sensor state classes in config flows and blueprints.
Example of a sensor state class selector that returns a single state class:
\nvol.Schema(
{
vol.Optional(CONF_STATE_CLASS): StateClassSelector(),
}
)
Example of a sensor state class selector that returns a single state class with only a filtered subset of available state classes:
\nvol.Schema(
{
vol.Optional(CONF_STATE_CLASS): StateClassSelector(
StateClassSelectorConfig(
state_classes=[
SensorStateClass.MEASUREMENT,
SensorStateClass.TOTAL_INCREASING,
],
)
),
}
)
Example of a state class selector that returns multiple state classes as a list:
\nvol.Schema(
{
vol.Optional(CONF_STATE_CLASS): StateClassSelector(
StateClassSelectorConfig(multiple=True),
),
}
)
Unlike using a generic SelectSelector, the DeviceClassSelector allows the frontend to automatically translate device classes into user-friendly names.
Existing implementations that select a device or state class using SelectSelector should be migrated to use DeviceClassSelector or StateClassSelector. After migration, any stale translations related to the old selector values should be removed.
The Selectors documentation has been updated to include the new selectors.
", "url": "https://developers.home-assistant.io/blog/2026/09/04/device-and-state-class-selectors", "title": "New device and state class selectors", "summary": "New selectors are available to choose a device class or sensor state class.", "date_modified": "2026-09-04T00:00:00.000Z", "author": { "name": "Jan Bouwhuis", "url": "https://github.com/jbouwh" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/09/02/modbus-get-hub-deprecation", "content_html": "As of Home Assistant Core 2026.10, modbus.get_hub is deprecated. It will be removed in Home Assistant Core 2027.10. Custom integrations that call it get a warning in the log until then, and stop working after that.
get_hub attaches an integration to a Modbus hub the user configured in YAML, under a name the integration has to be told. The user has to set up the hub by hand before the integration can work, and two integrations that need the same bus cannot share it.
In July we announced our plan to modernize Modbus in Home Assistant. Home Assistant Core 2026.9 delivered the first piece: async_get_unit. An integration collects the connection details in its own config flow, the same as any other integration, and asks the Modbus integration for a unit on them. Integrations that ask with equal details share one connection. Nothing is configured in YAML and nothing extra is persisted.
Replace the call to get_hub with a call to async_get_unit:
from homeassistant.components.modbus import async_get_unit
from modbus_connection import ModbusTcpParams
async def async_setup_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
\"\"\"Set up my device from a config entry.\"\"\"
unit = async_get_unit(
hass,
entry,
ModbusTcpParams(host=entry.data[CONF_HOST], port=entry.data[CONF_PORT]),
entry.data[CONF_UNIT_ID],
)
device = MyDevice(unit)
...
This is not a one-to-one swap. Your config flow has to collect the connection details required by the transport, for example host and port, besides unit ID, that the user used to write in the YAML hub, and the device-specific communication should move into a library built on modbus-connection. The Modbus developer documentation describes both, with example code and a reference device library.
More details can be found in the core PR.
", "url": "https://developers.home-assistant.io/blog/2026/09/02/modbus-get-hub-deprecation", "title": "Deprecating modbus.get_hub in favor of async_get_unit", "summary": "As of Home Assistant Core 2026.10, modbus.get_hub is deprecated. It will be removed in Home Assistant Core 2027.10. Custom integrations that call it get a warning in the log until then, and stop working after that.", "date_modified": "2026-09-02T00:00:00.000Z", "author": { "name": "Paulus Schoutsen", "url": "https://github.com/balloob" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/08/31/deprecate-configurator", "content_html": "The Configurator integration has been deprecated and will be removed in Home Assistant 2027.10. The integration was originally created to provide a web-based configuration interface for Home Assistant, but it is no longer recommended for use. No core integrations use the Configurator integration anymore, and it is not recommended for custom integrations either.
\nThe modern way to configure integrations in Home Assistant is via config flows and config entries. Config flows provide a user-friendly interface for setting up and configuring integrations, while config entries allow for easy management of integration settings.
", "url": "https://developers.home-assistant.io/blog/2026/08/31/deprecate-configurator", "title": "Configurator integration is now deprecated", "summary": "The Configurator integration has been deprecated and will be removed in Home Assistant 2027.10. The integration was originally created to provide a web-based configuration interface for Home Assistant, but it is no longer recommended for use. No core integrations use the Configurator integration anymore, and it is not recommended for custom integrations either.", "date_modified": "2026-08-31T00:00:00.000Z", "author": { "name": "Martin Hjelmare", "url": "https://github.com/MartinHjelmare" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/08/24/device-registry-follow-up-changes", "content_html": "This is a follow-up to Devices are restricted to a single config entry and at most one subentry, and covers additional device registry deprecations, a few new helper methods, and some stricter validation that landed after that post.
\nMost custom integrations won't be affected by this set of changes. Read on if your integration sets via_device or default_manufacturer / default_model / default_name in DeviceInfo, looks devices up in the registry, reads the registry's devices, deleted_devices or child_devices containers, calls async_update_device directly, or attaches a device to an entity that has no config entry or unique id.
Unless noted otherwise, deprecated functionality logs a warning at runtime and remains supported until Home Assistant Core 2027.8. As before, deprecations which are only relevant to core and core integrations are enforced more strictly there: those callers raise immediately, while custom integrations keep getting a warning until the removal version.
\nvia_device follow-upsThe previous post deprecated DeviceInfo[\"via_device\"] and DeviceRegistry.async_get_or_create(via_device=...) in favor of via_device_id, because identifiers are only unique per config entry and no longer point at a single device. A few related changes build on that.
async_get_device_id_by_identifier()To set via_device_id you need the device id of the via device. The new helper homeassistant.helpers.device_registry.async_get_device_id_by_identifier() looks it up, scoped to the config entry that owns the via device:
@callback
def async_get_device_id_by_identifier(
hass: HomeAssistant, identifier: tuple[str, str], *, config_entry_id: str
) -> str:
via_device_id=dr.async_get_device_id_by_identifier(
hass, (DOMAIN, hub_serial_number), config_entry_id=entry.entry_id
)
The lookup is unambiguous because identifiers are unique within a config entry. It raises ValueError if no matching device exists, so only call it once the via device has been created. When your integration creates the via device itself, skip the lookup and read .id from the DeviceEntry that async_get_or_create returned for it.
This helper was added in core PR #177494, which also migrated a number of integrations from via_device to via_device_id as examples.
via_device removed from the DeviceInfo type, and ATTR_VIA_DEVICE deprecatedTwo typing-level follow-ups from core PR #178465:
\nvia_device has been removed from the DeviceInfo TypedDict. A DeviceInfo literal that still sets via_device is now a typing error; use via_device_id.homeassistant.const.ATTR_VIA_DEVICE is deprecated. Importing it logs a warning; use the string \"via_device_id\" instead. It is removed in Home Assistant Core 2027.8.The same PR also escalates the enforcement of the deprecations announced in the previous post — DeviceRegistry.async_get_device(), passing via_device to async_get_or_create(), and the add_config_entry_id / add_config_subentry_id / remove_config_entry_id / remove_config_subentry_id parameters of async_update_device(). Core and core integrations now raise RuntimeError when calling these, while custom integrations continue to log a warning until Home Assistant Core 2027.8.
A device may no longer set itself as its own via device (core PR #178194):
\nvia_device_id equal to the device's own id to async_get_or_create() or async_update_device() raises HomeAssistantError.via_device referencing the device itself is ignored and logged now, and will raise from Home Assistant Core 2027.8.The device registry storage is bumped to version 3.3 (introduced in Home Assistant Core 2026.8), which clears any existing via_device_id self-references on load. Integrations which previously worked around this by clearing the self-reference themselves can drop that code.
async_update_device(): merge_connections and merge_identifiers deprecatedPassing merge_connections or merge_identifiers to DeviceRegistry.async_update_device() is deprecated in core PR #178888. These parameters only add to the device's existing connections or identifiers; compute the full desired set yourself and pass it as new_connections or new_identifiers instead.
Core and core integrations raise RuntimeError when passing the merge parameters; custom integrations log a warning until Home Assistant Core 2027.9 (note this removal is one release later than the others).
async_get_device_and_config_entry_for_domain()A common pattern was to fetch a device and loop over its config_entries to find the config entry belonging to a given integration. Since DeviceEntry.config_entries is deprecated, core PR #178991 adds a helper that does this directly:
@callback
def async_get_device_and_config_entry_for_domain(
hass: HomeAssistant, device_id: str, *, domain: str
) -> tuple[DeviceEntry | None, ConfigEntry | None]:
device, config_entry = dr.async_get_device_and_config_entry_for_domain(
hass, device_id, domain=DOMAIN
)
It returns (None, None) for an unknown or child-device id, and (device, None) when a main device exists but no config entry of domain owns it. For a pre-migration composite id it returns a matching split device and its config entry, or the restored composite device and None when no split matches. The helper does not check whether the config entry is loaded, so keep your own ConfigEntryState.LOADED check if you need one.
devices, deleted_devices and child_devices containers are protectedThe DeviceRegistry.devices, DeviceRegistry.deleted_devices and DeviceRegistry.child_devices attributes used to be dictionaries keyed by device id, and integrations sometimes read them directly — registry.devices.get(device_id), registry.devices.values(), or device_id in registry.devices. The backing containers are now protected, and the public attributes are narrowed to what an integration legitimately needs.
devices (core PR #179578) is now a read-only collection of the registered devices. Iterating it yields the DeviceEntry values directly, and len() and value membership (device_entry in registry.devices) work as expected. Using it as a mapping — subscription, .get(), .values(), .keys(), or membership by device id (device_id in registry.devices) — is deprecated. The mapping surface keeps working as a backwards compatibility shim: core and core integrations raise RuntimeError, while custom integrations only log a warning. It is removed in Home Assistant Core 2027.9.
In practice, iterate with for device in registry.devices instead of registry.devices.values(), and look a device up by id with registry.async_get(device_id) instead of registry.devices.get(device_id).
child_devices (core PR #179713) is now a read-only collection of the child devices. It follows the container protocol — you can iterate it (it yields the child device entries), take its len(), and test value membership — and offers no dictionary-style access at all: there is no .get() or .values() and no lookup by device id. There is no backwards compatibility shim.
deleted_devices (core PR #179720) is an internal implementation detail of the device registry, and the whole attribute is now deprecated — there is no supported public use. Accessing it in any way is deprecated: core and core integrations raise RuntimeError, while custom integrations only log a warning. It is removed in Home Assistant Core 2027.9.
With direct container access going away, DeviceRegistry.async_get gains an include_composite_devices parameter to test what an id refers to (core PR #179594). With include_composite_devices=False, a pre-migration composite device id resolves to None:
is_composite = (
registry.async_get(device_id) is not None
and registry.async_get(device_id, include_composite_devices=False) is None
)
This complements the existing include_child_devices and include_main_devices parameters, which similarly resolve — or exclude — child and main devices. DeviceRegistry.async_is_composite_device_id, introduced in the previous post, is now redundant and deprecated in the same PR; use async_get with include_composite_devices=False instead. It keeps working — core and core integrations raise RuntimeError, while custom integrations only log a warning — until Home Assistant Core 2027.9.
An entity may only attach a device if it has a unique id and belongs to a config entry. Attempting to attach a device from an entity without a config entry, or without a unique id, is now caught in entity_platform (core PR #177459): the device link is dropped and a warning is logged. This is only a warning for now, and will raise from Home Assistant Core 2027.8.
Note that the device link is already dropped today, even though the raise only lands in 2027.8 — an affected entity ends up with no device until it is given a unique id and a config entry.
\nThe device registry used to classify each DeviceInfo as one of a fixed set of \"device info types\" (link, primary, secondary) based on which keys it contained. This existed to guess the primary integration for a device shared across several config entries, which is obsolete now that a device is owned by a single config entry. The classification is removed and replaced by lighter validation in core PR #179397, with the following developer-visible consequences:
DeviceInfo shapes that previously didn't match any type are now accepted. The old error \"device info needs to either describe a device, link to existing device or provide extra information\" is gone; a DeviceInfo still needs at least one of identifiers or connections.default_ counterpart — for example both name and default_name, or model and default_model — now raises DeviceInfoError.default_manufacturer, default_model and default_name are deprecatedThe default_manufacturer, default_model and default_name members of DeviceInfo are deprecated in core PR #179549. Pass the plain manufacturer, model and name fields instead.
These default_ fields let an integration that wasn't considered the primary one for a shared device suggest a name, manufacturer or model without overwriting the value set by the primary integration. A device now belongs to a single config entry, so there is no longer a primary integration to defer to, and the plain fields can be set directly.
The three fields have been removed from the DeviceInfo type, so setting them is a typing error, and passing any of them to async_get_or_create logs a warning. As with the other device registry deprecations, core and core integrations raise RuntimeError, while custom integrations keep working with a warning until Home Assistant Core 2027.9.
Entities which set these fields — device trackers, for example, set default_name — should pass the non-default variant instead:
# Before
DeviceInfo(
connections={(CONNECTION_NETWORK_MAC, mac)},
default_name=f\"Device {mac}\",
)
# After
DeviceInfo(
connections={(CONNECTION_NETWORK_MAC, mac)},
name=f\"Device {mac}\",
)
created_at or modified_at to async_get_or_create is deprecatedcreated_at and modified_at are managed by the device registry itself, and passing them to DeviceRegistry.async_get_or_create never had any effect — the values were ignored. Passing either is now deprecated in core PR #179998: core and core integrations raise RuntimeError, while custom integrations only log a warning, until Home Assistant Core 2027.9. Simply drop the arguments.
The changes above land alongside a large number of per-integration adaptations — migrating to via_device_id, using the new lookup helpers, and removing device self-references — which can serve as further examples. Search the core repository for pull requests referencing these APIs if you need a concrete migration to follow.
This post describes changes to the device registry WebSocket API — the commands and device serialization consumed by the frontend, custom cards, and other WebSocket clients. They stem from two changes to the device registry:
\nMost clients only read devices through config/device_registry/list, and the new device fields are additive, so no changes are required to keep working — but clients that iterate the device list should be ready to encounter child devices, which are serialized differently. Clients that remove devices, or that inspect a device's config entries, should read on.
config_entry_id and config_subentry_idEvery device returned by config/device_registry/list, and every device in an EVENT_DEVICE_REGISTRY_UPDATED payload, now carries two new fields:
config_entry_id — the id of the single config entry the device belongs to.config_subentry_id — the id of the single config subentry the device belongs to, or null.They replace the previous fields, which modelled a device that could span several config entries and subentries:
\nconfig_entries — a list of config entry ids.config_entries_subentries — a map of config entry id to a list of subentry ids.primary_config_entry — the id of the device's primary config entry.The old fields are kept for backwards compatibility and are deprecated; they are scheduled for removal in Home Assistant Core 2027.8. During the deprecation period they are derived from the new values: a device reports config_entries as the single-element list [config_entry_id], config_entries_subentries as {config_entry_id: [config_subentry_id]}, and primary_config_entry equal to config_entry_id.
Update your client to read config_entry_id and config_subentry_id.
Home Assistant Core 2026.9 introduces child devices (architecture proposal #1414, core PR #178666). A child device is a lightweight logical part of a parent device: it has no hardware or firmware metadata of its own, and it references its parent through a parent_device_id. The parent must be registered by the same config entry and belong to the same config subentry.
config/device_registry/list now returns child devices alongside regular devices, so its result is a mix of two kinds of entry. A child device is serialized with a smaller set of fields:
{
\"id\": \"child1234\",
\"parent_device_id\": \"abcd1234\",
\"config_entry_id\": \"wxyz5678\",
\"config_subentry_id\": null,
\"area_id\": null,
\"name\": \"Left channel\",
\"name_by_user\": null,
\"labels\": [],
\"identifiers\": [[\"demo\", \"left\"]],
\"disabled_by\": null,
\"created_at\": 1723987200.0,
\"modified_at\": 1723987200.0
}
Compared to a regular device, a child device has no connections, via_device_id, configuration_url, entry_type, manufacturer, model, model_id, hw_version, sw_version, serial_number, primary_config_entry, config_entries, or config_entries_subentries. Clients that read the device list must not assume every entry carries these fields.
The reliable way to tell the two apart is the parent_device_id field: it is present and non-null only on child devices. A regular device carries via_device_id instead.
A child device with no area_id of its own inherits its parent's area, so a client resolving a child device's area should fall back to the parent device when the child's area_id is null.
Two related commands also understand child devices:
\nconfig/device_registry/update accepts a child device id — setting area_id, disabled_by, labels, or name_by_user — and returns the updated child device in the reduced serialization shown above.config/device_registry/list_linked_devices always returns an empty linked_devices list for a child device, since a child shares its parent's per-config-entry identifier namespace and is never linked to devices of other config entries.config/device_registry/removeA new WebSocket command removes a device by id:
\n{
\"type\": \"config/device_registry/remove\",
\"device_id\": \"abcd1234\"
}
Because a device now belongs to exactly one config entry, removing it from that config entry removes the device. The command requires admin, and it rejects a composite device id with the error Cannot remove a composite device.
It replaces config/device_registry/remove_config_entry, which took both a device_id and a config_entry_id:
{
\"type\": \"config/device_registry/remove_config_entry\",
\"config_entry_id\": \"wxyz5678\",
\"device_id\": \"abcd1234\"
}
That command still works but is deprecated: it logs a warning and will be removed in Home Assistant Core 2027.9. Its config_entry_id parameter is now only used to check that it matches the device's config entry — a mismatch fails with Config entry not in device — and the device is removed regardless of which config entry was passed. Update clients to call config/device_registry/remove and drop the config_entry_id.
Implemented in core PR #178319.
\nconfig/device_registry/list_linked_devicesBecause connections and identifiers are now unique per config entry, a physical device supported by several integrations is represented by one device per config entry instead of a single shared device. This command returns the other devices that share a connection or identifier with a given device — the sibling devices representing the same physical hardware under different config entries:
\n{
\"type\": \"config/device_registry/list_linked_devices\",
\"device_id\": \"abcd1234\"
}
Result:
\n{
\"linked_devices\": [\"ef567890\", \"12ab34cd\"]
}
The queried device itself is excluded from the result. This lets a client, for example, link from a device page to the other devices that represent the same hardware. Implemented in core PR #177449.
\nconfig/device_registry/list_composite_splitsWhen the device registry is loaded, each pre-migration device that spanned several config entries is split into one device per config entry, and the original (\"composite\") device id no longer refers to a registered device. Composite device ids are still referenced by automations, scripts, dashboards, and target pickers, so this command maps every composite device id to the devices it was split into:
\n{
\"type\": \"config/device_registry/list_composite_splits\"
}
Result:
\n{
\"old_composite_id\": {
\"split_ids\": [\"ef567890\", \"12ab34cd\"],
\"primary_id\": \"ef567890\"
}
}
For each composite device id, split_ids lists the replacement device ids and primary_id is the split that inherited the composite's former primary config entry, or null. Use it to resolve a stored composite device id to a current device — for example, to keep a device picker working when the stored id is a composite id. Implemented in core PR #176693.
The Backwards compatibility section of the companion post describes the rest of the deprecation-period behavior, such as actions targeting a composite device id trickling down to the split devices.
\nClients that subscribe to device_registry_updated events (EVENT_DEVICE_REGISTRY_UPDATED) see two changes, mirroring the Python API:
changes map of an update event reports a device move with the keys config_entry_id and config_subentry_id, replacing the previous config_entries and config_entries_subentries.remove event rather than an update.See Device registry events in the companion post for details.
", "url": "https://developers.home-assistant.io/blog/2026/08/19/device-registry-websocket-api-changes", "title": "Device registry WebSocket API changes", "summary": "Summary", "date_modified": "2026-08-19T00:00:00.000Z", "author": { "name": "Erik Montnemery", "url": "https://github.com/emontnemery" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/07/31/frontend-component-updates-2026.8", "content_html": "We added ha-split-panel, a Home Assistant wrapper around the Web Awesome split panel component.
Use it when a Home Assistant page, dialog, or tool needs a resizable two-pane layout. Custom card authors can use Home Assistant frontend components, but internal Home Assistant UI APIs may change.
\n<ha-split-panel position=\"40\" snap=\"50%\">
<div slot=\"start\">Editor</div>
<div slot=\"end\">Preview</div>
</ha-split-panel>
New component-specific tokens:
\n--ha-split-panel-divider-width
--ha-split-panel-divider-hit-area
--ha-split-panel-min
--ha-split-panel-max
--ha-split-panel-grip-display
ha-tile-info gained more layout controls for custom cards and tile-like surfaces.
New component-specific tokens:
\n--ha-tile-info-gap
--ha-tile-info-min-height
--ha-tile-info-primary-min-height
--ha-tile-info-primary-line-clamp
Use --ha-tile-info-primary-line-clamp when the primary text should wrap to more than one line, and use the min-height tokens to keep rows aligned when some tiles have secondary text and others do not.
ha-form schemas now support conditional field visibility with visible.
[
{
name: \"advanced\",
selector: { boolean: {} },
},
{
name: \"advanced_name\",
visible: { field: \"advanced\", value: true },
selector: { text: {} },
},
]
Supported operators are:
\n\"eq\"
\"not_eq\"
\"in\"
\"not_in\"
\"exists\"
\"not_exists\"
You can also combine conditions with and, or, and not.
Hidden fields are not rendered and are skipped during validation, so use visible instead of custom frontend-only hiding logic when a form field depends on another value.
The text selector now supports HTML pattern validation:
\n{
text: {
pattern: \"[a-z0-9_]+\",
validation_message: \"Use lowercase letters, numbers, and underscores\",
},
}
This works for both single-value and multiple-value text selectors.
\nEntity selectors can now filter by properties of the entity's device:
\n{
entity: {
filter: {
domain: \"sensor\",
device: {
manufacturer: \"Home Assistant\",
model: \"Connect ZBT-1\",
},
},
},
}
A new ui_clock_date_format selector was also added for the clock card date format editor.
The entities and glance cards now support color as the replacement for state_color.
Before:
\ntype: entities
state_color: true
entities:
- light.kitchen
After:
\ntype: entities
color: state
entities:
- light.kitchen
Use color: state for the old state_color: true behavior, and color: none for state_color: false.
Custom panels and add-on app iframes now get safe-area padding by default, so content stays clear of notches, status bars, and home indicators.
\nCustom panels that already handle safe areas themselves can opt out:
\npanel_custom:
- name: my-panel
module_url: /local/my-panel.js
handle_safe_area: true
For iframe-based custom panels, Home Assistant forwards the resolved safe-area values into the iframe document as CSS variables:
\n--safe-area-inset-top
--safe-area-inset-right
--safe-area-inset-bottom
--safe-area-inset-left
Add-on app iframes can also opt into managing the safe area themselves when subscribing to Home Assistant properties:
\nwindow.parent.postMessage(
{
type: \"home-assistant/subscribe-properties\",
handleSafeArea: true,
},
\"*\"
);
The properties message then includes safeAreaInsets.
DirtyStateProviderMixin now also publishes a global dirty state.
When any connected dirty-state provider has unsaved changes, window.isDirtyState is set and Home Assistant fires a dirty-state-changed event.
window.addEventListener(\"dirty-state-changed\", (ev) => {
console.log(ev.detail.isDirty);
});
This is useful for shared infrastructure that needs to avoid disrupting active editors or dialogs with unsaved changes.
", "url": "https://developers.home-assistant.io/blog/2026/07/31/frontend-component-updates-2026.8", "title": "Frontend component updates in 2026.8", "summary": "Component updates", "date_modified": "2026-07-31T00:00:00.000Z", "author": { "name": "Jan-Philipp Benecke", "url": "https://github.com/jpbede" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/07/22/button-standard-event-types", "content_html": "Button event entities now have a set of standard event types, provided by the new ButtonEventType enum. Integrations that use EventDeviceClass.BUTTON should use these types instead of custom strings whenever the interaction maps to one of them.
See the architecture discussion for the full background.
\nPreviously, each integration picked its own strings for button interactions — single, click, hold, double_press, and so on. This inconsistency made it impossible to build generic button automations that work across integrations, and prevented the frontend from offering meaningful trigger suggestions.
The new ButtonEventType standard event types solve this by giving every button integration a shared vocabulary for the common interactions.
ButtonEventType defines six standard event types:
ButtonEventType.PRESS_START: the button was pressed down.ButtonEventType.PRESS_END: the button was released after a brief press (the standard \"click\").ButtonEventType.LONG_PRESS_START: the button was held past a duration threshold.ButtonEventType.LONG_PRESS_END: the button was released after a long hold.ButtonEventType.MULTI_PRESS_ONGOING: an intermediate press in a multi-press sequence was detected.ButtonEventType.MULTI_PRESS_END: a multi-press sequence completed.The MULTI_PRESS_ONGOING and MULTI_PRESS_END events include a multi_press_count attribute in their event data (the ATTR_MULTI_PRESS_COUNT constant) with the number of presses.
None of these are mandatory. Unlike the doorbell ring event, there is no required type here. Each integration maps only the interactions its hardware can actually produce, and lists just those in event_types.
Import ButtonEventType from homeassistant.components.event and include the types your device supports in the entity's event_types. Fire them as the interactions happen:
from homeassistant.components.event import (
ATTR_MULTI_PRESS_COUNT,
ButtonEventType,
EventDeviceClass,
EventEntity,
)
class MyButtonEvent(EventEntity):
_attr_device_class = EventDeviceClass.BUTTON
_attr_event_types = [
ButtonEventType.PRESS_END,
ButtonEventType.LONG_PRESS_END,
ButtonEventType.MULTI_PRESS_END,
]
@callback
def _async_handle_multi_press(self, count: int) -> None:
\"\"\"Handle a completed multi-press sequence.\"\"\"
self._trigger_event(
ButtonEventType.MULTI_PRESS_END,
{ATTR_MULTI_PRESS_COUNT: count},
)
self.async_write_ha_state()
If a device only emits a single event per interaction, with no separate press and release, map it to the matching _end type (PRESS_END for short presses, LONG_PRESS_END for holds, and so on). This keeps the \"button was pressed\" trigger consistent across devices without synthesizing events the hardware never sends.
This change only adds the shared constants; nothing is deprecated and no integration is forced to migrate. Custom event types are still allowed alongside the standard ones. Adopt ButtonEventType when it fits your device.
For full details, see the event entity documentation.
", "url": "https://developers.home-assistant.io/blog/2026/07/22/button-standard-event-types", "title": "Standard event types for button event entities", "summary": "Button event entities now have a set of standard event types, provided by the new ButtonEventType enum. Integrations that use EventDeviceClass.BUTTON should use these types instead of custom strings whenever the interaction maps to one of them.", "date_modified": "2026-07-22T00:00:00.000Z", "author": { "name": "Abílio Costa", "url": "https://github.com/abmantis" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/07/21/device-registry-single-config-entry", "content_html": "A device is now owned by a single config entry, and by a single (or no) config subentry. Devices are no longer merged across integrations: a physical device supported by several integrations is now represented by one device per config entry instead of a single shared device.
\nDevices which were previously tied to multiple config entries are split into one device per config entry when the device registry is loaded. The entity registry is updated so entities point to the correct device.
\nMost integrations don't interact directly with the device registry and don't need any changes. Integrations which interact with it directly need to handle the deprecations listed below.
\nThis is implemented in core PR #175785, the rationale is described in architecture proposal home-assistant/architecture#1226. The changes land in Home Assistant Core 2026.8.
\nUntil now, a physical device supported by several integrations has been merged into a single, shared device. This was achieved by identifying devices by connections and identifiers which are globally unique, so that for example a device tracker and a native integration referring to the same MAC address end up on the same device.
\nThis causes a few problems:
\nThe new behavior is achieved by making identifiers and connections unique per config entry instead of globally unique.
\nUsing the deprecated functionality below logs a warning at runtime. Unless noted otherwise, deprecated functionality remains supported until Home Assistant Core 2027.8.
\nDeviceEntry.config_entriesDeprecated, use DeviceEntry.config_entry_id instead. The property is kept as a compatibility shim which returns a set with the device's single config entry.
DeviceEntry.config_entries_subentriesDeprecated, use DeviceEntry.config_entry_id and DeviceEntry.config_subentry_id instead. The property is kept as a compatibility shim.
DeviceEntry.primary_config_entryDeprecated, use DeviceEntry.config_entry_id instead. A device now belongs to a single config entry, which is its primary config entry.
DeviceEntry.config_entries, DeviceEntry.config_entries_subentries and DeviceEntry.primary_config_entry are only deprecated for ordinary devices, which belong to a single config entry. They are not deprecated when interacting with a synthesized composite device, the read-only device the backwards compatibility resolution returns for a pre-migration composite device id (see Backwards compatibility). Such a device spans several config entries, which config_entry_id and config_subentry_id can't represent, so these three properties, which report the union across the split devices, remain the way to read that information.
DeviceInfo[\"via_device\"] and DeviceRegistry.async_get_or_create(via_device=...)Deprecated, use via_device_id instead. Because identifiers are only unique per config entry, an identifier pair no longer unambiguously points at a single device, which is why via_device is deprecated.
Passing both via_device and via_device_id raises HomeAssistantError.
DeviceRegistry.async_update_device() config entry parametersThe add_config_entry_id, add_config_subentry_id, remove_config_entry_id and remove_config_subentry_id parameters are all deprecated. A device belongs to a single config entry and subentry, so adding and removing config entries is no longer meaningful; a device is instead moved or removed.
To move a device to another config entry or subentry, pass the new new_config_entry_id and new_config_subentry_id parameters:
device_registry.async_update_device(
device.id,
new_config_entry_id=config_entry.entry_id,
new_config_subentry_id=subentry.subentry_id,
)
Moving a device with the old parameters took the integration several async_update_device calls, adding the device to the new config entry and subentry and then removing it from the old ones, with a separate case for a device that only changed subentry within the same config entry. The single call shown above replaces all of that. In addition, the device registry now clears a CONFIG_ENTRY disable when a device is moved to an enabled config entry, so the integration no longer has to carry the disabled_by flag across the move by hand.
Relatedly, async_update_device now validates the disabled_by flag against the owning config entry's disabled state. Setting disabled_by=None for a device on a disabled config entry, or disabled_by=DeviceEntryDisabler.CONFIG_ENTRY for a device on an enabled config entry, is inconsistent; such a value is ignored and logged now, and will raise from Home Assistant Core 2027.8.
Core integrations have been updated as examples: openai_conversation in PR #176662, scrape in PR #176663, waqi in PR #176664 and wolflink in PR #176665.
To remove a device, call DeviceRegistry.async_remove_device():
device_registry.async_remove_device(device.id)
Core integrations have been updated to remove devices this way in PRs #176669, #176671, #176672 and #176673.
\nDeviceRegistry.async_get_device()Deprecated. Identifiers and connections are only unique per config entry, so a lookup by identifiers or connections can by design match more than one device, and what async_get_device returns is therefore ambiguous.
When the owning config entry is known, look the device up scoped to that config entry with the new methods DeviceRegistry.async_get_device_by_identifier() or DeviceRegistry.async_get_device_by_connection(). Each takes a single identifier or connection tuple plus the config entry id, so the lookup can no longer be ambiguous:
# Before
device = device_registry.async_get_device(identifiers={(DOMAIN, serial_number)})
# After
device = device_registry.async_get_device_by_identifier(
(DOMAIN, serial_number), entry.entry_id
)
Inside an entity, prefer self.device_entry over a registry lookup. If you genuinely need every device matching a key, possibly across config entries, use DeviceRegistry.async_get_devices(), which returns a list.
Core integrations are migrated to the new methods, heos in core PR #176932 is an example.
During the deprecation period, async_get_device resolves an ambiguous lookup as described in Backwards compatibility below. Note that this backwards-compatible resolution only happens through the DeviceRegistry lookup methods such as async_get() and async_get_device(); interacting with the devices container directly, for example DeviceRegistry.devices.get(device_id), does not synthesize a composite device.
Helper integrations must not add their config entry to the source entity's device or to a user-selected device, they should link their entities to the device instead. This is a direct consequence of the change described here: a device now belongs to a single config entry, so a helper config entry can no longer be added to a device owned by another integration.
\nThis was announced last year in Updated guidelines for helper integrations linking to other integration's device, and stops working in Home Assistant Core 2026.8.
\nhelpers.device.async_device_info_to_link_from_entity() and async_device_info_to_link_from_device_id()Both helpers now always return None.
They returned a DeviceInfo carrying another device's identifiers and connections, which implicitly added the caller's config entry to that device. A device with a single config entry can't represent that, it would silently fork a duplicate device instead.
Link the helper entity to the device by setting self.device_entry in the entity's constructor instead:
self.device_entry = async_entity_id_to_device(hass, source_entity_id)
The helpers are removed in Home Assistant Core 2027.8.
\nhelpers.helper_integration.async_handle_source_entity_changes(add_helper_config_entry_to_device=...)The parameter no longer has any effect and should be removed from the call.
\nWhen the source entity moves to another device, async_handle_source_entity_changes now only updates the helper entity to link to the new device, it no longer removes the helper config entry from the old device and adds it to the new one.
Passing the parameter is accepted until Home Assistant Core 2027.8, and logs a warning.
\nThe helper used to clean up a helper integration's devices from a config entry migration step has been renamed from async_remove_helper_config_entry_from_source_device to homeassistant.helpers.helper_integration.async_remove_helper_devices in core PR #176714. The old name is kept as a deprecated alias which keeps working until Home Assistant Core 2027.8. The new signature is:
def async_remove_helper_devices(
hass: HomeAssistant,
*,
helper_config_entry_id: str,
source_device_id: str | None,
remove_all_devices: bool = False,
keep_device_ids: Collection[str] = (),
) -> None:
helpers.device.async_remove_stale_devices_links_keep_entity_device() and async_remove_stale_devices_links_keep_current_device()Both are now no-ops. Call async_remove_helper_devices with remove_all_devices=True from the helper's async_setup_entry instead:
async_remove_helper_devices(
hass,
helper_config_entry_id=entry.entry_id,
source_device_id=entry.options.get(CONF_DEVICE_ID),
remove_all_devices=True,
)
The template helper has been migrated as an example in core PR #176900. The functions are removed in Home Assistant Core 2027.8.
A device can no longer be tied to more than one config subentry. This is a breaking change without a backwards compatibility shim; integrations which attach several subentries to the same device must create one device per subentry.
\ntelegram_botThe telegram_bot integration has been adjusted for this in core PR #176606, which can be used as an example.
It previously had a single bot device shared by every chat, with each chat's subentry attached to that same device. It now creates an individual device per chat, linked to the bot device as a via device. A config entry migration moves each chat's notify entity onto its own device and strips the chat subentries from the bot device, leaving the bot device with no subentry.
\nNote that the PR was written before via_device_id was added, new code should use via_device_id instead of via_device.
When child devices are introduced, integrations which model this with a via device should migrate to child devices instead.
\nA pre-migration composite device id no longer refers to a real device. Attempting to link an entity to such an id, by passing it to EntityRegistry.async_get_or_create(device_id=...) or EntityRegistry.async_update_entity(device_id=...), is ignored with a logged warning rather than applied. A new entity is then created with no device, and an existing entity keeps its current device. Passing a genuinely non-existent device id still raises ValueError as before.
Entities whose stored device is a composite device with no split owned by the entity's config entry are detached from the device when the registry is loaded; the owning integration is expected to re-link them.
\nLink entities to one of the split devices instead, looking it up with async_get_device_by_identifier or async_get_device_by_connection.
Splitting a pre-migration composite device happens when the registry is loaded from storage, before any listeners run, so it emits no EVENT_DEVICE_REGISTRY_UPDATED events; devices are already split at startup.
Two things change for integrations which subscribe to EVENT_DEVICE_REGISTRY_UPDATED, or use async_track_device_registry_updated_event, and inspect the payload:
changes dict of an update event reports a device move with the keys config_entry_id and config_subentry_id, replacing the previous config_entries and config_entries_subentries.A device now belongs to a single config entry, so it can no longer lose one config entry while staying around for another. Integrations which previously watched update events for a change to the config_entries or config_entries_subentries keys, typically to detect their config entry being removed from a device shared with another integration, probably only need to handle remove events now: a device losing its config entry means the device is removed.
Splitting devices changes assumptions which custom integrations may rely on, and device ids which are stored in automations and scripts no longer exist as devices. To soften that, the device registry makes a best-effort attempt to keep unmodified custom integrations working, by resolving a pre-migration composite device id to the devices it was split into.
\nThis is best-effort, not a guarantee. The shims can't cover every way a custom integration interacts with the device registry, and an operation which is ambiguous across the split devices can't be applied at all. An AI-assisted analysis of 462 custom integrations interacting directly with the device registry suggests at least 90% are expected to work unaffected, which also means some will not. Please migrate your integration to the new API rather than relying on these shims; they are removed in Home Assistant Core 2027.8.
\nDuring the deprecation period:
\nDeviceRegistry.async_get() synthesizes a read-only restored composite device when passed the id of a pre-migration composite device. Its identifiers, connections and config entries are the union of the split devices'. The synthesis only happens in async_get(); interacting with the devices container directly, for example DeviceRegistry.devices.get(device_id), does not synthesize a composite and returns None for a pre-migration composite device id.DeviceRegistry.async_get_device() resolves a lookup by identifiers or connections matching several config entries to a single device when possible, preferring the device whose config entry domain matches the looked-up identifier. If the remaining matches are the splits of one pre-migration composite device, a read-only composite spanning them is returned. For independent devices sharing an identifier or connection, a device owned by the calling integration is preferred, falling back to the first match.DeviceRegistry.async_update_device() and DeviceRegistry.async_remove_device() forward the call to each of the split devices. Arguments which rewrite a device's identity or move it are ambiguous across the split devices; they are ignored and reported to the offending integration.get_entries_for_device_id() and async_entries_for_device() expand a pre-migration composite device id to the entities of the devices it was split into.A new method DeviceRegistry.async_get_devices_for_composite_device_id() returns the devices a pre-migration composite device was split into. DeviceRegistry.async_is_composite_device_id() returns whether a device id is a pre-migration composite device id, that is, an id which was split into one device per config entry and no longer refers to a registered device.
AI-assisted development has become part of daily reality for many contributors, and for us as maintainers too. That can be a good thing: AI tools help people write code, improve their English, and find their way in an unfamiliar codebase. It also has a downside: unreviewed AI output submitted as a contribution costs maintainers real time, and maintainer time is the scarcest resource an open source project has.
\nToday, we are publishing the Open Home Foundation AI Policy. It applies to all Open Home Foundation projects, including every repository in the home-assistant and home-assistant-libs GitHub organizations.
The policy boils down to a few points:
\nWe are rolling the policy out to every repository in both organizations. Each repository gets an AI_POLICY.md file in its root, and existing contributing guidelines and AGENTS.md files gain a reference to it, so both humans and their AI tools know what we expect.
Read the full policy in the developer documentation. If a contribution does not follow it, it will be closed. If you believe that happened to yours in error, reach out to a maintainer and we will sort it out.
", "url": "https://developers.home-assistant.io/blog/2026/07/20/ai-policy", "title": "Introducing the Open Home Foundation AI Policy", "summary": "AI-assisted development has become part of daily reality for many contributors, and for us as maintainers too. That can be a good thing unreviewed AI output submitted as a contribution costs maintainers real time, and maintainer time is the scarcest resource an open source project has.", "date_modified": "2026-07-20T00:00:00.000Z", "author": { "name": "Franck Nijhof", "url": "https://github.com/frenck" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/07/05/modernizing-modbus", "content_html": "Modbus is everywhere in the modern home: solar inverters, energy meters, heat pumps, and all kinds of industrial equipment that has found its way indoors. Home Assistant has long supported these devices through the YAML-based modbus integration, where users hand-write register maps in their configuration. That integration is not going anywhere, and existing setups keep working. But hand-writing register maps puts the burden of understanding a device's protocol on every user, and it does not fit the config-flow, UI-first direction the rest of Home Assistant has taken.
So we are adding a new way to use Modbus: an integration-based approach, where a device integration owns the device-specific knowledge and the user simply picks their device in the UI, the same as any other integration.
\nA Modbus connection is a single, exclusive resource: only one party can talk on the bus at a time. A serial (RS-485) bus, or a TCP-to-serial gateway, can carry many devices at once, sometimes from different manufacturers. If two integrations each open their own connection to the same bus, they fight over it, and historically Home Assistant did not support sharing a bus between integrations at all.
\nThe modbus integration solves this by handing out units over connections it shares. A device integration collects its own connection details in its own config flow, the same as any other integration, and asks modbus for a unit on them. Two integrations that ask with equal details get units over one connection, so their requests serialize behind it instead of contending for the bus.
The shared connection is not configured or persisted separately. It exists only while an integration holds a unit, and it closes when the last consumer's config entry unloads. That keeps the user experience where it belongs — you set up your heat pump, not a bus — while still giving the bus a single owner. The Modbus developer documentation covers how to ask for a unit, with example code.
\nThe connection abstraction underneath modbus lives in modbus-connection, a new library we designed for this purpose and published on PyPI. It is not bound to Home Assistant and can be used standalone in any Python project. It presents a common, backend-neutral interface, so device library authors write against one API regardless of the underlying Modbus implementation, and it ships a device-modelling framework and a pytest plugin to make building and testing a device library straightforward.
This keeps concerns where they belong. A device library is a normal PyPI package that knows how to talk to a specific device, and a consuming integration in Home Assistant wires that library up to a shared connection and exposes entities. Both can be developed and tested independently.
\nFor more background, see our research.
\nWith these new building blocks in place, it is now possible to turn a collection of YAML configuration for Modbus into manufacturer-specific integrations that people can set up via the UI. If you're (interested in) working on this, stop by the #modbus channel on the Home Assistant Discord and we'll be happy to help.
\nIf you're using an AI agent, you can give it the following prompt:
\n\n", "url": "https://developers.home-assistant.io/blog/2026/07/05/modernizing-modbus", "title": "Modernizing Modbus in Home Assistant", "summary": "Modbus is everywhere in the modern home: solar inverters, energy meters, heat pumps, and all kinds of industrial equipment that has found its way indoors. Home Assistant has long supported these devices through the YAML-based modbus integration, where users hand-write register maps in their configuration. That integration is not going anywhere, and existing setups keep working. But hand-writing register maps puts the burden of understanding a device's protocol on every user, and it does not fit the config-flow, UI-first direction the rest of Home Assistant has taken.", "date_modified": "2026-07-05T00:00:00.000Z", "author": { "name": "Paulus Schoutsen", "url": "https://github.com/balloob" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/07/03/media-source-search", "content_html": "I want to create a new integration for Home Assistant using the new Modbus Connection integration as documented here: https://developers.home-assistant.io/docs/modbus/introduction
\nThe YAML we want to turn into a device library can be found here: TODO INSERT LOCATION OF MODBUS YAML!
\nThe deliverables of this task are going to be 3 folders:
\n\n
\n- \n
\nStart by creating a device library based on the YAML. Follow https://github.com/darkrain-nl/sofar-modbus as an exact example, including how to use component models, all GitHub Actions, helper scripts and README. This library is meant as a standalone device library and should not mention Home Assistant. Look at the source of modbus_connection to figure out all supported fields.
\n- \n
\nCreate an integration that can be contributed to Home Assistant core that follows this example: https://github.com/home-assistant/core/tree/dev/homeassistant/components/sofar
\n- \n
\nCreate a custom integration version where the device library is vendorized so it is ready to be tested by the community via HACS. Follow this template https://github.com/ludeeus/integration_blueprint
\n
Media sources can now implement search. By adding an async_search_media method to your MediaSource, users can search through your media directly from the media browser.
from homeassistant.components.media_player import SearchMedia, SearchMediaQuery
async def async_search_media(
self, item: MediaSourceItem, query: SearchMediaQuery
) -> SearchMedia:
\"\"\"Search media.\"\"\"
results = [...] # list of BrowseMediaSource items
return SearchMedia(result=results)
To tell the media browser which items can be searched, set the can_search flag to True on the BrowseMediaSource items you return while browsing (typically directories). Other integrations can trigger a search through the new media_source.async_search_media helper.
For more info, see the updated documentation.
", "url": "https://developers.home-assistant.io/blog/2026/07/03/media-source-search", "title": "Media sources can now be searched", "summary": "Media sources can now implement search. By adding an asyncsearchmedia method to your MediaSource, users can search through your media directly from the media browser.", "date_modified": "2026-07-03T00:00:00.000Z", "author": { "name": "Josef Zweck", "url": "https://github.com/zweckj" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/06/30/async-initialize-triggers-home-assistant-start-deprecated", "content_html": "The dedicated home_assistant_start flag of async_initialize_triggers is deprecated and will be removed in Home Assistant Core 2027.8. During the deprecation period the parameter no longer has any effect.
The flag existed because the homeassistant start trigger was a pseudo trigger: instead of acting like a real trigger, it relied on the caller of the trigger API passing home_assistant_start=True so that async_initialize_triggers would fire the trigger during startup.
The start trigger has been rewritten to work as a real trigger, so the flag is no longer needed. Callers of async_initialize_triggers should simply stop passing home_assistant_start.
To make the new implementation possible, the rewrite adds HomeAssistant.async_add_startup_job, which registers a job to be called after all listeners to EVENT_HOMEASSISTANT_START have executed, but before EVENT_HOMEASSISTANT_STARTED is fired. This mirrors the approach already used for the homeassistant shutdown trigger, and avoids adding yet another core state and event to the already complex relationship between core states and events.
For more details, see core PR 175160.
", "url": "https://developers.home-assistant.io/blog/2026/06/30/async-initialize-triggers-home-assistant-start-deprecated", "title": "Deprecation of the home_assistant_start flag of async_initialize_triggers", "summary": "The dedicated homeassistantstart flag of asyncinitializetriggers is deprecated and will be removed in Home Assistant Core 2027.8. During the deprecation period the parameter no longer has any effect.", "date_modified": "2026-06-30T00:00:00.000Z", "author": { "name": "Erik Montnemery", "url": "https://github.com/emontnemery" }, "tags": [] }, { "id": "https://developers.home-assistant.io/blog/2026/06/30/new-unit-enumerators", "content_html": "As of Home Assistant Core 2026.7, the following unit constants are deprecated and replaced\nby a corresponding enum:
\nUnitOfDensity enumerator replaces mass over volume CONCENTRATION_*** constants\n(\"g/m³\", \"mg/m³\", \"μg/m³\", \"μg/ft³\")UnitOfRatio enumerator replaces unit-less ratio CONCENTRATION_*** constants\n(\"ppm\", \"ppb\")CONCENTRATION_PARTS_PER_CUBIC_METER was only used by a single integration and is deprecated\nwithout a replacement unit.
Please note that the use of PERCENTAGE constant is also deprecated when used as a unit of\nmeasurement, even if the constant itself is not deprecated.