Skip to content

Commit b099914

Browse files
Ahbrown41Ahbrown41
committed
Added docs for the new Matter lock integration
1 parent f8ebdc7 commit b099914

File tree

1 file changed

+221
-0
lines changed

1 file changed

+221
-0
lines changed

‎source/_integrations/matter.markdown‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -365,6 +365,13 @@ The Home Assistant Matter updates currently do not work for Thread devices on a
365365
The Matter integration has the following actions:
366366

367367
- `matter.water_heater_boost`
368+
- `matter.set_lock_user`
369+
- `matter.clear_lock_user`
370+
- `matter.get_lock_info`
371+
- `matter.get_lock_users`
372+
- `matter.set_lock_credential`
373+
- `matter.clear_lock_credential`
374+
- `matter.get_lock_credential_status`
368375

369376
### Action: Water heater boost
370377

@@ -376,6 +383,220 @@ The `matter.water_heater_boost` action enables water heater boost for a specific
376383
| `emergency_boost` | Yes | Whether to enable emergency boost mode |
377384
| `temporary_setpoint` | Yes | Temporary setpoint temperature in Celsius during the boost period |
378385

386+
### Lock user and credential management
387+
388+
The following actions let you manage users and credentials (such as PIN codes and RFID tags) on Matter-compatible locks. Your lock must support the Matter Door Lock cluster user and credential management features for these actions to work.
389+
390+
{% note %}
391+
Not all Matter locks support user and credential management. Use the `matter.get_lock_info` action to check what your lock supports before attempting to manage users or credentials.
392+
{% endnote %}
393+
394+
### Action: Set lock user
395+
396+
The `matter.set_lock_user` action creates or updates a user on the lock. If you omit the `user_index`, the lock automatically assigns the next available slot.
397+
398+
- **Data attribute**: `user_index`
399+
- **Description**: The user slot index (1-based). Leave empty to let the lock automatically find an available slot.
400+
- **Required**: No
401+
402+
- **Data attribute**: `user_name`
403+
- **Description**: A name for the user.
404+
- **Required**: No
405+
406+
- **Data attribute**: `user_type`
407+
- **Description**: The type of user to create.
408+
- **Required**: No
409+
- **Options**:
410+
- `unrestricted_user`: A regular user with no access restrictions.
411+
- `year_day_schedule_user`: Access is limited to specific date ranges.
412+
- `week_day_schedule_user`: Access is limited to specific days and times each week.
413+
- `programming_user`: A user who can manage other users and credentials on the lock.
414+
- `non_access_user`: A user record that exists on the lock but cannot unlock it.
415+
- `forced_user`: A user whose access triggers a special alarm or notification, for example a duress code.
416+
- `disposable_user`: A user whose credential is automatically revoked after a single use.
417+
- `expiring_user`: A user whose access expires after a set period.
418+
- `schedule_restricted_user`: A user restricted by both week-day and year-day schedules.
419+
- `remote_only_user`: A user who can only operate the lock remotely, not from the physical keypad.
420+
421+
- **Data attribute**: `credential_rule`
422+
- **Description**: The credential rule for the user. Determines how many credentials must be presented to unlock.
423+
- **Required**: No
424+
- **Options**:
425+
- `single`: One credential is required to unlock (for example, just a PIN).
426+
- `dual`: Two different credentials are required to unlock (for example, a PIN and an RFID tag).
427+
- `tri`: Three different credentials are required to unlock.
428+
429+
```yaml
430+
action: matter.set_lock_user
431+
target:
432+
entity_id: lock.front_door
433+
data:
434+
user_name: "Jane"
435+
user_type: unrestricted_user
436+
credential_rule: single
437+
```
438+
439+
### Action: Clear lock user
440+
441+
The `matter.clear_lock_user` action deletes a user and all their associated credentials from the lock. To clear all users at once, use index `65534`. This is a special value defined by the Matter specification (hex `0xFFFE`) that tells the lock to remove every user.
442+
443+
- **Data attribute**: `user_index`
444+
- **Description**: The user slot index (1-based) to clear. Use `65534` to clear all users at once.
445+
- **Required**: Yes
446+
447+
```yaml
448+
# Remove a single user
449+
action: matter.clear_lock_user
450+
target:
451+
entity_id: lock.front_door
452+
data:
453+
user_index: 3
454+
```
455+
456+
```yaml
457+
# Remove all users
458+
action: matter.clear_lock_user
459+
target:
460+
entity_id: lock.front_door
461+
data:
462+
user_index: 65534
463+
```
464+
465+
### Action: Get lock info
466+
467+
The `matter.get_lock_info` action returns the lock's capabilities, including supported credential types, maximum number of users, and PIN length constraints. This action returns a response and does not require any additional data attributes.
468+
469+
```yaml
470+
action: matter.get_lock_info
471+
target:
472+
entity_id: lock.front_door
473+
response_variable: lock_info
474+
```
475+
476+
### Action: Get lock users
477+
478+
The `matter.get_lock_users` action returns all users configured on the lock along with their associated credentials. This action returns a response and does not require any additional data attributes.
479+
480+
```yaml
481+
action: matter.get_lock_users
482+
target:
483+
entity_id: lock.front_door
484+
response_variable: lock_users
485+
```
486+
487+
### Action: Set lock credential
488+
489+
The `matter.set_lock_credential` action adds or updates a credential on the lock. If you omit the `credential_index`, the lock automatically assigns the next available slot. If you omit the `user_index`, a new user is created for the credential. This action returns a response containing the assigned credential and user indices.
490+
491+
- **Data attribute**: `credential_type`
492+
- **Description**: The type of credential to set.
493+
- **Required**: Yes
494+
- **Options**:
495+
- `pin`: A numeric PIN code entered on the lock's keypad.
496+
- `rfid`: An RFID tag or card tapped against the lock's reader.
497+
- `fingerprint`: A fingerprint registered on the lock's biometric sensor.
498+
- `finger_vein`: A finger-vein pattern registered on the lock's biometric sensor.
499+
- `face`: A facial recognition profile registered on the lock.
500+
501+
- **Data attribute**: `credential_data`
502+
- **Description**: The credential data to store. For `pin` credentials, use digits only (for example, `1234`). For `rfid` credentials, use a hexadecimal string representing the tag ID (for example, `AABBCCDD`).
503+
- **Required**: Yes
504+
505+
- **Data attribute**: `credential_index`
506+
- **Description**: The credential slot index (0-based). Leave empty to let the lock automatically find an available slot.
507+
- **Required**: No
508+
509+
- **Data attribute**: `user_index`
510+
- **Description**: The user index (1-based) to associate the credential with. Leave empty to have the lock automatically create a new user.
511+
- **Required**: No
512+
513+
- **Data attribute**: `user_status`
514+
- **Description**: The user status to set when creating a new user for this credential.
515+
- **Required**: No
516+
- **Options**:
517+
- `occupied_enabled`: The user is active and can use their credentials to unlock.
518+
- `occupied_disabled`: The user exists but their credentials are temporarily disabled.
519+
520+
- **Data attribute**: `user_type`
521+
- **Description**: The user type to set when creating a new user for this credential. See the `matter.set_lock_user` action for a description of each user type.
522+
- **Required**: No
523+
524+
```yaml
525+
# Add a PIN to an existing user
526+
action: matter.set_lock_credential
527+
target:
528+
entity_id: lock.front_door
529+
data:
530+
credential_type: pin
531+
credential_data: "1234"
532+
user_index: 1
533+
response_variable: result
534+
```
535+
536+
```yaml
537+
# Add an RFID tag and let the lock create a new user
538+
action: matter.set_lock_credential
539+
target:
540+
entity_id: lock.front_door
541+
data:
542+
credential_type: rfid
543+
credential_data: "AABBCCDD"
544+
response_variable: result
545+
```
546+
547+
### Action: Clear lock credential
548+
549+
The `matter.clear_lock_credential` action removes a credential from the lock.
550+
551+
- **Data attribute**: `credential_type`
552+
- **Description**: The type of credential to remove. See the `matter.set_lock_credential` action for a description of each credential type.
553+
- **Required**: Yes
554+
555+
- **Data attribute**: `credential_index`
556+
- **Description**: The credential slot index (0-based) to clear.
557+
- **Required**: Yes
558+
559+
```yaml
560+
action: matter.clear_lock_credential
561+
target:
562+
entity_id: lock.front_door
563+
data:
564+
credential_type: pin
565+
credential_index: 1
566+
```
567+
568+
### Action: Get lock credential status
569+
570+
The `matter.get_lock_credential_status` action returns the status of a specific credential slot on the lock, including whether the slot is occupied and which user it belongs to. This action returns a response.
571+
572+
- **Data attribute**: `credential_type`
573+
- **Description**: The type of credential to query.
574+
- **Required**: Yes
575+
- **Options**:
576+
- `programming_pin`: A special administrative PIN used to manage the lock at the keypad.
577+
- `pin`: A numeric PIN code entered on the lock's keypad.
578+
- `rfid`: An RFID tag or card tapped against the lock's reader.
579+
- `fingerprint`: A fingerprint registered on the lock's biometric sensor.
580+
- `finger_vein`: A finger-vein pattern registered on the lock's biometric sensor.
581+
- `face`: A facial recognition profile registered on the lock.
582+
- `aliro_credential_issuer_key`: An Aliro credential issuer key (used by Aliro-compatible locks for NFC-based access).
583+
- `aliro_evictable_endpoint_key`: An Aliro endpoint key that the lock can remove when it runs out of space.
584+
- `aliro_non_evictable_endpoint_key`: An Aliro endpoint key that the lock must keep and cannot automatically remove.
585+
586+
- **Data attribute**: `credential_index`
587+
- **Description**: The credential slot index (0-based) to query.
588+
- **Required**: Yes
589+
590+
```yaml
591+
action: matter.get_lock_credential_status
592+
target:
593+
entity_id: lock.front_door
594+
data:
595+
credential_type: pin
596+
credential_index: 1
597+
response_variable: credential_status
598+
```
599+
379600
## Automate on a button press
380601

381602
You have a device that takes button presses as inputs (such as a Tuo Smart Button, VTM31SN dimmer by Inovelli, or the Matter Pushbutton Module by Innovation Matters) and now want to trigger an automation based on that button press. To learn how to create an automation triggered by a button press, refer to this [tutorial](/integrations/event/#automating-on-a-button-press).

0 commit comments

Comments
 (0)