Native lock code functionality

[raman325]

CC @AlCalzone @marcelveldt for input from a Z-Wave/Matter perspective

Background

The lock platform natively allows users to control the lock state of a lock, but it is not possible, at least natively, to manage codes for the lock. While not all locks have this functionality, many integrations/protocols support this, including zwave_js, zigbee, matter, and proprietary WiFi/BLE locks.

Today, integrations are forced to handle lock code management on their own. For zwave_js, there are zwave_js specific services to manage user codes, but there isn't a native UI that makes them easily manageable. As a result, there are integrations like https://github.com/FutureTense/keymaster which hack together a solution using a combination of the HA packages functionality, input helpers, and automations. In addition to generating a lot of artifacts which pollute a user's instance, the UI that gets created is not optimized for the use case and is quite complex given what it's trying to accomplish.

Purpose

The purpose of the initial proposal is to come to a consensus that a new entity platform is needed to support codes. There are a lot of details to iron out about this platform, and we can discuss that as a follow up, but I first want to come to consensus that this is needed and that we can't use what we already have.

Considerations

• Not all locks support codes
• Codes can be of variable length and an integration may need to enforce some rules on them
• While most locks with codes that I have seen use PIN numbers, we should consider a scenario where alphanumeric characters may want to be used
• We may also want to consider locks that don't have user defined codes but user configurable identifiers such as an RFID tag for this use case.
• There may be additional metadata about a code that can't be stored in the lock itself that integrations would want to keep track of, such as assigning a name/person entity to a code.

Options

Option 1: Leave things as is and let integrations create their own solutions

We could choose to do nothing and to continue to let each integration figure this out. Integrations can provide a lot of this functionality through services, and when entity services support responses, most if not all of it will be available.

Pros:

• No additional work required in the core or frontend
• Users who already have a solution in place can continue to use that solution

Cons:

• Every integration would have to build its own UI for managing codes if that was desired/needed
• It would be difficult for users to mix and match locks from different integrations because their automations would have to be integrations specific

Considerations:

• We would have a difficult time obtaining Z-Wave certification for HA. See User Code CC support zwave-js/certification-backlog#25 for specific requirements.
• This may also affect a future Matter certification although I am less knowledgeable about what's required there.

Option 2: Use existing HA constructs

Now that most of the input helpers have corresponding entity platforms, integrations could cobble together their own collection of entities that can be used to manage user codes. text entities could be used to view and set codes (and names), and a switch could be exposed to allow codes to be enabled/disabled.

Pros:

• No additional work required in the core or frontend
• Platforms like the text entity already support regex validation and could be used to enforce requirements on the code
• Integrations can add support for this today.

Cons:

• My Z-Wave lock supports up to 30 user codes. If we were to create three entities for every code (text entity for code, text entity for a name, and a switch entity for enabled state), that would result in 90 entities for my one lock. In addition to being a lot of entities, users would have to construct a UI for user code management themselves, and that UI would not be well optimized for the use case.
• Automations would still likely have to be integration specific because every integration could choose to implement this slightly differently
• A UI would not be optimized for this particular use case and users would be required to build their own UI, or integraitons would have to build their own UI.

Considerations:

• We'd have to evaluate whether this would be sufficient for Z-Wave certification. I think we could make it work but it would not be as clean as I think we'd prefer it to be.

Option 3: Establish a new entity type for codes

Pros:

• We could standardize how codes are managed across integrations
• We could create an optimized UI for user code management
• We could reuse some of the techniques we've used elsewhere (like regex validation in the text entity) to provide the needed capabilities while giving integration owners a consistent pattern to follow.
• We could explicitly look at the Z-Wave certification requirements (and Matter certification requirements if they exist) and ensure that we are checking all of the boxes in terms of functionality.

Cons:

• This would require significant work in both the core and the frontend
• There's a risk that we don't foresee all the necessary use cases and integrations will inevitably have to build their own custom solutions for something we are trying to support natively

Considerations:

• We probably want a way to tie this new entity type back to the lock entity. While they would all be tied together through the device_registry, I don't think we can assume that a single device is a single lock, although I don't have any good examples to support that theory.

Recommendation

I recommend that we go with option 3 but spend some time researching what the requirements are that we need to support before creating an in depth proposal. Even if we were able to get certified using option 1 or 2, the user experience is not great (keymaster is a good way to "test" how option 1 or 2 might look like from a user perspective, and while some of the functionality would definitely be eliminated if integrations supported these things natively, my experience has shown that it is suboptimal)

[dknowles2]

