Usage

How it works

Each code slot has an Active binary sensor and a Sync Status sensor.

Keymaster writes a PIN to the physical lock only when the slot is active.
If a slot becomes inactive, disabled, or cleared, Keymaster removes that PIN from the lock.

Lock Provider Types

How Keymaster communicates with your lock depends on the provider:

• Native/Direct Providers (Z-Wave JS, ZHA, Zigbee2MQTT)
  These providers directly query and modify user codes on the lock's hardware memory slots.
• Virtual Mapping Providers (Schlage WiFi, Local Akuvox)
  These platforms do not support direct slot manipulation APIs. Keymaster manages codes virtually by prefixing tags or modifying user attributes (e.g. prefixing tags to code names or door controller user names) to map virtual slots to their respective profiles.

How Keymaster Gets & Sets Codes

Keymaster uses a state-driven synchronization loop to keep the physical lock and Home Assistant in sync:

1. Retrieving Codes (GET): When Keymaster starts or detects an update, it queries the provider using async_get_usercodes() to fetch the active PINs and slots.
   • Supported Platforms: Z-Wave JS and Zigbee2MQTT support querying the lock for its stored user codes.
   • Limitations (e.g., ZHA): ZHA uses the standard Zigbee get_pin_code command, which is unsupported by many Zigbee locks. In these cases, Keymaster falls back to using its local state cache to track active PINs.
2. Synchronizing State (SET/CLEAR):
   • When a slot should be active (rules pass) but the lock does not have the correct PIN, Keymaster puts the slot into the Adding sync state and calls async_set_usercode() to write the PIN to the lock.
   • When a slot should be inactive (rules fail, or code is cleared) but the lock still has a PIN set, Keymaster puts the slot into the Deleting sync state and calls async_clear_usercode() to erase the PIN from the lock.
   • Once the lock confirms the change, the sync status changes to Synced.

What makes a slot Active

A slot is active when all enabled rules pass:

• Enabled is on
• PIN exists (PIN entry from the UI requires numeric values with 4+ digits)
• Limit by Number of Uses is either off, or Uses Remaining is greater than 0
• Limit by Date Range (if enabled) is currently in range
• Limit by Day of Week (if enabled) allows the current day/time

If a slot unlocks the door and Limit by Number of Uses is enabled, Uses Remaining is decremented.

For day/time limits, each day supports:

• enable/disable the day
• optionally enforce a time window
• include or exclude that time window

PIN Status

Code Slot X: Sync Status reflects whether Home Assistant and the lock agree on the PIN state.

Status	Meaning
Adding	PIN is being written to the lock
Deleting	PIN is being cleared from the lock
Synced	Keymaster and lock are in sync
Out of Sync	The lock reported a different numeric PIN than expected
Disconnected	Slot is inactive/cleared or lock connection is unavailable