376 lines
13 KiB
Markdown
376 lines
13 KiB
Markdown
|
## 串口配置
|
|||
|
|
|
|||
|
|
- 波特率：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 。<br/>0表示此消息无参数 |
|
|||
|
|
| ParityCheck | 1 byte | 协议的奇偶检验码。<br/>去除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 定义如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
struct msg_verify_data {
|
|||
|
|
uint8_t pd_rightaway;
|
|||
|
|
uint8_t timeout;
|
|||
|
|
};
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
参数说明：
|
|||
|
|
|
|||
|
|
- pd_rightaway：表示是否在识别完成后立刻关机(预留参数)，默认设 00。
|
|||
|
|
- timeout：识别超时时间，默认为10s，用户可以自行设置（最大不超过255s）。**主控等待模组录入应答的超时时间应大于此参数设置值。**
|
|||
|
|
|
|||
|
|
主控下发消息格式如下：
|
|||
|
|
|
|||
|
|
<br/>
|
|||
|
|
|
|||
|
|
<table align="center">
|
|||
|
|
<tr align="center">
|
|||
|
|
<th>SyncWord</th>
|
|||
|
|
<th>MsgID</th>
|
|||
|
|
<th>DataSize</th>
|
|||
|
|
<th colspan="2">Data</th>
|
|||
|
|
<th>ParityCheck</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td colspan="2">2 bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>0xEF 0xAA</td>
|
|||
|
|
<td>MID_VERIFY<br/>(0x12)</td>
|
|||
|
|
<td>0x02</td>
|
|||
|
|
<td>pd_rightaway<br/>(1 byte)</td>
|
|||
|
|
<td>timeout<br/>(1 byte)</td>
|
|||
|
|
<td> </td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
|
|||
|
|
|
|||
|
|
识别结果 Result 确认码的返回值见 `命令结果上报（MID_REPLY）`。
|
|||
|
|
|
|||
|
|
模组掌静脉识别成功后，通过消息 MID_REPLY 返回的数据 ResultData 定义如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
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：保留参数，未使用
|
|||
|
|
|
|||
|
|
模组识别成功上报消息格式如下：
|
|||
|
|
|
|||
|
|
<table align="center">
|
|||
|
|
<tr align="center">
|
|||
|
|
<th rowspan="3">SyncWord</th>
|
|||
|
|
<th rowspan="3">MsgID</th>
|
|||
|
|
<th rowspan="3">DataSize</th>
|
|||
|
|
<th colspan="6">Data</th>
|
|||
|
|
<th>ParityCheck</th>
|
|||
|
|
</tr>
|
|||
|
|
<td>RID</td>
|
|||
|
|
<td>Result</td>
|
|||
|
|
<td colspan="4">ResultData</td>
|
|||
|
|
<tr>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td colspan="6">N bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>0xEF 0xAA</td>
|
|||
|
|
<td>MID_REPLY<br/>(0x00)</td>
|
|||
|
|
<td>0x26</td>
|
|||
|
|
<td>MID_VERIFY<br/>(0x12)</td>
|
|||
|
|
<td>Result<br/>(1 byte)</td>
|
|||
|
|
<td>user_id<br/>(2 byte)</td>
|
|||
|
|
<td>username<br/>(32 byte)</td>
|
|||
|
|
<td>admin<br/>(1 byte)</td>
|
|||
|
|
<td>unlockStatus<br/>(1 byte)</td>
|
|||
|
|
<td> </td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
|
|||
|
|
|
|||
|
|
### 掌静脉注册（MID_ENROLL_SINGLE）
|
|||
|
|
|
|||
|
|
掌静脉注册指令下发携带的参数 `msg_enroll_data` 定义如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
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 定义如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
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 定义如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
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 如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
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 如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
struct msg_get_palm_feature_data {
|
|||
|
|
uint16_t user_id;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
录入结果 Result 确认码的返回值见 `命令结果上报（MID_REPLY）`。
|
|||
|
|
|
|||
|
|
获取掌静脉特征值任务成功后，通过消息 MID_REPLY 返回的数据 ResultData 定义如下：
|
|||
|
|
|
|||
|
|
```c++
|
|||
|
|
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 消息的完整协议如下所示：
|
|||
|
|
|
|||
|
|
<table align="center">
|
|||
|
|
<tr align="center">
|
|||
|
|
<th>SyncWord</th>
|
|||
|
|
<th>MsgID</th>
|
|||
|
|
<th>DataSize</th>
|
|||
|
|
<th colspan="3">Data</th>
|
|||
|
|
<th>ParityCheck</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td colspan="3">N bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>0xEF 0xAA</td>
|
|||
|
|
<td>MID_REPLY(0x00)</td>
|
|||
|
|
<td> </td>
|
|||
|
|
<td>RID(1 byte)</td>
|
|||
|
|
<td>Result(1 byte)</td>
|
|||
|
|
<td>ResultData( N-2 bytes)</td>
|
|||
|
|
<td> </td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
|
|||
|
|
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 消息主要作用是主动向主控上报一些信息，报文格式如下：
|
|||
|
|
|
|||
|
|
<table align="center">
|
|||
|
|
<tr align="center">
|
|||
|
|
<th>SyncWord</th>
|
|||
|
|
<th>MsgID</th>
|
|||
|
|
<th>DataSize</th>
|
|||
|
|
<th colspan="3">Data</th>
|
|||
|
|
<th>ParityCheck</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
<td>2 bytes</td>
|
|||
|
|
<td colspan="3">N bytes</td>
|
|||
|
|
<td>1 byte</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr align="center">
|
|||
|
|
<td>0xEF 0xAA</td>
|
|||
|
|
<td>MID_NOTE(0x01)</td>
|
|||
|
|
<td> </td>
|
|||
|
|
<td>NID(1 byte)</td>
|
|||
|
|
<td>NoteData( N-1 bytes)</td>
|
|||
|
|
<td> </td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
|
|||
|
|
目前NID主要内容如下：
|
|||
|
|
|
|||
|
|
| NID（*表示该消息携带 NoteData 数据） | Code | 说明 |
|
|||
|
|
| ------------------------------------ | ---- | -------------------- |
|
|||
|
|
| NID_READY | 0x00 | 模组已上电初始化成功 |
|
|||
|
|
|
|||
|
|
## 示例报文
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
|