Repository navigation
Zigbee2MQTT integration
Lock Code Manager supports Zigbee locks running Zigbee2MQTT via the MQTT integration.
Zigbee2MQTT exposes lock PIN codes through MQTT topics. Lock Code Manager communicates with the lock by publishing and subscribing to these topics using the Home Assistant MQTT integration. The lock's topic is taken from the MQTT discovery data Zigbee2MQTT publishes for the lock entity.
PIN codes are readable on most Zigbee locks — the lock reports both occupancy and the actual PIN value. However, some models or firmware versions may mask PINs depending on the expose_pin setting in Zigbee2MQTT, and some locks can't report their codes at all (see Locks that can't report their codes).
- Zigbee2MQTT running and connected to Home Assistant via the MQTT integration
- A Zigbee lock that supports PIN codes (e.g., Yale, Kwikset, or similar models with the DoorLock cluster)
- The lock entity must appear as
lock.*from themqttintegration in Home Assistant
| Operation | Supported | Notes |
|---|---|---|
| Set PIN | ✅ | Via MQTT publish to zigbee2mqtt/<friendly_name>/set
|
| Clear PIN | ✅ | Via MQTT publish to zigbee2mqtt/<friendly_name>/set
|
| Read PIN | Depends | Available when expose_pin is enabled in Zigbee2MQTT; otherwise occupancy-only |
| Push updates | ✅ | Via MQTT subscription to zigbee2mqtt/<friendly_name>
|
| Code slot events | Yes | Via lock/unlock actions with user identification |
Lock Code Manager subscribes to the lock's MQTT topic and receives real-time updates when:
- A PIN code is added, modified, or cleared on the lock
- The lock reports its current user/PIN state
This means changes made at the lock keypad, via the Zigbee2MQTT frontend, or through other tools are detected without polling. Lock Code Manager does not poll the lock on a schedule; it re-reads its slots once an hour to catch anything a push update missed.
Lock Code Manager uses the topics from the lock's MQTT discovery data:
-
Subscribe:
<base_topic>/<friendly_name>— receives state updates includingusersandpin_codedata -
Get:
<base_topic>/<friendly_name>/get— requests current PIN state for individual slots -
Set:
<base_topic>/<friendly_name>/set— sets or clears PIN codes
The base topic is usually zigbee2mqtt. Custom and multi-level base topics work without any configuration, because the topic comes from the discovery data rather than being built from the device name.
- Writes are read back: After setting or clearing a PIN, Lock Code Manager reads the slot back to confirm the change. MQTT QoS 0 does not guarantee delivery, so a lost message shows up as a slot that is not yet in sync, and Lock Code Manager tries again.
- Code slot events: Lock/unlock actions with PIN identification are mapped to Lock Code Manager events via MQTT action messages.
-
expose_pinsetting: Ifexpose_pinis disabled in Zigbee2MQTT (the default on some lock models), the lock only reports whether a slot is occupied, not the actual PIN value. Lock Code Manager remembers what it last wrote to each slot, so a hidden PIN that it wrote counts as in sync and is not re-sent after a restart. - Sequential slot queries: PIN codes are fetched one slot at a time to avoid overwhelming the Zigbee mesh. This is slower than parallel queries but more reliable.
- Timeout handling: If the lock doesn't answer a slot query within 10 seconds, that slot is treated as unanswered rather than empty, so Lock Code Manager doesn't re-program a slot it simply couldn't read. If a lock that has answered before leaves every slot in a read unanswered (two or more slots), the lock is treated as unreachable.
Some lock models have expose_pin disabled by default. To enable it:
- Open the Zigbee2MQTT frontend
- Navigate to your lock device
- Go to the Settings (specific) tab
- Enable Expose pin
When expose_pin is enabled, Lock Code Manager can read back the actual PIN values and verify they match the configured PINs. When disabled, it can only see whether each slot is occupied, and relies on remembering what it wrote.
Some Zigbee locks accept PIN codes but never report them back: every slot read goes unanswered, or the lock answers with status not_supported_255 ("not supported"). Lock Code Manager detects these on its own; there is nothing to configure.
A lock that has never described any of its slots is treated as one that can't report its codes. For such a lock:
- Lock Code Manager can't see codes set at the keypad, so it treats the slots it can't see as free. When you add the lock or add users, the dialog names the lock and the slots Lock Code Manager will use on it, and warns that any code set at the keypad in those slots will be replaced. This is a notice, not a question.
- New users are placed starting from slot 1, so on these locks add codes through Lock Code Manager only, or keep any codes you set at the keypad in the highest slots.
- A slot counts as in sync when the PIN Lock Code Manager last wrote there matches the configured PIN.
- The lock card shows these slots as Not reported.
This is remembered across restarts. As soon as the lock describes a slot, it is read like any other lock. From then on, a slot it answers "not supported" for is treated as taken, so new users won't be placed there.
If a lock that can't report its codes was once taken for one that can (so new users can't be placed on it), run the lock_code_manager.hard_refresh_usercodes action with Forget that the lock can report codes (forget_reporting: true) turned on. Don't use this on a lock that does report its free slots: until it reports one again, a new user may be placed over a code set at the keypad. See Services and Actions.
Zigbee2MQTT lock support is new. The following locks have been tested:
- Yale YMF40A with Zigbee module
If you have tested Lock Code Manager with a specific Zigbee lock, please open an issue or PR to add it to this list.
Ensure the MQTT integration is loaded and the lock entity appears in Home Assistant as lock.* from the mqtt platform. Lock Code Manager identifies Zigbee2MQTT devices by their device registry identifiers (must contain zigbee2mqtt_*).
Lock Code Manager could not find the lock's topic in the MQTT discovery data Zigbee2MQTT published for the lock entity. Make sure Home Assistant discovery is enabled in Zigbee2MQTT and the lock entity comes from that discovery (not a manually configured MQTT lock). Restarting Zigbee2MQTT republishes the discovery data.
- Check that the MQTT integration is connected (Settings > Integrations > MQTT)
- Verify the lock is online in the Zigbee2MQTT frontend
- Check Home Assistant logs for MQTT publish/subscribe errors
- If PINs are hidden, enable
expose_pinin Zigbee2MQTT settings
Zigbee mesh congestion or a sleeping end device can cause timeouts. Lock Code Manager reads the slot again later and retries any write it couldn't confirm. If timeouts are frequent, check your Zigbee mesh quality and ensure the lock has good signal strength.
Getting Started
- Upgrading to 7.0
- Upgrading to 6.0
- Upgrading to 5.0
- Configuration Structure
- Adding and Removing Locks
- Migrating from keymaster
UI
Features
- Managing Guests and Rentals
- Services and Actions
- Blueprints
- Tracking lock state change events
- Using Condition Entities
- Unsupported Condition Entities
Advanced
Development
Troubleshooting
FAQ
Supported Integrations