指纹管理

指纹识别凭证，通过门锁指纹传感器验证开锁。

生物特征凭证

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

指令列表

指令码	名称	方向	说明
0x0700	ListFingerprints	APP → 设备	获取指纹列表
0x0701	GetFingerprint	APP → 设备	获取指纹详情
0x0702	StartFingerprintEnroll	APP → 设备	启动指纹录入
0x0703	CancelFingerprintEnroll	APP → 设备	取消指纹录入
0x0704	UpdateFingerprint	APP → 设备	更新指纹信息
0x0705	DeleteFingerprint	APP → 设备	删除指纹
0x0706	ClearFingerprints	APP → 设备	清空所有指纹
0x0780	FingerprintEnrollProgress	设备 → APP	录入进度通知
0x0781	FingerprintEnrollResult	设备 → APP	录入结果通知

数据结构

message Fingerprint {
  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	是否胁迫凭证

录入流程

指纹录入需要用户多次按压指纹传感器，通常需要 4-6 次：

ListFingerprints - 获取指纹列表

指令码: 0x0700

ListFingerprintsReq

message ListFingerprintsReq {
  optional uint32 user_id = 1;  // 按用户ID筛选（不指定则返回所有）
}

ListFingerprintsResp

message ListFingerprintsResp {
  uint32 code = 1;
  string message = 2;
  repeated Fingerprint fingerprints = 3;  // 指纹列表
}

GetFingerprint - 获取指纹详情

指令码: 0x0701

GetFingerprintReq

message GetFingerprintReq {
  uint32 credential_id = 1;  // 凭证ID
}

GetFingerprintResp

message GetFingerprintResp {
  uint32 code = 1;
  string message = 2;
  Fingerprint fingerprint = 3;  // 指纹详情
}

StartFingerprintEnroll - 启动指纹录入

指令码: 0x0702

调用此指令后，门锁进入指纹录入模式。

StartFingerprintEnrollReq

message StartFingerprintEnrollReq {
  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;          // 单次按压超时（秒），默认30
}

字段	必填	说明
user_id	否	不指定时自动创建新用户
validity	否	不指定时永久有效
use_count_limit	否	默认 0（不限制）
label	否	默认空字符串
is_duress	否	默认 false
timeout	否	单次按压等待超时，默认 30 秒

StartFingerprintEnrollResp

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

FingerprintEnrollProgress - 录入进度通知

指令码: 0x0780

方向: 设备 → APP（Notify）

每次用户按压指纹后，设备推送当前进度：

message FingerprintEnrollProgress {
  uint32 current = 1;   // 当前已完成次数
  uint32 total = 2;     // 总共需要次数
  uint32 quality = 3;   // 本次采集质量（0-100）
  string hint = 4;      // 提示信息（如"请换个角度"）
}

字段	类型	说明
current	uint32	当前已完成的按压次数
total	uint32	总共需要的按压次数
quality	uint32	本次采集质量，0-100
hint	string	提示信息，如"请将手指放正"、"请用力按压"

FingerprintEnrollResult - 录入结果通知

指令码: 0x0781

方向: 设备 → APP（Notify）

录入完成或失败时，设备推送最终结果：

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

CancelFingerprintEnroll - 取消指纹录入

指令码: 0x0703

在录入过程中可调用此指令取消。

CancelFingerprintEnrollReq

message CancelFingerprintEnrollReq {
  // 无参数
}

CancelFingerprintEnrollResp

message CancelFingerprintEnrollResp {
  uint32 code = 1;
  string message = 2;
}

UpdateFingerprint - 更新指纹信息

指令码: 0x0704

仅更新属性

指纹原始数据无法修改，此指令仅能更新标签、有效期等属性。

UpdateFingerprintReq

message UpdateFingerprintReq {
  uint32 credential_id = 1;             // 凭证ID（必填）
  optional ValidityPeriod validity = 2; // 有效期
  optional uint32 use_count_limit = 3;  // 使用次数限制
  optional string label = 4;            // 标签
  optional bool is_duress = 5;          // 是否胁迫凭证
}

UpdateFingerprintResp

message UpdateFingerprintResp {
  uint32 code = 1;
  string message = 2;
}

DeleteFingerprint - 删除指纹

指令码: 0x0705

DeleteFingerprintReq

message DeleteFingerprintReq {
  uint32 credential_id = 1;  // 凭证ID
}

DeleteFingerprintResp

message DeleteFingerprintResp {
  uint32 code = 1;
  string message = 2;
}

ClearFingerprints - 清空所有指纹

指令码: 0x0706

危险操作

此操作将删除门锁上所有指纹凭证，不可恢复。

ClearFingerprintsReq

message ClearFingerprintsReq {
  // 无参数
}

ClearFingerprintsResp

message ClearFingerprintsResp {
  uint32 code = 1;
  string message = 2;
  uint32 count = 3;  // 删除的数量
}

相关文档

• 凭证管理概述
• 凭证期限