Skip to content

Zigbee2MQTT integration

raman325 edited this page Oct 27, 2026 · 9 revisions

Zigbee2MQTT Integration

Lock Code Manager supports Zigbee locks running Zigbee2MQTT via the MQTT integration.

How It Works

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).

Requirements

  • 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 the mqtt integration in Home Assistant

Supported Operations

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

Push Updates

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.

MQTT Topic Structure

Lock Code Manager uses the topics from the lock's MQTT discovery data:

  • Subscribe: <base_topic>/<friendly_name> — receives state updates including users and pin_code data
  • 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.

Limitations

  • 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_pin setting: If expose_pin is 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.

Zigbee2MQTT Configuration

expose_pin

Some lock models have expose_pin disabled by default. To enable it:

  1. Open the Zigbee2MQTT frontend
  2. Navigate to your lock device
  3. Go to the Settings (specific) tab
  4. 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.

Locks that can't report their codes

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.

Verified Locks

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.

Troubleshooting

Lock not detected

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_*).

"Could not determine MQTT topic"

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.

PINs not syncing

  1. Check that the MQTT integration is connected (Settings > Integrations > MQTT)
  2. Verify the lock is online in the Zigbee2MQTT frontend
  3. Check Home Assistant logs for MQTT publish/subscribe errors
  4. If PINs are hidden, enable expose_pin in Zigbee2MQTT settings

Timeout errors during PIN retrieval

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.

Clone this wiki locally