Lockly

Lockly is a Home Assistant integration and Lovelace card for managing PIN slots on Zigbee2MQTT smart locks. Keep household access in one place: edit a slot, push changes to one lock or many, and see who came in.

Screenshots and Features

See slot status at a glance Color-coded rows show enabled vs. disabled slots plus queued/updating states during bulk operations.
See who unlocked your doors The Lock Activity card shows recent lock events across all your managed locks — who unlocked, how, and when. Redundant events (firmware echoes, duplicate automation commands) are automatically collapsed. Toggle between a chronological feed and a per-lock summary that highlights the last identified user. Click any entry to jump to that lock's history.
Edit slots in a focused dialog Update a slot's name, PIN, or enabled state with inline validation as you type. The action button knows when a change is local only and when it needs to reach the lock, and labels itself accordingly.
Pick the locks each card manages The card configuration dialog opens on a Locks tab where you select individual locks or whole groups directly from the Lovelace editor, with a live preview alongside.
Tweak behavior in Settings Hide PINs from non-admins, run in simulation mode without touching MQTT, and toggle the Apply all button on or off.
Grant access to specific people The Admins tab lets non-admin Home Assistant users see PINs and edit slots. Pick them from your list of people.
Manage multiple configurations Run separate Lockly entries for different homes, buildings, or lock groups, each with its own slots and MQTT settings.

What you can do

• Run multiple Lockly configurations side by side for different lock groups.
• Add, edit, enable, or remove lock slots on demand.
• Update slot name and PIN with inline validation and clear error feedback.
• Apply a single slot to all selected locks.
• Apply all enabled slots in one action with queued/updating progress.
• Wipe slots from locks when you need a clean slate.
• Restrict PIN visibility and edits to admins only (plus optionally grant that ability to other specified users).
• Simulate changes without sending MQTT commands.
• Choose a Lockly instance per card and preview the card live while configuring.
• Pick locks and lock groups directly from the visual editor.
• Track lock activity — see who unlocked each door, when, and how (keypad, RFID, manual, automation).
• Smart deduplication collapses firmware echoes and redundant automation locks while preserving the raw event log.
• Per-lock view shows the last identified user who unlocked each door, so you always know who came in.
• Activity data persists across restarts and integrates with HA's built-in logbook.
• Reconstruct activity history from Zigbee2MQTT logs with the included replay tool.

Installation (HACS)

This integration is available directly in HACS under the Integration category. Requires Home Assistant 2026.4.0 or newer.

1. Add this repository to HACS as a custom repository.
2. Install the integration from HACS.
3. Restart Home Assistant when prompted.

Manual install (without HACS)

1. Copy the custom_components/lockly folder from this repository into your Home Assistant config/custom_components/ directory.
2. Restart Home Assistant.

Configuration

1. Go to Settings > Devices & Services and add the Lockly integration.
2. Set the first and last slot, MQTT base topic, and update endpoint.

Lovelace Card

This integration ships with a bundled Lovelace card, so you can add it the usual way from the dashboard UI.

If you prefer YAML mode, add the card manually:

type: custom:lockly-card
entry_id: YOUR_ENTRY_ID
title: Lockly
lock_entities:
  - lock.front_door
  - group.downstairs_locks
admin_only: true
dry_run: true
admin_users:
  - person.alice

To find the entry ID, open the Lockly integration in Settings > Devices & Services and copy the entry ID shown in the options dialog.

Activity Card

The Lock Activity card shows recent lock events — who unlocked, the method, and when. It supports two views: Recent (chronological) and Per Lock (latest event per lock with the last identified unlocker). Whichever view you pick from the in-card toggle sticks per browser across reloads. Activity survives HA restarts and also appears as rich entries in the built-in logbook.

Events are stored raw and deduplicated at display time, so no data is lost:

• Firmware echoes — manual_lock + lock(rf) pairs from a single Zigbee command are collapsed into one "Locked (AUTOMATION)" entry (5 s window).
• Same-action repeats — duplicate lock commands from overlapping automations are collapsed, keeping the first (5 s window).
• Deliberate physical + redundant automation — a one_touch_lock followed by a redundant automation lock keeps the physical action (60 s window).

type: custom:lockly-activity-card
entry_id: YOUR_ENTRY_ID
title: Lock Activity
view: recent
max_events: 5

Slot Management Card

The card editor opens on a Locks tab where you pick which locks or lock groups this card manages. The Settings tab holds three toggles: hide PINs from non-admins, run in simulation mode (no MQTT), and show or hide the Apply all button. The Admins tab lets specific Home Assistant users see PINs and edit slots without granting them HA admin — pick them from your list of people. The in-card "All vs Enabled only" filter is remembered per browser across reloads.

How it works

• Each Lockly integration entry represents a group of slots you manage together.
• Slots are stored in Home Assistant and applied to one or more locks as needed.
• The card shows live state (queued, updating, timeout) and gives you a clear, consistent edit flow.

Resource registration

• Storage mode (default): the integration registers the card automatically.
• YAML mode: add a resource pointing to /lockly/lockly-card.js (type module).

Services

• lockly.add_slot
• lockly.remove_slot
• lockly.apply_slot
• lockly.push_slot
• lockly.apply_all
• lockly.update_slot
• lockly.export_slots
• lockly.import_slots

See custom_components/lockly/services.yaml for fields and descriptions.

Rebuilding Activity from Z2M Logs

If you want to reconstruct your activity history from Zigbee2MQTT log files (e.g. after a fresh install, or to iterate on dedup rules without losing data), use the included replay script:

# Preview parsed events
python scripts/replay_z2m_log.py /path/to/z2m/log.log --tz-offset -8

# Write directly to the HA store, resolving slot names automatically
python scripts/replay_z2m_log.py /path/to/z2m/log.log \
    --tz-offset -8 \
    --slots-store /config/.storage/lockly_slots.YOUR_ENTRY_ID \
    --store-path /config/.storage/lockly_activity.YOUR_ENTRY_ID

Stop HA before writing and restart it afterward so the integration picks up the new data. The --slots-store flag reads slot-to-name mappings from the existing Lockly slots file; use --slots '{"7": "Name"}' for manual overrides.

Export & Import

To move data between environments, export slots from one instance and import them into another:

1. In production, call lockly.export_slots with your entry_id.
2. Copy the returned JSON (the slots array).
3. In dev, call lockly.import_slots with the entry_id and a payload containing the JSON.

Use include_pins: true when exporting if you want PINs included. The import will overwrite slots by default; set replace: false to merge instead.

Credits

• The per-browser persistence pattern used by the slot card's "All vs Enabled only" filter and the activity card's "Recent vs Per Lock" view follows the model established by Alia5/lovelace-expander-card, which uses localStorage to remember its expanded/collapsed state across reloads. Thanks to Alia5 for the clean pattern.