门锁 Cluster（DoorLock）

Cluster ID: 0x0101  | 所在 Endpoint: 通常在 Endpoint 1（功能端点）

DoorLock 是 Matter 门锁设备的核心 Cluster，定义了锁的状态查询、开/关锁操作、用户管理、凭据（PIN 码/指纹/NFC）管理等全部能力。 门锁类设备的日常开发基本都围绕这个 Cluster 展开。

命令（Commands）

Command 是发送给门锁执行的操作。大多数写操作都要求 Timed Interaction（定时交互），这是 Matter 针对门锁等安全设备的安全要求。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

LockDoor —— 上锁（0x00）

向门锁发送上锁指令。执行成功后，LockState 属性会从当前值变为 Locked (1)。 这是门锁最核心、最常用的命令之一。

↑ 返回命令列表

UnlockDoor —— 解锁（0x01）

向门锁发送解锁指令。执行成功后，LockState 属性会变为 Unlocked (2)。 与 LockDoor 对称，同样是最常用的命令。

↑ 返回命令列表

UnlockWithTimeout —— 限时解锁（0x03）

解锁门锁，经过指定时间后自动回锁。功能上等同于先 UnlockDoor 再等待 AutoRelockTime，但超时时间由命令参数指定，不受 AutoRelockTime 属性影响。

↑ 返回命令列表

SetCredential —— 设置凭据（0x1A）

为用户添加或修改凭据。凭据是用户用来开锁的「钥匙」—— 可以是 PIN 码、指纹、RFID 卡等。 每个凭据需要绑定到一个已存在的用户（通过 SetUser 创建）。

↑ 返回命令列表

GetCredentialStatus —— 查询凭据状态（0x1B）

查询指定凭据槽位是否已被占用、绑定在哪个用户上。不需要 Timed Interaction，是只读查询操作。

↑ 返回命令列表

ClearCredential —— 删除凭据（0x1D）

删除指定的凭据。如果传入特定的 CredentialType 和 CredentialIndex，则精确删除对应凭据；也可以批量清除某类凭据或全部凭据。

↑ 返回命令列表

SetAliroReaderConfig —— 配置 Aliro 读卡器（0x22）

配置 Aliro NFC 读卡器的签名密钥、群组密钥、支持的协议版本等参数。Aliro 是 Matter 为门锁新增的 NFC 无感开锁标准。

↑ 返回命令列表

ClearAliroReaderConfig —— 清除 Aliro 配置（0x24）

重置 Aliro NFC 读卡器的所有配置，恢复到未配置状态。

↑ 返回命令列表

SetUser —— 设置用户（0x26）

创建或修改门锁上的用户。用户是凭据的「容器」—— 每个用户可以绑定多个凭据（密码、指纹等）， 并且可以设置权限级别和有效期。用户管理和凭据管理是门锁最复杂的两个操作。

↑ 返回命令列表

GetUser —— 查询用户（0x28）

按 UserIndex 查询用户的详细信息，包括名称、状态、类型、绑定的凭据列表等。不需要 Timed Interaction。

↑ 返回命令列表

ClearUser —— 删除用户（0x29）

删除指定用户及其关联的所有凭据。这是一个「级联删除」操作 —— 不需要额外调用 ClearCredential。

↑ 返回命令列表

定时交互示例（Timed Interaction）

发送上锁命令时，请求结构大致如下：

{
  "timedRequest": {
    "timeoutMs": 5000       // 超时时间 5 秒
  },
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 1,       // 功能端点
      "clusterId": "0x0101", // DoorLock
      "commandId": "0x00"    // LockDoor
    },
    "commandFields": {}      // LockDoor 无额外参数
  }]
}

↑ 返回命令列表

属性详解

DoorLock Cluster 的属性按功能分为五组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

锁核心状态（0x00-0x06）

门锁最基本的状态信息，包括锁状态、锁类型、执行器以及门体位置传感器数据。

LockState 枚举值

LockType 枚举值

DoorState 枚举值

↑ 返回属性列表

用户与凭据（0x10-0x1B）

描述门锁支持的用户数量、凭据类型容量以及时间表调度能力。

CredentialRulesSupport 位图

↑ 返回属性列表

操作与显示（0x1C-0x27）

控制门锁的操作行为、界面显示和本地编程功能。

LEDSettings 枚举值

SoundVolume 枚举值

OperatingMode 枚举值

↑ 返回属性列表

远程操作（0x30-0x33）

与远程（网络/无线）操作安全策略相关的属性。

↑ 返回属性列表

Aliro NFC 门禁（0x80-0x88）

Aliro 是 Matter 为门锁新增的 NFC 无感开锁标准。支持手机靠近门锁自动解锁，类似 Apple 数字车钥匙的体验。 通过 SetAliroReaderConfig / ClearAliroReaderConfig 命令管理。

↑ 返回属性列表

标准示例

以下是 Matter 门锁的典型属性数据示例（JSON 格式），逐字段标注含义：

{
  // --- 锁核心状态 ---
  "0x00": 1,           // LockState = Locked（已锁定）
  "0x01": 0,           // LockType = DeadBolt（锁舌锁）
  "0x02": true,        // ActuatorEnabled = true（执行器启用）
  "0x03": 1,           // DoorState = Closed（门已关闭）

  // --- 用户与凭据 ---
  "0x10": 10,          // NumberOfTotalUsersSupported = 10
  "0x11": 10,          // NumberOfPINUsersSupported = 10
  "0x16": 8,           // MaxPINCodeLength = 8 位
  "0x17": 4,           // MinPINCodeLength = 4 位
  "0x1B": 5,           // NumberOfCredentialsSupportedPerUser = 5

  // --- 操作与显示 ---
  "0x1E": 30,          // AutoRelockTime = 30 秒
  "0x1F": 2,           // SoundVolume = High
  "0x20": 0,           // OperatingMode = Normal
  "0x21": 65535,       // SupportedOperatingModes（支持所有模式）

  // --- 远程操作 ---
  "0x30": 5,           // WrongCodeEntryLimit = 5 次
  "0x33": false        // RequirePINforRemoteOperation = false
}

常见场景

场景 1：远程开锁 / 关锁

1. 读取 ActuatorEnabled (0x02)，确认执行器是否启用
2. 读取 RequirePINforRemoteOperation (0x33)，判断是否需要用户输入 PIN
3. 发送 LockDoor (0x00) 或 UnlockDoor (0x01) 命令（必须带 Timed Interaction）
4. 订阅 LockState (0x00) 的变化，确认操作结果

场景 2：添加新用户和 PIN 码

1. 读取 NumberOfTotalUsersSupported (0x10) 确认用户容量
2. 发送 SetUser (0x26) 创建用户
3. 读取 MinPINCodeLength (0x17) 和 MaxPINCodeLength (0x16) 确认 PIN 长度要求
4. 发送 SetCredential (0x1A) 为该用户绑定 PIN 码
5. 可通过 GetCredentialStatus (0x1B) 验证凭据是否设置成功

场景 3：首页展示锁状态

1. 读取 LockState (0x00) —— 注意处理 null 值
2. 读取 OperatingMode (0x20) —— 如果不是 Normal，界面上可能需要提示
3. 配合 PowerSource Cluster 读取电池电量