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

1 串口配置

目前模组支持两种通信接口：UART，USB（CDC）。其中

UART：

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

USB（CDC）：

• 波特率：2000000
• 数据位：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_MODULE_ID	0xAC	获取模组ID，唯一标识

3.1 设备初始化完成

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

该消息仅支持使用串口连接，使用CDC不会上报此消息

主控在接收到 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 reserved1; 
    uint8_t timeout; 
    uint8_t reserved2[6];
};

参数说明：

• reserved1：保留字段，暂未使用。需设置为 0x00。
• timeout：识别超时时间，默认为10s，用户可以自行设置（最大不超过255s）。主控等待模组录入应答的超时时间应大于此参数设置值。
• reserved2：保留字段，暂未使用。需设置为 0x00。

主控下发消息格式如下：

SyncWord	MsgID	DataSize	Data			ParityCheck
2 bytes	1 byte	2 bytes	8 bytes			1 byte
0xEF 0xAA	MID_VERIFY (0x12)	0x08	reserved1 (1 byte)	timeout (1 byte)	reserved2 (6 bytes)

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

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

struct msg_reply_verify_data {
    uint16_t user_id;
    uint8_t username[32];
    uint8_t reserved[2];
};

参数说明：

• user_id：识别成功的用户 ID
• username：识别成功的用户名字
• reserved：保留字段，暂未使用。需设置为 0x00。

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

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)	reserved (2 bytes)

3.4 掌静脉录入（MID_ENROLL_SINGLE）

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

struct msg_enroll_data {
    uint8_t username[32];
    uint8_t reserved1[3];
    uint8_t timeout;
    uint8_t reserved2[4];
};

参数说明：

• username：录入用户的用户名。
• reserved1：保留字段，暂未使用。需设置为 0x00。
• timeout：录入过程的超时时间（s），默认为10s，用户可以自行设置（最大不超过255s）。主控等待模组录入应答的超时时间应大于此参数设置值。
• reserved2：保留字段，暂未使用。需设置为 0x00。

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

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

struct msg_reply_enroll_data {
    uint16_t user_id;
    uint8_t reserved;
};

参数说明：

• user_id：用户 ID
• reserved：保留，暂未使用。

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 获取模组ID

该命令用于获取模组ID，类型为长度为32的字符串。

该指令无需携带参数。

模组通过消息 MID_REPLY 返回的数据 msg_reply_module_id 定义如下：

struct msg_reply_module_id {
    char id[32];
    uint8_t reserved[512]; 
};

参数说明：

• id：长度不超过32的字符串ID。
• reserved：保留，暂未使用。

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 示例报文

• 掌静脉录入

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

  0xef 0xaa 0x1d 0x00 0x28 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 0x00 0x00 0x0a 0x00 0x00 0x00 0x00 0x29

  录入成功，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为test ，模组上报：

  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 0x7a 0x59

• 删除所有录入掌静脉

  主控发送：

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

  删除成功，模组上报：

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

5 文档修改记录

2024/10/14：V0.1版本，描述模组识别、录入、删除几个基本协议指令。

2024/11/18：V0.2版本，MID_VERIFY 消息新增字段预留空间，用于功能扩展。