Skip to content

v0.3.0 — entity identity moves to the device UUID

Choose a tag to compare

@github-actions github-actions released this 05 Sep 00:35
· 36 commits to main since this release

Superseded by v0.3.1. Install that instead — a review of this release found three ways the migration below could leave an install worse than it started.

These notes were missing when this release was cut, and are backfilled here for the record.

Entity identity changed, and migration is automatic

Entity and device identity moved from the BLE advertised name to the GATT
device UUID. On the first connection after upgrading, entity unique ids and the
device registry row are rewritten in place, so entity ids, history, names,
and area assignments are preserved
— dashboards and automations keep working.

Why

Identity previously came from the advertised name, while device_info
preferred the device UUID and fell back to the name. A window that had not yet
reported its UUID when entities were created got a name-keyed device row that
silently became UUID-keyed on a later run. Home Assistant treats that as a
different device: duplicate devices, and history stranded on the old one.

The two roles are now split by what each identifier can actually do. Discovery
and the config entry's unique id stay on the advertised name, because
rediscovery has only an advertisement to match against and reading the UUID
needs a connection. Entities and the device registry key on the UUID, adopted
once and never replaced — a different UUID means a different window.

Fixes #8
and #12.

Known problems, fixed in v0.3.1

  • A unique-id conflict part-way through the rewrite left the entry stranded
    across two identity namespaces, failing setup with no message and no recovery.
  • A second entry could adopt a UUID another already held, then load with no
    entities at all.
  • The entry and the registries are written to stores that flush seconds apart;
    a crash in between left them disagreeing with nothing to repair it.