Matter integration

Matter Integration

Lock Code Manager supports Matter locks that have the User Management (USR) feature with PIN credential support via the Matter integration.

How It Works

Matter lock PINs are write-only — the lock accepts PIN codes but never reveals them back. This means:

• LCM can set and clear PINs on the lock
• The lock reports whether a credential slot is occupied, but not the actual PIN value
• The code sensor shows the configured PIN (from LCM config) rather than the on-lock value
• On Home Assistant restart, LCM re-sets all configured PINs to guarantee correctness

Requirements

• Home Assistant 2026.6.0 or later
• A Matter lock with User Management (USR) feature and PIN credential support
• The Matter integration configured and connected in Home Assistant

How LCM Tags Lock Users (4.0.0+)

LCM identifies its own Matter users by writing a tag into the user name field: lcm:<slot>:<friendly name>. So an LCM-managed user for slot 3 named "Alice" appears on the lock as lcm:3:Alice. This lets LCM coexist with other Matter controllers (or keypad-enrolled users) on the same lock — users whose names don't carry the tag are invisible to LCM's write paths.

Two lifecycle consequences worth knowing:

• Lock-side users persist across PIN clear/replace cycles. Clearing a slot's PIN deletes the credential but leaves the user record in place as a stable slot anchor. The user is removed only when the slot itself is removed from LCM's config.
• Matter credential indices are opaque. Previously, LCM pinned the Matter credential index to the LCM slot number; now Matter auto-allocates and LCM discovers the credential by walking the tagged user's credential list. You may see the on-lock credential index differ from the LCM slot, which is expected.

On upgrade from an earlier version, LCM adopts existing pre-tagged users at their old credential_index == slot position so existing PINs don't get orphaned.

Supported Operations

Operation	Supported	Notes
Set PIN	✅	Via Matter DoorLock cluster commands
Clear PIN	✅	Via Matter DoorLock cluster commands
Read PIN	❌	Matter spec does not allow reading back PINs
Push updates	✅	Via DoorLock LockUserChange events (occupancy only, not PIN values)
Code slot events	✅	Via DoorLock LockOperation events (keypad PIN usage)

Limitations

• PINs are write-only: LCM cannot verify the actual PIN on the lock. The sync indicator assumes the PIN is correct after a successful set.
• Occupancy-only push updates: LCM detects credential changes (add/clear/modify) in real time via LockUserChange events, but cannot see the actual PIN value. External changes are detected immediately rather than waiting for the next poll.
• Restart behavior: On HA restart, all configured PINs are re-set to the lock. This is a one-time operation per restart and ensures the lock has the correct PINs.
• PIN changes while masked: When you change a configured PIN, LCM detects the change and re-sets the new PIN, even though it can't read the old one back.

Event Subscriptions

LCM subscribes to two DoorLock cluster events:

• LockOperation (event ID 2): Fires when a PIN is used to lock or unlock. LCM creates pin_used events for automations, enabling the Slot Usage Limiter blueprint for Matter locks.
• LockUserChange (event ID 4): Fires when a credential is added, modified, or cleared. LCM pushes occupancy updates to the coordinator immediately, so changes are detected in real time rather than waiting for the next poll.

Note: only PIN credential events are tracked. Other credential types (RFID, fingerprint, etc.) are not currently handled.

Verified Locks

Matter lock support is new. If you have tested LCM with a specific Matter lock, please open an issue or PR to add it to this list.

Troubleshooting

Lock not detected

Ensure the Matter integration is loaded and the lock entity appears in Home Assistant. LCM detects Matter locks by their entity domain (lock.* from the matter integration).

"Does not support user management" error

The lock's Matter DoorLock cluster does not have the USR (User Management) feature enabled. This is a hardware/firmware limitation.

"Does not support PIN credentials" error

The lock supports user management but not PIN credentials (it may only support RFID or biometric credentials).