人脸管理

3D人脸识别凭证，通过门锁摄像头验证开锁。

生物特征凭证

人脸是生物特征凭证，原始数据存储在门锁本地，无法导出或修改。UpdateFace 仅能更新标签、有效期等属性，如需修改人脸需删除后重新录入。

指令列表

指令码	名称	方向	说明
0x0800	ListFaces	APP → 设备	获取人脸列表
0x0801	GetFace	APP → 设备	获取人脸详情
0x0802	StartFaceEnroll	APP → 设备	启动人脸录入
0x0803	CancelFaceEnroll	APP → 设备	取消人脸录入
0x0804	UpdateFace	APP → 设备	更新人脸信息
0x0805	DeleteFace	APP → 设备	删除人脸
0x0806	ClearFaces	APP → 设备	清空所有人脸
0x0880	FaceEnrollProgress	设备 → APP	录入进度通知
0x0881	FaceEnrollResult	设备 → APP	录入结果通知

数据结构

message Face {
  uint32 credential_id = 1;    // 凭证ID（锁内唯一）
  uint32 user_id = 2;          // 归属用户ID
  uint32 created_by = 3;       // 创建者用户ID
  uint64 created_at = 4;       // 创建时间（UNIX毫秒时间戳）
  ValidityPeriod validity = 5; // 有效期
  uint32 use_count_limit = 6;  // 使用次数限制（0=不限）
  uint32 use_count = 7;        // 已使用次数
  string label = 8;            // 标签
  bool is_duress = 9;          // 是否胁迫凭证
}

字段	类型	说明
credential_id	uint32	凭证ID，锁内唯一标识
user_id	uint32	归属用户ID
created_by	uint32	创建者用户ID
created_at	uint64	创建时间（UNIX毫秒时间戳）
validity	ValidityPeriod	有效期，详见 凭证期限
use_count_limit	uint32	使用次数限制，0 表示不限制
use_count	uint32	已使用次数
label	string	用户自定义标签
is_duress	bool	是否胁迫凭证

胁迫凭证限制

人脸通常不适合作为胁迫凭证，因为用户无法主动选择使用哪张人脸开锁。建议使用指纹或密码作为胁迫凭证。

录入流程

人脸录入需要用户面对摄像头，系统会采集多角度面部特征：

StartFaceEnroll - 启动人脸录入

指令码: 0x0802

StartFaceEnrollReq

message StartFaceEnrollReq {
  optional uint32 user_id = 1;          // 归属用户ID（不指定则自动创建用户）
  optional ValidityPeriod validity = 2; // 有效期
  optional uint32 use_count_limit = 3;  // 使用次数限制
  optional string label = 4;            // 标签
  optional bool is_duress = 5;          // 是否胁迫凭证
  optional uint32 timeout = 6;          // 录入超时（秒），默认60
}

StartFaceEnrollResp

message StartFaceEnrollResp {
  uint32 code = 1;   // 0=已进入录入模式
  string message = 2;
}

FaceEnrollProgress - 录入进度通知

指令码: 0x0880

方向: 设备 → APP（Notify）

message FaceEnrollProgress {
  uint32 current = 1;   // 当前进度百分比（0-100）
  uint32 total = 2;     // 总进度（固定100）
  string hint = 3;      // 提示信息（如"请向左转头"）
}

hint 示例	说明
请正视摄像头	初始位置
请向左转头	采集左侧面
请向右转头	采集右侧面
请抬头	采集仰视角度
请低头	采集俯视角度

FaceEnrollResult - 录入结果通知

指令码: 0x0881

方向: 设备 → APP（Notify）

message FaceEnrollResult {
  uint32 code = 1;           // 0=成功
  string message = 2;
  uint32 credential_id = 3;  // 新建的凭证ID（成功时有效）
  uint32 user_id = 4;        // 归属用户ID（成功时有效）
}

其他指令

人脸管理的 List、Get、Cancel、Update、Delete、Clear 指令结构与 指纹管理 完全一致，仅将 Fingerprint 替换为 Face，指令码使用 0x08xx 区块。

指令	请求结构	响应结构
ListFaces	ListFacesReq	ListFacesResp
GetFace	GetFaceReq	GetFaceResp
CancelFaceEnroll	CancelFaceEnrollReq	CancelFaceEnrollResp
UpdateFace	UpdateFaceReq	UpdateFaceResp
DeleteFace	DeleteFaceReq	DeleteFaceResp
ClearFaces	ClearFacesReq	ClearFacesResp

相关文档

• 凭证管理概述
• 指纹管理 - 结构相似，可参考详细字段定义
• 凭证期限