Upgrading to 5.0

Upgrading to 5.0

Lock Code Manager 5.0 is configured by user, not by slot number. The slot number still exists — locks are built around numbered slots and always will be — but it is bookkeeping now. What you name, see and address is the person holding the code.

Upgrading migrates each config entry from version 3 to version 4. It cannot be undone from inside the integration. Downgrading Lock Code Manager will not convert your configuration back; the only way back is restoring a Home Assistant backup. Take one before you upgrade.

If you roll back and try again, read Restoring a backup and upgrading again first. There is one thing that costs you history, and it is avoidable.

---

What happens on the first restart

The migration runs once, when Home Assistant next starts. In order:

1. Every slot is given a user name. A slot that already had a name keeps it. A slot with a PIN but no name is named after its slot number, so nothing that holds a credential is left anonymous.
2. Empty slots are dropped. A slot with neither a name nor a PIN held no credential and named nobody, so it is removed along with its entities and its device.
3. Entity IDs are re-slugged onto the user's name (see below).
4. Codes the configuration cannot account for are offered up, once (see Unmanaged codes).
5. A notification lists every entity ID that changed, so you can repoint anything that referenced the old ones.

Your PINs, conditions and enabled/disabled states all carry across. So do your entity settings, area assignments and recorder history — the entities are renamed in place rather than recreated, so nothing hanging off them is stranded.

---

Entity IDs change

Before, an entity was named after the slot it lived in:

text.all_locks_code_slot_1_pin
binary_sensor.front_door_lock_code_slot_1_in_sync

Now it is named after the person:

text.all_locks_raman_pin
binary_sensor.all_locks_raman_front_door_lock_in_sync

The pattern is {config entry title} {user name} {what it is}. The config entry title is included because a name is only unique within its entry — two entries each holding a "Raman" would otherwise collide.

Home Assistant repoints recorder history automatically, so your graphs and logbook keep working. What it does not do is rewrite entity IDs stored inside automations, scripts, dashboards or blueprints. Those keep pointing at names that no longer exist, silently.

So after upgrading you get a notification titled "Entity IDs now follow your users' names" listing every rename as old → new. Work through it. The automations most likely to be affected are ones built from the Slot Usage Limiter and Slot Usage Notifier blueprints, which reference these entity IDs directly.

The credential-used event was renamed

The event entity that fires when a PIN is used is now event.{entry} {user} credential_used, and it is named "Credential used" rather than being unnamed. It reports a credential being used rather than specifically a PIN, ahead of credential types beyond PINs.

If you have automations triggering on the old event entity, they are in the rename notification along with everything else.

---

Users, not slots

Every user must have a name

A name is required, must be unique within the config entry, and cannot contain |. The name is what identifies the user everywhere: in the configuration, on the dashboard, and in the actions.

Renaming a user is free. Unique IDs still carry the slot number, so a rename does not disturb entity IDs, history, or anything referencing them. Only the display name changes.

Slot numbers are chosen for you

You no longer pick a slot number when adding someone. Lock Code Manager reads what each lock actually holds, asks each provider where its slot numbers stop, and allocates a free one. Existing users keep the numbers they already had.

Removing a user clears their PIN

Earlier versions left a removed user's PIN programmed on the lock, and the code went on working. From 5.0, removing a user clears the credential from every lock in the entry.

The delete_user action takes a clear_credentials flag if you want the opposite — hand the credential over and stop managing it — but the default, and what the dashboard does, is to clear it.

---

Unmanaged codes

Because earlier versions left codes behind, your locks may hold codes that no configuration accounts for. Lock Code Manager cannot tell one of those from a code you set at the keypad yourself — they look identical.

So on upgrade, and only once, every unaccounted-for code raises a repair under Settings → Repairs, one per slot, offering two answers:

• Clear it — remove the code from the lock.
• Keep it — leave it programmed and stop asking.

Neither is the "correct" answer; only you know whether that code belongs to somebody. If you keep a code, that slot stays occupied and will not be handed to a new user.

This check does not run again. It is measured against the configuration you end up with after migrating, not the one you had before.

---

The dashboard

The generated dashboard is user-centric now:

• The user card (custom:lcm-user) shows a person, never a slot number. It can rename them, change their PIN, set a condition, and remove them.
• An "Add user" card (custom:lcm-add-user) sits between the users and the locks, with a name, an optional PIN (with a generator), a condition picker and an enabled toggle.
• custom:lcm-slot still works but is deprecated. It is the same card under an old name and logs a warning; it will be removed in a future release. Change type: custom:lcm-slot to type: custom:lcm-user in any dashboard you wrote by hand. Generated dashboards update themselves.

The config entry no longer creates a device of its own. It held no entities and existed only so the per-user devices had a parent; the users are the devices now.

See Custom Cards and UI Strategies.

---

New actions

Two actions were added so an entry can be managed without opening the config flow:

• lock_code_manager.add_user
• lock_code_manager.delete_user

Both accept either config_entry_id or config_entry_title.

---

Restoring a backup and upgrading again

If you upgrade, restore a pre-upgrade backup, and upgrade a second time, the second upgrade loses your history — quietly.

Home Assistant's recorder repoints history when an entity is renamed, but it declines when the destination name already exists, logs a warning, and carries on. Your first upgrade created those names in the recorder database. Restoring a backup rewinds your configuration past that point, but the recorder database keeps moving forward, so the second upgrade asks for names that are already taken.

Nothing is deleted — the history is still in the database under the old names — but no entity points at it any more.

To avoid it: restore the recorder database along with the configuration, or accept the gap. A single one-way upgrade never hits this.

---

If something goes wrong

• Check Settings → Repairs first; the migration reports through it.
• The rename notification stays in your notification list until you dismiss it. Do not dismiss it until you have repointed your automations.
• Debug logs and device diagnostics both include the migrated configuration shape.
• Recovery from a bad migration is a Home Assistant backup restore. There is no code-level downgrade.