Support PIN management for Matter DoorLock

[Leah-Anderson]

Describe the enhancement

Setting up a Yale matter door lock enables control of the lock but there is no way within homeassistant to configure passcodes for the device. The only way I found to do so was to share the device with google home and configure the passcodes within the google home app. Ideally this would be capable within homeassistant

Device or feature details

Device: Yale Smart Lock with Matter (33040)
Firmware: 1.0.1+0

Use cases

Fully support a matter door lock from within homeassistant without requiring a 3rd party ecosystem.

Anything else?

No response

[Particpant]

This is missing from zwave locks, as well (though zwave js UI does provide a way to directly access the code assignments.)

[Leah-Anderson]

For what it's worth there are at least service/action calls to set user codes for zwavejs. I can't speak to if there's some aspect of functionality of them that is lacking but figured I'd mention it in case it was helpful.

[Pr0bably]

Matter – Missing support for PIN/RFID on Aqara Smart Lock U200

Hello. I recently migrated the Aqara Smart Lock U200 from SmartThings to Home Assistant via Matter. The lock/unlock function and status work fine, but I discovered that all functionality for managing codes and RFID tags is missing.

In SmartThings, I could create, edit, and delete codes directly, and it was possible to see who unlocked the door. The Matter standard does have support for this (Door Lock User / Door Lock Credential clusters), so it should be possible to expose it in HA as well.

For those of us who actively use the lock with multiple users and temporary codes, this is a fairly significant limitation. I would therefore like for HA's Matter integration to get support for:

Creating, editing, and deleting PIN codes

Managing RFID tags and fingerprints if posible :)

Viewing the event log to see which user unlocked the door

These are features that already exist in the Aqara app and worked in SmartThings, so it's a shame to lose them when transitioning to HA. I hope this can be prioritized – the Matter part is there, it's just the implementation in HA that is missing.

Thank you for looking into this.

— Probably

[tailg8nj]

I've created a workaround.

Download / clone the file matter_door_lock.py.

Place the matter_door_lock.py in your Home Assistant configuration directory and add the following to configuration.yaml:

shell_command:
  matter_door_lock: ./matter_door_lock.py --nodeId {{node_id}} {{sub_command}}

You can then create a script which executes the file:

To get the device node ID:

sequence:
  - action: shell_command.matter_door_lock
    data:
      node_id: >-
        {% set entity_id = 'lock.yale_smart_lock_with_matter' %}
        {% set device_id = device_id(entity_id) %}
        {% set matter_id = device_attr(device_id, 'identifiers') | selectattr(0, 'eq', 'matter') |
           map(attribute=1) | select('match', 'deviceid_.*') | first %}
        {% set node_id = matter_id.split('-')[1] | int(base=16) %}
        {{ node_id }}
      sub_command: >-
        set-user --userIndex {{ user_index }} --userName {{ user_name }}
        --userUniqueID {{ unique_id }} --userType {{user_type}}
    response_variable: response
fields:
  user_index:
    selector:
      text: null
    required: true
    name: User Index
  unique_id:
    selector:
      text: null
    name: Unique Id
    required: true
  user_name:
    selector:
      text: null
    name: User Name
    required: true
  user_type:
    selector:
      text: null
    name: User Type
    required: true
    description: |-
      kUnrestrictedUser
      kYearDayScheduleUser
      kWeekDayScheduleUser
      kProgrammingUser
      kNonAccessUser
      kForcedUser
      kDisposableUser
      kExpiringUser
      kScheduleRestrictedUser
      kRemoteOnlyUser
alias: Set Lock User
description: ""

If this is worth additional investment let me know, or if there is a clear direction on how to add users / pins in Home Assistant I can refactor and contribute!

[raman325]

@tailg8nj regarding changes in core. I am not familiar with the matter code so I can't speak in too much detail about it, but I think you would want to register entity services in the lock platform and there you can register entities conditionally based on cluster discovery. zwave_js obviously doesn't have the concept of clusters but look at the lock platform module for the integration if you want some hints on how to do it.

As for my integration, I had Claude Code generate this but I don't know the matter standard or code well enough to audit the code yet and I have no matter locks to test with: raman325/lock_code_manager#741

If you are interested in seeing this PR through, you are welcome to take over the branch (basically just copy it down to your repo) and make the fixes to submit a new PR and I will close this one. Alternatively, feel free to test and/or comment on the PR, I'll take whatever form of help I can get!

[Hedda]

regarding changes in core. I am not familiar with the matter code so I can't speak in too much detail about it, but I think you would want to register entity services in the lock platform and there you can register entities conditionally based on cluster discovery. zwave_js obviously doesn't have the concept of clusters but look at the lock platform module for the integration if you want some hints on how to do it.

