Zigbee2MQTT integration

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. Each lock is identified by its Zigbee2MQTT friendly name, which is resolved from the device registry.

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.

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 quickly without waiting for the next poll.

Polling still occurs as a fallback (every 5 minutes) and a hard refresh runs every hour to catch any missed updates.

MQTT Topic Structure

Lock Code Manager uses the standard Zigbee2MQTT topic layout:

• Subscribe: zigbee2mqtt/<friendly_name> — receives state updates including users and pin_code data
• Get: zigbee2mqtt/<friendly_name>/get — requests current PIN state for individual slots
• Set: zigbee2mqtt/<friendly_name>/set — sets or clears PIN codes

The base topic (zigbee2mqtt) is auto-detected from the device registry. Custom base topics are supported.

Limitations

• Optimistic updates: After setting a PIN, Lock Code Manager optimistically assumes success. MQTT QoS 0 does not guarantee delivery, so if the message is lost, the actual state may diverge until the next hard refresh (up to 1 hour). This is the same pattern used by other push-based providers.
• 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 treats unreadable PINs as UNREADABLE_CODE and re-sets them on restart to guarantee correctness.
• 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 a slot query times out (10 seconds), the slot is reported as UNREADABLE_CODE rather than empty, preventing unnecessary re-programming.

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 relies on occupancy status and optimistic updates.

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 resolve the Zigbee2MQTT friendly name from the device registry. Ensure the lock has a device entry with a name that matches its Zigbee2MQTT friendly name.

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 show as "unreadable", 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 will retry on the next poll cycle. If timeouts are frequent, check your Zigbee mesh quality and ensure the lock has good signal strength.