I'm not sure there's a meaningful distinction between Option 1 & Option 2. If integrations are creating their own solutions, they are inherently using existing HA constructs. But I agree with your analysis of the cons here, and that's essentially why I didn't implement this for the Schlage integration: there's not really a clean way to model this in HA.

Let's consider the features we would want a lock code to have:

• name - Handled by a base entity type
• code - A (semi secret) value that is associated with a particular entity
• enabled - A toggle for whether the code can be used

Looking at the zwave certification list, I also see:

• admin_code - Whether a code has administrative powers
• keypad_mode - (I'm not sure I understand what this means?)

Some other interesting things to note:

• The access code itself should not be visible by default in the UI. If you have administrative access to a lock (e.g. you have access to HA, which has full control over the lock anyway) then you should be able to read the code, but it shouldn't be immediately shown.
• Administrative attributes & Keypad mode are both optional attributes that not every code would support. I don't think those have analogous settings in Schlage, for example.
• When changing a code (assuming the input is a numeric keypad on the screen) you would want the user to enter the value twice to make sure it's correct. Alternatively, since HA is a rich UI, we could provide a free-form text box.
• Showing a list of lock codes for a lock likely warrants its own section in the UI. Having them intertwined with other entities could be confusing, and you would instead expect them to be grouped together.
• Adding a new access code from the HA UI should be possible, but I'm not sure where that would go. Is there a similar paradigm with another entity type? I'm not sure there is...
• Similarly, you need to be able to remove an access code.

There are probably other things worth considering, but that's what's top-of-mind for me. ;)

[raman325]

Your point about options 1 and 2 being the same is valid, and if anything, that demonstrates why leaving it up to integrations is going to lead to a fragmented experience.

Thanks for those additional thoughts. I need to look into admin code and keypad mode more because I'm not familiar with them

[AlCalzone]

• enabled - A toggle for whether the code can be used

Z-Wave goes even further and has different "user ID statuses", which define how a code slot behaves. I'll just share the table instead of reiterating it:

[allenporter]

I think that this is a broader problem where option 3 directionally feels right. Alarm control panels also deal with codes.

I'm not sure if its an entity platform or something else like application credentials that can be used by integrations? Maybe thinking more about the access patterns for alarm control panels and locks would help? I may be focused on the "local code" use case which is perhaps different since i'm thinking about how manual or template alarm could use this for a DIY alarm system.

Future use cases:

• Might want to have the same code for a lock as an alarm control panel or shared across a couple locks.
• Codes may expire. I'd like to give my cat sitter a code that works for this weekend.
• … Or have a schedule. I'd like to give a guest access between 2-3pm on Wednesdays

[jvmahon]

It seems this may also be considered at a higher level of abstraction. Rather than a entity for input of lock codes, I'd suggest a more generalized "table" input entity may be better (or, at least, for the underlying foundation to build this on). There are several input items that are tables in form - for example, Lock codes (rows with User ID, Status, Type, PINCode columns), Groups (rows with IDs, Groups Names, Members), Scenes (rows with ID, Name, Members), Schedules, etc.

Perhaps the starting place for something like this is a concept like this flex-table-card lovelace https://github.com/custom-cards/flex-table-card?tab=readme-ov-file, and see example images: https://github.com/custom-cards/flex-table-card/blob/master/images/MultiExample.png, but extended into a reusable Entity that could appear on a device's page for lock codes, Groups, Scenes, or other data in 2D table form.

Then build from this 2D Table Input Entity to the more purpose-specific integration implementation.

[Hedda]

FYI, there is a feature request with related discussions from an end-user point-of-view in the Home Assistant's community forum here:

• https://community.home-assistant.io/t/lock-codes-user-management-unified-inc-users-pin-codes-for-code-locks-centalized-tracking-which-users-locked-unlocked-a-lock-and-when-how-was-locking-done-manual-from-inside-outside-keypad-integration-service-or-home-assistant-companion-etc/771302

The lock platform natively allows users to control the lock state of a lock, but it is not possible, at least natively, to manage codes for the lock. While not all locks have this functionality, many integrations/protocols support this, including zwave_js, zigbee, matter, and proprietary WiFi/BLE locks.

Can I suggest that you might also want to get zha/zigpy developers involved early for also looking at it from the Zigbee (ZHA) perspective?

• https://www.home-assistant.io/integrations/zha
  • https://github.com/home-assistant/core/tree/dev/homeassistant/components/zha
    • https://github.com/zigpy/zha
      • https://github.com/zigpy/zha-device-handlers
        • https://zigbeealliance.org/wp-content/uploads/2021/10/07-5123-08-Zigbee-Cluster-Library.pdf