SmartLockerTools/resources/L015掌静脉识别模组串口通信协议.md

串口配置

• 波特率：115200
• 数据位：8
• 停止位：1
• 奇偶检验：无
• 流控制：无

消息格式

主控和模块通讯的基本格式如下表所示，字节序为 大端字节序（Big Endian）：

SyncWord	MsgID	DataSize	Data	ParityCheck
2 bytes	1 byte	2 bytes	N bytes	1 byte

下表是对上述各个字段的详细说明：

字段	长度	说明
SyncWord	2 bytes	固定的消息开头同步字：0xEF 0xAA
MsgID	1 byte	消息ID（例如 MID_VERIFY）
DataSize	2 bytes	Data数据的长度，0 ≤ size ≤ 65535
Data	N bytes	消息（MsgID）对应的数据内容，长度 N 为 DataSize 。 0表示此消息无参数
ParityCheck	1 byte	协议的奇偶检验码。 去除SyncWord，对 MsgID、DataSize、Data 的内容字节做XOR运算

消息列表

MsgID	Code	说明
MID_REPLY	0x00	模组对主控发送出的命令的应答，对于主控下发的每条命令，模组最终都会使用 MID_REPLY 进行结果应答上报
MID_NOTE	0x01	摸组主动上报给主控的信息，根据 NID 判断消息类型和对应的 Data 结构（详细内容见下文）
MID_VERIFY	0x12	掌静脉识别比对
MID_ENROLL_SINGLE	0x1D	掌静脉录入（单帧）
MID_DELUSER	0x20	删除一个已注册的掌静脉
MID_DELALL	0x21	删除所有已注册的掌静脉
MID_ENROLL_PALM_FEATUTE	0xF9	主控下发掌静脉特征值给模组进行注册
MID_GET_PALM_FEATUTE	0xFA	主控请求获取指定用户掌静脉特征值

设备初始化完成

模组上电初始化完成后，会通过串口向主控发送一条 NID 为 NID_READY 的 MID_NOTE 消息： 0xEF 0xAA 0x01 0x00 0x01 0x00 0x00。（消息详细解释见 模组状态上报（MID_NOTE））。

主机在接收到握手信号后，可以和模组进行指令交互。

掌静脉识别（MID_VERIFY）

主控下发该指令给模组，模组开始识别掌静脉进行比对，指令下发携带的参数 msg_verify_data 定义如下：

struct msg_verify_data  {
    uint8_t pd_rightaway; 
    uint8_t timeout; 
};

参数说明：

• pd_rightaway：表示是否在识别完成后立刻关机(预留参数)，默认设 00。
• timeout：识别超时时间，默认为10s，用户可以自行设置（最大不超过255s）。主控等待模组录入应答的超时时间应大于此参数设置值。

主控下发消息格式如下：

SyncWord	MsgID	DataSize	Data		ParityCheck
2 bytes	1 byte	2 bytes	2 bytes		1 byte
0xEF 0xAA	MID_VERIFY (0x12)	0x02	pd_rightaway (1 byte)	timeout (1 byte)

识别结果 Result 确认码的返回值见 命令结果上报（MID_REPLY）。

模组掌静脉识别成功后，通过消息 MID_REPLY 返回的数据 ResultData 定义如下：

struct msg_reply_verify_data {
    uint16_t user_id;
    uint8_t username[32];
    uint8_t admin;
    uint8_t unlockStatus;
};

参数说明：

• user_id：识别成功的用户 ID
• username：识别成功的用户名字
• admin：识别成功的用户是否为管理员用户
• unlockStatus：保留参数，未使用

模组识别成功上报消息格式如下：

SyncWord	MsgID	DataSize	Data						ParityCheck
			RID	Result	ResultData
2 bytes	1 byte	2 bytes	N bytes						1 byte
0xEF 0xAA	MID_REPLY (0x00)	0x26	MID_VERIFY (0x12)	Result (1 byte)	user_id (2 byte)	username (32 byte)	admin (1 byte)	unlockStatus (1 byte)

掌静脉注册（MID_ENROLL_SINGLE）

掌静脉注册指令下发携带的参数 msg_enroll_data 定义如下：

struct msg_enroll_data {
    uint8_t admin;
    uint8_t username[32];
    uint8_t palm_direction;
    uint8_t timeout;
};

参数说明：

• admin：设置该录入的掌静脉人员为管理员。
• username：录入用户的用户名。
• palm_direction：保留，暂未使用。可设置为 0x00。
• timeout：录入过程的超时时间（s），默认为10s，用户可以自行设置（最大不超过255s）。主控等待模组录入应答的超时时间应大于此参数设置值。

录入结果 Result 确认码的返回值见 命令结果上报（MID_REPLY）。

模组掌静脉录入成功后，通过消息 MID_REPLY 返回的数据 ResultData 定义如下：

struct msg_reply_enroll_data {
    uint16_t user_id;
    uint8_t face_direction;
};

参数说明：

• user_id：用户 ID 每次录入都会增加 1，即使删除某个 ID 后，再次录入 ID 会继续增加，直至 65530，ID 变为 0。
• face_direction：保留，暂未使用。

删除单个掌静脉（MID_DELUSER）

通过传入用户 ID, 删除指定 ID 的单个用户。

