Ha Integration Conventions

Home Assistant integration conventions

These are the rules that are cheap to follow while writing and expensive to retrofit, because getting them wrong changes entity IDs or loses history in installations you cannot reach.

The three that cost users data if you get them wrong

Unique IDs are permanent. _attr_unique_id is what ties an entity to its recorded history, its customisations and its area. Derive it from something the device reports — serial, MAC — plus a stable key. Never from the host, the IP, the display name, the config entry ID, or an index into a list. Changing it later silently creates a new entity with a _2 suffix and abandons years of statistics.

Corollary: leave out anything that can be corrected. If the model or the protocol version is part of the ID, fixing a mis-detection orphans everything.

The config entry's unique ID is the device's identity. Set it in the config flow with async_set_unique_id(serial) and _abort_if_unique_id_configured(updates=...). Keying on the host means a DHCP lease change adds a duplicate entry; the updates= argument is what makes a re-run of the flow move the existing entry to the new address instead.

Migrations are one-way. If you must change a unique ID scheme, migrate explicitly in async_migrate_entry with entity_registry.async_update_entity, bump VERSION, and test it. Do not hope users will re-add the integration.

Naming and translation

class FooEntity(CoordinatorEntity[FooCoordinator]):
    _attr_has_entity_name = True

With has_entity_name, the entity's own name is just the thing it measures — "Temperature", not "Living Room Sensor Temperature". Home Assistant composes the device name in front of it. Setting _attr_name to a string containing the device name gives users "Kitchen Kettle Kitchen Kettle Temperature".

Names come from translation_key + strings.json, not from Python strings:

SensorEntityDescription(key="temperature", translation_key="temperature", ...)

{"entity": {"sensor": {"temperature": {"name": "Temperature"}}}}

Set _attr_name = None on the one entity that is the device (a single lamp's light entity, a lock's lock entity) so it inherits the device name alone.

strings.json is the source; translations/en.json is what Home Assistant serves. They must be identical — CI diffs them. Copy, never hand-edit one of them.

Config entry runtime data

type FooConfigEntry = ConfigEntry[FooCoordinator]


async def async_setup_entry(hass: HomeAssistant, entry: FooConfigEntry) -> bool:
    entry.runtime_data = coordinator

Not hass.data[DOMAIN][entry.entry_id]. The typed alias means every platform reads entry.runtime_data with no cast and no KeyError on a half-torn-down entry.

Coordinator

• await coordinator.async_config_entry_first_refresh() in async_setup_entry. It raises ConfigEntryNotReady on failure, which is what makes Home Assistant retry with backoff rather than marking the entry broken.
• Raise UpdateFailed for transient problems and ConfigEntryAuthFailed for rejected credentials. The first retries on a timer; the second prompts the user to reauthenticate. Retrying a bad token every 30 seconds forever is the standard version of this bug.
• For a push protocol, keep a DataUpdateCoordinator but call async_set_updated_data from the callback and use update_interval only as a reconnect backstop.
• Do not log every failed poll. The coordinator already logs the first failure and the recovery, and suppresses the rest.

Availability

The default — entities go unavailable when the coordinator fails — is right for most things. Override it only with a reason worth writing down. A solar inverter that sleeps overnight, for example, should stay available and expose staleness as data (a last_seen timestamp, a connectivity binary sensor), because marking it unavailable puts a nightly gap in every history graph. If you do override it, say why in a docstring; the next person will assume it is a mistake otherwise.

Config flow

• Every flow needs user. Add reauth if credentials can expire and reconfigure if the device can move. Both are cheap and both are the difference between a user fixing something in 10 seconds and deleting the integration.
• _abort_if_unique_id_mismatch(reason="wrong_device") in reconfigure, so nobody points an entry at a different device and silently merges two histories.
• Errors go back to the same form with errors={"base": "..."} and the flow must still work once the problem is fixed. Test the recovery, not just the message.
• Discovery (dhcp, zeroconf, bluetooth, usb blocks in the manifest) beats asking for an IP. If the protocol makes it possible, do it.
• data is what the integration needs to connect. options is what the user can change without re-validating. Do not put a poll interval in data.

Services

Register in async_setup (not async_setup_entry) so the service exists once, not once per entry. Every service needs an entry in services.yaml and matching strings.json text, with selectors — a service that asks for a raw entity ID string in the UI is a service nobody discovers. Raise ServiceValidationError for bad input from the user and HomeAssistantError for a failure of the device; only the second one gets a traceback.

Diagnostics

Implement async_get_config_entry_diagnostics before the first release. It turns "it doesn't work" into a file. Redact serials, tokens and anything else that identifies a person's hardware with async_redact_data.

Deprecated — do not write these

Blocking calls

Everything in async_ code must be non-blocking. File I/O, requests, time.sleep and most third-party clients are not. Wrap them in hass.async_add_executor_job. Home Assistant detects and warns about some of these at runtime, but only some.