@raman325 could this new platform for registering service actions that is being worked on as draft for core by epenet maybe also be useful?

• POC Add service actions platform core#161658

[tailg8nj]

I think these links give me a good starting point. I'll circle back when I have something.

If I place something like this in services.yaml:

lock_set_user:
  target:
    entity:
      domain: lock
      integration: matter

It should restrict the service action to only lock entities within the matter integration, basically matching matter clusters that have this attribute: https://github.com/home-assistant/core/blob/91a3e488b103b82d2dd56f1df540f87a15c33cd7/homeassistant/components/matter/lock.py#L268

[tailg8nj]

Just looked at the lock_code_manager draft as well, and I'm not seeing a separation of user and credential concepts (please correct me if I'm wrong). Although that could be obfuscated from the end user if we want with some simple strategy (like creating a separate user for each credential).

[raman325]

Right now there is no distinction between credential types. That's something I'll add, need to figure out how to generalize a solution across integrations

[contactpb]

Ignore my earlier comment about aiohttp/chip imports, this was a red herring...

In the Home Assistant Traces I see the following:

Executed: January 12, 2026 at 8:54:29 PM
Result:
params:
  domain: shell_command
  service: matter_door_lock
  service_data:
    node_id: ''
    sub_command: >-
      set-user --userIndex 1 --userName user --userUniqueID 1234 --userType
      kUnrestrictedUser
  target: {}
running_script: false

response:
  stdout: ''
  stderr: |-
    usage: matter_door_lock.py [-h] --nodeId NODEID [--timeout TIMEOUT]
                               {set-user,get-user,clear-user,set-credential,get-credential,clear-credential} ...
    matter_door_lock.py: error: argument --nodeId: invalid int value: 'set-user'
  returncode: 2

So it appears all arguments are being passed to matter_door_lock.py except for nodeId.

If I test the logic in Template editor node_id is correctly returned.

{% set matter_id = device_attr(device_id, 'identifiers') | selectattr(0, 'eq', 'matter') | map(attribute=1) | select('match', 'deviceid_.*') | first %}
{{ matter_id }} ===>>> deviceid_1234567890123456-000000000000000D-MatterNodeDevice
{% set node_id = matter_id.split('-')[1] | int(base=16) %}
{{ node_id }} ===>>> 13

I'll try to dig into this further, but let me know if you see anything obvious.

[tailg8nj]

Can you share the top half of your script as well as the configuration.yaml snippet for shell_command?

[contactpb]

I migrated to the latest script (set matter_id -> set identifier) and that seems to have resolved the null --nodeId. It now returns 0 when run with the following:

user_index: '1'
unique_id: '1234'
user_name: user
user_type: kUnrestrictedUser

However if I try to lock 'lock.yale_smart_lock_with_matter' I get the code request and then:

[123456789012345] Error during service call to lock.lock: InteractionModelError: Failure (0x1)

The code also doesn't work from the keypad.

I can't see anything obvious in the Matter Server under Node 13 that would help debug (i.e. # assigned user codes).

Any thoughts?

Thanks

[tailg8nj]

The unique ID is not a pin. You need a subsequent set-credential call. See the readme for an example, I elaborated a bit more in it today.

[contactpb]

Thanks - up and running now - really appreciate the hard work that went in to this!

[Hedda]

FYI, I posted a new feature request for a universal lock user code manager that would apply to all locks instead of just Matter protocol, see here:

• https://github.com/orgs/home-assistant/discussions/2555

Regardless of that, developers who have input on this would probably also want to contribute idea and feedback to this architecture discussions:

• Native lock code functionality architecture#1000

Those discussions also have links to custom components for lock managers where a developer is working on adding cross-protocol support. See:

• https://github.com/raman325/lock_code_manager

and

• https://github.com/FutureTense/keymaster/

[tailg8nj]

Looks like a few days ago this was pushed up in PR home-assistant/core#161936 and based on it's contents it would probably supersede this work.

[tailg8nj]

The YRD510 supports SetUser/GetUser/ClearUser. Are you saying that home assistant is reporting it only supports pin? My script mentioned above in https://github.com/orgs/home-assistant/discussions/551#discussioncomment-15471048 was written and tested against the YRD510.

[keck9939]

According to the new matter lock support, yes, the YRD510 only supports PIN. However, looking at the FeatureMap via the MatterServer, it is 1457. Bit 8 of this (USR) is 1, so it should support USR.

[tailg8nj]

