Remote Management of Kwikset Zigbee Lock PINs via Zigbee2MQTT

If you’ve ever owned a Kwikset Zigbee smart lock, you know the “programming dance.” It usually involves standing in an open doorway, squinting at a manual, and pressing a sequence of buttons on the interior assembly while hoping you didn't miss a beep or a step.

While these locks are reliable once configured, manual management is a pain. Since I use Zigbee2MQTT to bridge my devices into Home Assistant, I wanted a way to manage user access codes remotely—without the quirky UI limitations or the physical button-mashing.

Why MQTT instead of the Zigbee2MQTT UI?

Zigbee2MQTT provides a front-end UI for managing PIN codes, but it isn't perfect. Notably, the Zigbee2MQTT documentation points out a frustrating quirk: if your PIN code starts with a zero, you cannot set it via the web interface. Presumably because it's treated as a number, and the leading 0 is stripped.

By using MQTT directly, we bypass the UI limitations and gain the ability to automate PIN management through Home Assistant scripts and automations.

Getting Under the Hood: The MQTT Commands

To manage these codes, you’ll need to publish JSON payloads to your lock’s “set” topic. In Zigbee2MQTT, this usually looks like:

zigbee2mqtt/[FRIENDLY_NAME]/set

1. Retrieving All Existing PINs

Before changing anything, it’s helpful to see what is currently stored in the lock’s memory. Sending an empty string to the pin_code attribute triggers the lock to report its current database.

Topic: zigbee2mqtt/[FRIENDLY_NAME]/set

Payload:

{"pin_code": ""}

2. Setting a New PIN

To program a code for a specific user (slot), you need to define the user ID, the type, and the status. This is particularly useful for setting temporary codes for guests or contractors.

Topic: zigbee2mqtt/[FRIENDLY_NAME]/set

Payload:

{
  "pin_code": {
    "user": 1, 
    "user_type": "unrestricted", 
    "user_enabled": true, 
    "pin_code": "1234"
  }
}

Note: Ensure your user index corresponds to the slot you want to overwrite.

3. Clearing and Disabling a PIN

When you no longer want a specific code to work, you should both clear the PIN and disable that user slot to ensure the lock state is clean.

Topic: zigbee2mqtt/[FRIENDLY_NAME]/set

Payload:

{
  "pin_code": {
    "user": 1, 
    "user_type": "unrestricted", 
    "user_enabled": false, 
    "pin_code": null 
  }
}

Integration with Home Assistant

While you can send these commands using the “MQTT Publish” service in Home Assistant, the real power comes from creating a simple Script.

I’ve set up a script that takes variables, allowing me to update codes from a dashboard without having to deal with a difficult-to-remember sequence of button presses on the lock.

By moving PIN management to MQTT, the lock becomes truly “smart.” No more manuals, no more button sequences, and total control over who has access to my home at any given time.