Skip to content
raman325 edited this page Oct 17, 2026 · 5 revisions

Z-Wave Integration

Lock Code Manager supports Z-Wave locks via the Z-Wave JS integration in Home Assistant.

How It Works

In Lock Code Manager you configure named users; the lock itself stores PIN codes in numbered user code slots, and LCM assigns each user's PIN to one of those slots for you (the slot number is internal bookkeeping — the interface addresses everything by user). Lock Code Manager reads, sets, and clears these codes via the Z-Wave JS driver. Most Z-Wave locks support push updates — when a code is used or changed, the lock notifies Home Assistant immediately.

Some Z-Wave locks mask PIN codes (returning **** instead of the actual value). Lock Code Manager handles this transparently — masked codes are treated as "occupied but unreadable" and the configured PIN is shown in the sensor display.

User Credential CC vs User Code CC

Z-Wave locks expose codes through one of two command classes:

  • User Code CC (UC) — the older slot-only model: a slot holds a PIN with no user concept. LCM addresses these by slot number directly. No on-lock identity tag is needed (there is no name field).
  • User Credential CC (U3C) — the newer Z-Wave Plus v2 model: each PIN belongs to a named user on the lock. LCM tags its own U3C users with lcm:<slot>:<name> in the user-name field — so an LCM user named "Alice" whose internal slot number is 3 appears on the lock as lcm:3:Alice. This lets LCM coexist with other controllers managing their own users on the same lock.

For U3C locks, a few consequences worth knowing:

  • Lock-side user_id is not pinned to LCM's slot number. Z-Wave auto-allocates a free user_id and LCM discovers the user by walking the lock's user list for the tag. You may see the on-lock user_id differ from LCM's internal slot number, which is expected.
  • Long names are shortened. If the tagged name is longer than the lock allows, LCM shortens the display name. If even lcm:<slot>: doesn't fit, LCM uses just the slot number as the name.
  • Removing a user from LCM removes only LCM's PIN. If the lock-side user holds nothing but LCM's PIN, LCM deletes the user. If it also holds credentials added another way (another PIN, an RFID tag, a fingerprint), LCM removes only its own PIN, keeps the user, and removes its tag from the name. LCM never deletes or modifies users without its tag. If removal fails, LCM retries it, and raises a repair if it keeps failing.
  • Existing installs migrate seamlessly. On the first write after upgrading from a pre-4.0 version, LCM scans for an untagged user at the old user_id == slot position; if found, it adopts that user (preserving its credentials) and rewrites its name to the new tagged form. No PIN re-entry needed.

UC locks have no user name field to tag. Removing a user from LCM clears its slot.

LCM uses the Z-Wave JS unified access_control API for both command classes; the same code path serves UC and U3C locks. It relies on driver fixes in zwave-js 15.24.3, which is included in the minimum supported Home Assistant version.

Requirements

  • Home Assistant 2026.9.0 or later (which includes zwave-js 15.24.3 or later)
  • The Z-Wave JS integration configured in Home Assistant
  • A Z-Wave lock with user code support

Supported Operations

Operation Supported Notes
Set PIN ✅ Via the Z-Wave JS driver's unified access_control API
Clear PIN ✅ Via the Z-Wave JS driver's unified access_control API
Read PIN Varies Some locks return actual PINs, others mask them
Push updates ✅ Real-time notifications for code changes and usage
Code slot events ✅ Reports which code was used to unlock

Features

  • Push updates: Code changes and lock operations are reported in real time (no polling delay)
  • Code slot events: The user's credential_used event entity fires when a specific code is used, enabling automations like the Slot Usage Limiter blueprint
  • Duplicate code detection: Detects when a lock rejects a code because it duplicates an existing one

Limitations

  • Masked PINs: Some Z-Wave locks (e.g. certain Schlage models via Z-Wave) mask PIN values. Lock Code Manager cannot read the actual PIN back. It remembers what it last wrote to each slot, so a masked PIN it wrote counts as in sync and is not re-sent after a restart.
  • No periodic re-check: Lock Code Manager relies on the lock's push updates and does not re-read the lock on a schedule. To re-read it on demand, run the lock_code_manager.hard_refresh_usercodes action.
  • Lock-specific behavior: Different Z-Wave lock brands may handle user code slots differently (e.g. slot numbering, status reporting).

Troubleshooting

Codes not syncing

Check that the Z-Wave JS integration is loaded and the lock entity is available. Verify the lock's node is not in a failed state in the Z-Wave JS control panel.

"Code rejected" errors

The lock rejected the PIN. Common causes: duplicate PIN already on another slot, or the slot is firmware-disabled. (Out-of-range PIN lengths are normally caught before reaching the lock — LCM limits the PIN field to the lock's advertised length bounds.)

Masked PINs showing as "unknown"

This is normal for locks that mask their codes. The code sensor shows the configured PIN for display purposes. After a write, LCM reads the slot back to confirm it is occupied, and treats the PIN as correct.

Clone this wiki locally