Unfortunately the lock is at a different location so I can't confirm anything readily. But another user above also had success with the same model. It does require a user in order to add a pin. Either it's not reporting it correctly for your firmware, or for all versions, or we're checking the wrong endpoint or something. Can you report back using the script / matter server and the set user command?

[keck9939]

You probably saw my unedited reply. The feature map is decimal not hex. With this change USR is supported. So there is a discrepancy.
I will give your script a try.

[tailg8nj]

It sounds as if this code path isn't working as intended for that model on 2026.4.0:

https://github.com/home-assistant/core/blob/375bd55ae6ea27814de1eaaf7c66846c4e767dc5/homeassistant/components/matter/lock_helpers.py#L149

It probably warrants a bug for the matter component.

Unfortunately I won't be able to test with mine for a few weeks, but some debug statements there would be a great start.

[keck9939]

Unfortunately, I'm not a Python expert so I can't judge.
I was able to use your script to add a user and PIN. Interestingly, after doing so, the Matter integration showed 2 users, one I did not create, but looks like it might be built in, and the one I did create where previously it showed no users. More interestingly, it then allowed me to add another user and PIN where previously it failed with an unknown error. So, it seems that using your integration to add the first user/PIN gets it to a state where the integration works.

The lock of course did have a user and PIN, but it was set on another fabric (Google Home) which I was using because Home Assistant could not set PINS. The lock was also joined to the Home Assistant fabric, but as I understand it, users and PINS and maintained separately by each fabric and one fabric cannot see the other's users.

Edit: Looking at the Matter server logs, it appears this lock probably does not keep user info by fabric. The unknown entry would appear to be some kind of hash of the user created with Google Home.

[Hedda]

FYI, the custom Lock Code Manager integration componest just added a new lock provider for Matter locks as well if want some additional features like sync codes between different locks and ability to schedule when codes should be enabled (and more via Blueprint automations):

• https://github.com/raman325/lock_code_manager

For reference, Lock Code Manager is a custom component integration (that can be installed via HACS) which adds severql additipnal lock related features and functions which are not yet supported in Home Assistant’s core:

• https://github.com/raman325/lock_code_manager/blob/main/README.md

  Lock Code Manager is a Home Assistant integration that allows you to more easily manage your usercodes on your locks. Once you have configured it, the integration will set and clear codes on your locks as needed depending on how you decide to configure them.

  Features:

  • Synchronize multiple locks with a single set of codes
  • Optionally use a condition entity to control when a code is active. Supported entity types:
    • calendar - code is active when an event is in progress
    • binary_sensor - code is active when the sensor is on
    • switch - code is active when the switch is on
    • schedule - code is active when the schedule is on
    • input_boolean - code is active when the input boolean is on
  • Optionally define a maximum number of uses for a code before the code is disabled

Lock Code Manager currently support Z-Wave + virtual locks via the Virtual custom integration component (also available via HACS):

• https://github.com/twrecked/hass-virtual

  • https://github.com/raman325/lock_code_manager/wiki/Virtual-integration

    "The Virtual integration allows users to set up "virtual" entities of different types. One of those entity types is locks.

    The reason support for this integration was added is because it can be used to test Lock Code Manager functionality without affecting your main locks. Because Virtual locks don't have support for setting and clearing user codes, the way this works is that user codes are persisted to disk as you set them. If you remove a Virtual lock from your configuration, the file will be removed to keep your file system clean.

    If you are curious about Lock Code Manager and don't want to impact any existing locks functionality, I would encourage you to try setting up Lock Code Manager with Virtual locks first!

    The way Virtual locks integrate with LCM is not set in stone. If you have ideas on how to make support for these locks better, please open an issue."

PS: Lock Code Manager integration has in turn taken a lot of inspiration from the keymaster interation but taken it to the next level.

[lboue]

This seems to be addressed in the following request and the latest version:

• Add Matter lock user and credential management services core#161936

[zeryors]

Perhaps we could implement a feature where Lock-type entities require unlocking via your mobile device's security method (fingerprint, pattern, PIN, etc.).
Additionally, we could add a permissions manager at the entity level for users and groups.

[mkerstner]

As @lboue mentioned this functionality is addressed on our public roadmap:

• Credential management for Matter locks OpenHomeFoundation/roadmap#69

More recently, there was another improvement in home-assistant/frontend#51293

In general, we aim to further streamline credential management, starting with Matter locks and proceeding with Z-Wave, more info here to engage further OpenHomeFoundation/roadmap#8

• Credential management for Matter locks OpenHomeFoundation/roadmap#69
• Credential management for Z-Wave locks OpenHomeFoundation/roadmap#70