ZHA integration

ZHA (Zigbee Home Automation) Integration

Lock Code Manager supports Zigbee locks connected through the ZHA integration.

How It Works

Lock Code Manager communicates directly with the lock's zigpy DoorLock cluster through ZHA. PIN codes are read, set, and cleared using the standard ZCL DoorLock cluster commands (get_pin_code, set_pin_code, clear_pin_code).

PIN codes are readable on most Zigbee locks — the lock returns the actual PIN value, not a masked placeholder. This enables full sync verification without relying on optimistic updates.

Requirements

• ZHA integration set up and running in Home Assistant
• A Zigbee lock that supports PIN codes (e.g., Kwikset 914, Yale YRD256, or similar models with the DoorLock cluster)
• The lock entity must appear as lock.* from the zha integration in Home Assistant

Supported Operations

Operation	Supported	Notes
Set PIN	Yes	Via zigpy set_pin_code cluster command
Clear PIN	Yes	Via zigpy clear_pin_code cluster command
Read PIN	Yes	Via zigpy get_pin_code — actual PINs returned
Push updates	Yes	Via zigpy cluster listeners for operation and programming events
Code slot events	Yes	Lock/unlock with user identification via operation event notifications

Push Updates

Lock Code Manager subscribes to the DoorLock cluster as a zigpy listener and receives two types of events:

• Operation event notifications (0x20): Fired when the lock is locked or unlocked, including the source (keypad, RF, manual) and user ID. These are mapped to Lock Code Manager code slot events for automations.
• Programming event notifications (0x21): Fired when a PIN code is added, modified, or deleted on the lock. These trigger a coordinator refresh to pick up the change.

Programming Event Detection

Not all locks support programming event notifications. Lock Code Manager automatically detects support by reading the lock's event mask attributes (keypad_programming_event_mask, rf_programming_event_mask, rfid_programming_event_mask). If no mask attributes have non-zero values, Lock Code Manager falls back to hourly drift detection polling to catch out-of-band changes.

Limitations

• No user names: The ZCL DoorLock cluster does not have a concept of user names attached to PIN slots. The name parameter in async_set_usercode is accepted but ignored by the lock hardware.
• Sequential slot queries: PIN codes are fetched one slot at a time. This is slower than a bulk read but necessary because the DoorLock cluster only supports per-slot queries.
• Programming event support varies: Some lock models do not fire programming event notifications. Lock Code Manager detects this and enables drift detection as a fallback.

Verified Locks

The following locks have been tested with Lock Code Manager via ZHA:

• Kwikset 914 (ZNP coordinator over network)

If you have tested Lock Code Manager with a specific Zigbee lock via ZHA, please open an issue or PR to add it to this list.

ZHA vs Zigbee2MQTT

Both ZHA and Zigbee2MQTT support Zigbee locks, but they use different communication paths:

	ZHA	Zigbee2MQTT
Communication	Direct zigpy cluster commands	MQTT publish/subscribe
PIN readback	Direct from lock	Depends on expose_pin setting
Push updates	Cluster listener callbacks	MQTT subscription
Setup	ZHA integration only	Zigbee2MQTT + MQTT integration

Both providers support the same lock models. Choose based on which Zigbee coordinator stack you're already using.

Troubleshooting

Lock not detected

Ensure the ZHA integration is loaded and the lock entity appears in Home Assistant as lock.* from the zha platform. The lock must have a DoorLock cluster on one of its endpoints.

PINs not syncing

1. Check that the ZHA integration is connected (Settings > Integrations > ZHA)
2. Verify the lock is online (check the device page for availability)
3. Check Home Assistant logs with debug logging enabled for custom_components.lock_code_manager

"DoorLock cluster not available"

Lock Code Manager could not find a DoorLock cluster on the device. This may happen if:

• The lock was just paired and hasn't finished initializing
• The device is a lock that doesn't expose the DoorLock cluster (unusual)

Try removing and re-pairing the lock with ZHA.