删除单个用户指令携带参数 msg_deluser_data 定义如下：

struct msg_deluser_data {
    uint16_t user_id;
};

参数说明：

• user_id：需要删除的用户 ID。

指令执行结束后，通过消息 MID_REPLY 返回结果（主控等待应答超时时间建议设置为 5s）：

• 0x00（MR_SUCCESS）：删除成功
• 0x05（MR_FAILED4_UNKNOWNREASON）：未知错误
• 0x08（MR_FAILED4_UNKNOWNUSER）：删除的用户ID不存在

删除所有掌静脉（MID_DELALL）

删除所有已注册的用户。

该指令无需携带参数。

指令执行结束后，通过消息 MID_REPLY 返回结果（主控等待应答超时时间建议设置为 5s）：

• 0x00（MR_SUCCESS）：删除成功
• 0x05（MR_FAILED4_UNKNOWNREASON）：未知错误

掌静脉特征值注册（MID_ENROLL_PALM_FEATUTE）

该命令用于直接将掌静脉特征值下发给模组进行注册。

下发掌静脉特征值注册携带的参数 msg_palm_feature_enroll_data 如下：

struct msg_palm_feature_enroll_data  {
    uint16_t user_id;       
    uint8_t username[32];
    uint8_t admin;             
    uint8_t feature_data_md5[16];
    uint16_t feature_total_size;
    uint8_t feature_data[feature_total_size];
};

参数说明：

• user_id：用户ID，下发掌静脉特征值时，由用户设置。
• username：录入用户的用户名。
• admin：设置该录入的掌静脉人员为管理员。
• feature_data_md5：特征值 feature_data 的 md5 校验值
• feature_total_size：特征值 feature_data 的长度
• feature_data：掌静脉特征值数据

指令执行结束后，通过消息 MID_REPLY 返回结果（主控等待应答超时时间建议设置为 5s）：

• 0x00（MR_SUCCESS）：注册成功
• 0x05（MR_FAILED4_UNKNOWNREASON）：未知错误

获取掌静脉特征值（MID_GET_PALM_FEATUTE）

该命令用于获取对应已注册用户的掌静脉特征值，携带参数 msg_get_palm_feature_data 如下：

struct msg_get_palm_feature_data {
    uint16_t user_id;
}

录入结果 Result 确认码的返回值见 命令结果上报（MID_REPLY）。

获取掌静脉特征值任务成功后，通过消息 MID_REPLY 返回的数据 ResultData 定义如下：

struct msg_palm_feature_enroll_data  {
    uint16_t user_id;       
    uint8_t username[32];
    uint8_t admin;             
    uint8_t feature_data_md5[16];
    uint16_t feature_total_size;
    uint8_t feature_data[feature_total_size];
};

参数定义见 掌静脉特征值注册（MID_ENROLL_PALM_FEATUTE） 携带参数的参数定义说明。

命令结果上报（MID_REPLY）

模组向主控发送的 MID_NOTE 消息的完整协议如下所示：

SyncWord	MsgID	DataSize	Data			ParityCheck
2 bytes	1 byte	2 bytes	N bytes			1 byte
0xEF 0xAA	MID_REPLY(0x00)		RID(1 byte)	Result(1 byte)	ResultData( N-2 bytes)

RID表示模组当前正在处理的任务，例如当 RID 为 MID_ENROLL_SINGLE 是，表示该消息是模组处理完单帧录入任务后回复的消息。

消息对应的 ResultData 会在主控下发命令（例如 MID_ENROLL_SINGLE ）中进行介绍。

Result 表示该命令的最终执行结果，详细如下表所示。

Result	Code	说明
MR_SUCCESS	0	指令执行成功
MR_REJECTED	1	模组拒绝该命令
MR_ABORTED	2	录入/解锁算法已终止
MR_FAILED4_CAMERA	4	相机打开失败
MR_FAILED4_UNKNOWNREASON	5	未知错误
MR_FAILED4_INVALIDPARAM	6	无效的参数
MR_FAILED4_NOMEMORY	7	内存不足
MR_FAILED4_UNKNOWNUSER	8	未录入的用户
MR_FAILED4_MAXUSER	9	录入超过最大数量
MR_FAILED4_PALMENROLLED	10	掌静脉已录入
MR_FAILED4_LIVENESSCHECK	12	活体检测失败
MR_FAILED4_TIMEOUT	13	录入或解锁超时
MR_FAILED4_AUTHORIZATION	14	加密芯片授权失败
MR_FAILED4_READ_FILE	19	读文件失败
MR_FAILED4_WRITE_FILE	20	写文件失败
MR_FAILED4_NO_ENCRYPT	21	未采用加密通讯

模组状态上报（MID_NOTE）

MID_NOTE 消息主要作用是主动向主控上报一些信息，报文格式如下：

SyncWord	MsgID	DataSize	Data			ParityCheck
2 bytes	1 byte	2 bytes	N bytes			1 byte
0xEF 0xAA	MID_NOTE(0x01)		NID(1 byte)	NoteData( N-1 bytes)

目前NID主要内容如下：

NID（*表示该消息携带 NoteData 数据）	Code	说明
NID_READY	0x00	模组已上电初始化成功

示例报文