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

1 串口配置

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

2 消息格式

主控和模块通讯的基本格式如下表所示，字节序为 大端字节序（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运算

3 消息列表

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

3.1 设备初始化完成

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

主控在接收到 MID_NOTE 信息后，可以和模组进行指令交互。

3.2 模组复位（MID_RESET）

模组同一时刻，只能执行一个任务，当模组在执行耗时长的任务时（例如掌静脉识别 MID_VERIFY），主控可以向模组下发 MID_RESET 打断取消当前任务，进而再去执行其它任务。

该指令无需携带参数。

指令执行结束后，通过消息 MID_REPLY 返回结果：

• 0x00（MR_SUCCESS）：复位成功
• 0x05（MR_FAILED4_UNKNOWNREASON）：未知错误

3.3 掌静脉识别（MID_VERIFY）

主控下发该指令给模组，模组开始检测摄像头图像中的掌静脉，并和底库中的掌静脉进行比对。指令下发携带的参数 msg_verify_data 定义如下：

struct msg_verify_data  {
    uint8_t pd_rightaway; 
    uint8_t timeout; 
};

参数说明：

• pd_rightaway：保留，暂未使用。可设置为 0x00。
• 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 bytes)	username (32 bytes)	admin (1 byte)	unlockStatus (1 byte)

3.4 掌静脉录入（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：设置该录入的掌静脉人员为管理员。0：非管理员，1：管理员。
• 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：保留，暂未使用。

3.5 删除单个掌静脉（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不存在

3.6 删除所有掌静脉（MID_DELALL）

删除所有已录入的用户。

该指令无需携带参数。

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

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

3.7 掌静脉特征值录入（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）：未知错误

3.8 获取掌静脉特征值（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） 携带参数的参数定义说明。

3.9 命令结果上报（MID_REPLY）

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

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	未采用加密通讯

3.10 模组状态上报（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	模组已上电初始化成功

4 示例报文

• 掌静脉录入

  录入 admin为0，username为 test 的用户，超时时间 10s，主控发送：

  0xef 0xaa 0x1d 0x00 0x23 0x00 0x74 0x65 0x73 0x74 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x0a 0x22

  录入成功，ID为1，模组上报：

  0xef 0xaa 0x00 0x00 0x05 0x1d 0x00 0x00 0x01 0x00 0x19

• 掌静脉识别

  开始识别比对，超时时间20s，主控发送：

  0xef 0xaa 0x12 0x00 0x02 0x00 0x14 0x04

  识别比对成功，user_id为1，username为amass，admin为0，模组上报：

  0xef 0xaa 0x00 0x00 0x26 0x12 0x00 0x00 0x01 0x74 0x65 0x73 0x74 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0xc8 0xeb

• 删除所有录入掌静脉

  主控发送：

  0xef 0xaa 0x21 0x00 0x00 0x21

  删除成功，模组上报：

  0xef 0xaa 0x00 0x00 0x02 0x21 0x00 0x23