Skip to content

[request] Add PIN/RFID credential and User (USR) support to MatterDoorLock #198

Description

@lboue

Summary

MatterDoorLock / DeviceDoorLock currently only exposes a bare lock/unlock
boolean (is_locked(), set_locked(), toggle()) and implements LockState
as a plain attribute write, bypassing the Door Lock cluster's command and
credential model entirely. The full door-lock-server plugin (with PIN/RFID
credential and User management support) is already vendored in the Matter SDK
for every Matter-capable variant, it's just not wired up:

  • variants/<board>/matter/matter_2.5.1/third_party/matter_sdk/src/app/clusters/door-lock-server/door-lock-server.h

This plugin expects the application to implement a set of weak callbacks
(emberAfPluginDoorLockGetCredential, emberAfPluginDoorLockSetCredential,
emberAfPluginDoorLockGetUser, emberAfPluginDoorLockSetUser,
emberAfPluginDoorLockOnDoorLockCommand, emberAfPluginDoorLockOnDoorUnlockCommand)
and to report state changes through DoorLockServer::Instance().SetLockState(...)
with a LockOpCredentials list, so that:

  • A Matter controller (Home Assistant, Apple Home, etc.) can provision PIN or
    RFID credentials via the standard SetCredential / GetCredentialStatus /
    ClearCredential commands, and manage users via SetUser/GetUser.
  • A physical credential presentation (keypad PIN entry, RFID/NFC tag scan) can
    be validated against those stored credentials and reported back with the
    correct CredentialType/CredentialIndex in the LockOperation event —
    today, no such event with credential attribution is emitted at all.

What's currently missing (all in libraries/Matter/src/devices/DeviceDoorLock.*

and libraries/Matter/src/MatterDoorLock.*)

  1. FeatureMap is hardcoded to 0 (no features advertised) — needs
    kPinCredential / kRfidCredential / kUser bits, plus the associated
    mandatory attributes (NumberOfPINUsersSupported,
    NumberOfCredentialsSupportedPerUser, MaxPINCodeLength,
    MinPINCodeLength, etc.).
  2. doorLockIncomingCommands only lists LockDoor/UnlockDoor — missing
    SetCredential, GetCredentialStatus, ClearCredential, SetUser,
    GetUser, ClearUser.
  3. No implementation of the emberAfPluginDoorLock* weak callbacks — so even
    if the commands were declared, credential/user provisioning would go
    nowhere.
  4. DeviceDoorLock::SetLockState() only takes a bare lock_state_t — no
    overload taking an OperationSourceEnum + credential info, so the richer
    DoorLockServer::Instance().SetLockState(endpoint, state, opSource, userIndex, credentials) overload (which emits LockOperation with
    credential attribution) is never reached.
  5. Public MatterDoorLock API has no way for a sketch to (a) be notified when
    a credential is provisioned/cleared, or (b) report a locally-validated
    physical credential presentation (e.g. an RFID tag scanned via Wire +
    an NFC reader library) back into the cluster.

Motivating use case

Building a door lock sketch on an xG24/MG24 board where an RFID/NFC reader is
wired over I2C (Wire) to authenticate users, with credentials provisioned
normally through a Matter controller's native "add code/tag" UI.

Proposed minimal API addition to MatterDoorLock

bool set_credential(CredentialTypeEnum type, uint16_t index,
                     const uint8_t* data, uint8_t len);
bool clear_credential(CredentialTypeEnum type, uint16_t index);
void set_credential_changed_callback(void (*cb)(CredentialTypeEnum, uint16_t));

// Called by the sketch after it has itself matched a physically-presented
// credential (e.g. a scanned RFID UID) against a previously provisioned one.
void report_credential_unlock(CredentialTypeEnum type, uint16_t index);

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions