# zLock Slots

Home Assistant custom integration for managing user-code slots on Z-Wave locks,
with per-lock "last action" / "last user" tracking and a Lovelace card for
inline slot management.

Requires Home Assistant **2026.6.0 or later** and locks connected through the
built-in `zwave_js` integration.

## Installation

Install via [HACS](https://hacs.xyz/) as a custom repository
(`https://git.zi3.xyz/code/zlock_slots`, category *Integration*), or copy
`custom_components/zlock_slots/` into your HA `config/custom_components/`
directory. Restart Home Assistant, then add the integration under
**Settings → Devices & services → Add integration → zLock Slots** and select
the Z-Wave lock(s) to manage.

The integration's options (⚙ on the integration entry) let you add/remove
locks later and define **groups** — named sets of locks that publish a shared
last-action / last-user sensor.

## Entities

For each configured lock (`lock.<name>`):

| Entity | State |
|---|---|
| `sensor.<name>_last_action` | `locked` / `unlocked`, or unknown until the first event |
| `sensor.<name>_last_user` | slot name (or number), `<Manual>` for physical operation, `<Radio>` for HA/Z-Wave commands |
| `sensor.<name>_slots` | count of occupied code slots; `attributes.slots` lists `{slot_num, status, name}` |

Each group gets its own `last_action` / `last_user` sensor pair, updated by
events from any lock in the group. Last action/user survive HA restarts.

Slot names are stored by the integration (they are not written to the lock)
and are preserved when a code is cleared.

## Services

All services take `lock_entity_id` plus:

| Service | Fields | Notes |
|---|---|---|
| `zlock_slots.set_code` | `slot` (optional), `code`, `name` (optional) | Omit `slot` to auto-assign the lowest free slot |
| `zlock_slots.clear_code` | `slot` | Slot name is preserved |
| `zlock_slots.set_name` | `slot`, `name` | Set an empty name to remove it |
| `zlock_slots.set_slot_enabled` | `slot`, `enabled` | Enable/disable without changing the PIN |

Slot 0 is reserved by Z-Wave and never shown or written.

## Lovelace card

The card is registered automatically as a dashboard resource
(`/zlock_slots/zlock-slots-card.js`). If your dashboards are YAML-managed,
add it manually as a JavaScript module resource.

```yaml
type: custom:zlock-slots-card
entity: sensor.front_door_slots    # the *_slots sensor
lock_entity_id: lock.front_door
title: Front Door                  # optional
```

The card lists occupied slots with inline editing: click a name to rename it,
use the row icons to change a PIN, enable/disable, or clear a slot, and use
the form at the bottom to add a code (slot number optional — auto-assigns).

## Development

```sh
uv run pytest
```

Tests run against the pinned Home Assistant version from
`pytest-homeassistant-custom-component` (kept in sync with the minimum
supported HA release declared in `hacs.json`).