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.*)
FeatureMap is hardcoded to 0 (no features advertised) — needs
kPinCredential / kRfidCredential / kUser bits, plus the associated
mandatory attributes (NumberOfPINUsersSupported,
NumberOfCredentialsSupportedPerUser, MaxPINCodeLength,
MinPINCodeLength, etc.).
doorLockIncomingCommands only lists LockDoor/UnlockDoor — missing
SetCredential, GetCredentialStatus, ClearCredential, SetUser,
GetUser, ClearUser.
- No implementation of the
emberAfPluginDoorLock* weak callbacks — so even
if the commands were declared, credential/user provisioning would go
nowhere.
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.
- 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);
Summary
MatterDoorLock/DeviceDoorLockcurrently only exposes a bare lock/unlockboolean (
is_locked(),set_locked(),toggle()) and implementsLockStateas a plain attribute write, bypassing the Door Lock cluster's command and
credential model entirely. The full
door-lock-serverplugin (with PIN/RFIDcredential 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.hThis 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
LockOpCredentialslist, so that:RFID credentials via the standard
SetCredential/GetCredentialStatus/ClearCredentialcommands, and manage users viaSetUser/GetUser.be validated against those stored credentials and reported back with the
correct
CredentialType/CredentialIndexin theLockOperationevent —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.*)FeatureMapis hardcoded to0(no features advertised) — needskPinCredential/kRfidCredential/kUserbits, plus the associatedmandatory attributes (
NumberOfPINUsersSupported,NumberOfCredentialsSupportedPerUser,MaxPINCodeLength,MinPINCodeLength, etc.).doorLockIncomingCommandsonly listsLockDoor/UnlockDoor— missingSetCredential,GetCredentialStatus,ClearCredential,SetUser,GetUser,ClearUser.emberAfPluginDoorLock*weak callbacks — so evenif the commands were declared, credential/user provisioning would go
nowhere.
DeviceDoorLock::SetLockState()only takes a barelock_state_t— nooverload taking an
OperationSourceEnum+ credential info, so the richerDoorLockServer::Instance().SetLockState(endpoint, state, opSource, userIndex, credentials)overload (which emitsLockOperationwithcredential attribution) is never reached.
MatterDoorLockAPI has no way for a sketch to (a) be notified whena 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 provisionednormally through a Matter controller's native "add code/tag" UI.
Proposed minimal API addition to
MatterDoorLock