438 lines
10 KiB
Markdown
438 lines
10 KiB
Markdown
# SI-M1 串口指令测试说明
|
||
|
||
本文档用于串口助手或底层串口程序直接测试 SI-M1 人脸识别模组协议。Unity 端同样按本文的封包格式发送命令。
|
||
|
||
## 1. 基础封包格式
|
||
|
||
主控发送：
|
||
|
||
```text
|
||
EF AA MID SIZE_H SIZE_L DATA... CHECKSUM
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 长度 | 说明 |
|
||
| --- | --- | --- |
|
||
| `EF AA` | 2 bytes | 同步头 |
|
||
| `MID` | 1 byte | 命令 ID |
|
||
| `SIZE_H SIZE_L` | 2 bytes | DATA 长度，大端 |
|
||
| `DATA` | N bytes | 命令参数，可为空 |
|
||
| `CHECKSUM` | 1 byte | `MID ^ SIZE_H ^ SIZE_L ^ DATA[0] ^ ...` |
|
||
|
||
模组回复：
|
||
|
||
```text
|
||
EF AA 00 SIZE_H SIZE_L MID RESULT DATA... CHECKSUM
|
||
```
|
||
|
||
主动通知：
|
||
|
||
```text
|
||
EF AA 01 SIZE_H SIZE_L NID DATA... CHECKSUM
|
||
```
|
||
|
||
常见结果码：
|
||
|
||
| Result | 说明 |
|
||
| --- | --- |
|
||
| `00` | 成功 |
|
||
| `01` | 模组拒绝命令 |
|
||
| `02` | 操作终止 |
|
||
| `06` | 参数无效 |
|
||
| `08` | 未找到用户 |
|
||
| `09` | 用户已满 |
|
||
| `0A` | 人脸已录入 |
|
||
| `0C` | 活体检测失败 |
|
||
| `0D` | 超时 |
|
||
|
||
## 2. 通用测试准备
|
||
|
||
1. 打开串口：默认 `115200`，8N1。
|
||
2. 上电后先等模组主动发 READY：`EF AA 01 00 01 00 00`。
|
||
3. 如果没有 READY，可发送 `GET STATUS` 确认设备是否在线。
|
||
4. 中文用户名使用 UTF-8，定长 `user_name[32]` 不足补 `00`。
|
||
5. 多字节数值均为大端，例如用户 ID `1` 为 `00 01`。
|
||
|
||
## 3. 基础接口
|
||
|
||
| 接口 | MID | DATA | 示例发送 Hex | 成功回复 DATA |
|
||
| --- | --- | --- | --- | --- |
|
||
| 复位模组 | `10` | 无 | `EF AA 10 00 00 10` | 无 |
|
||
| 获取状态 | `11` | 无 | `EF AA 11 00 00 11` | `status` |
|
||
| 取消当前人脸流程 | `23` | 无 | `EF AA 23 00 00 23` | 无 |
|
||
| 获取版本 | `30` | 无 | `EF AA 30 00 00 30` | 版本字符串 |
|
||
| 获取 SN | `93` | 无 | `EF AA 93 00 00 93` | `Device_SN[32]`，前 8 bytes 有效 |
|
||
| 固件升级 | `F6` | 无 | `EF AA F6 00 00 F6` | 无，后续等 OTA 通知 |
|
||
|
||
状态值：
|
||
|
||
| Status | 说明 |
|
||
| --- | --- |
|
||
| `00` | Standby 待机 |
|
||
| `01` | Busy 忙碌 |
|
||
| `02` | Error 错误 |
|
||
| `03` | Invalid 无效 |
|
||
|
||
## 4. 人脸验证接口
|
||
|
||
### 4.1 普通验证 `VERIFY`
|
||
|
||
DATA：
|
||
|
||
```text
|
||
pd_rightaway timeout max_recognition_times
|
||
```
|
||
|
||
| 字段 | 示例 | 说明 |
|
||
| --- | --- | --- |
|
||
| `pd_rightaway` | `00` | 普通验证 |
|
||
| `timeout` | `0A` | 超时时间，单位秒 |
|
||
| `max_recognition_times` | `1E` | 最大识别次数 |
|
||
|
||
示例发送：
|
||
|
||
```text
|
||
EF AA 12 00 03 00 0A 1E 05
|
||
```
|
||
|
||
成功回复 DATA：
|
||
|
||
```text
|
||
user_id[2] user_name[32] admin unlock_status
|
||
```
|
||
|
||
### 4.2 自动验证 `AUTO_VERIFY`
|
||
|
||
DATA：
|
||
|
||
```text
|
||
at_verify timeout
|
||
```
|
||
|
||
| 字段 | 示例 | 说明 |
|
||
| --- | --- | --- |
|
||
| `at_verify` | `01` | `01` 开启，`00` 关闭 |
|
||
| `timeout` | `0A` | 超时时间，单位秒 |
|
||
|
||
示例发送：
|
||
|
||
```text
|
||
EF AA 12 00 02 01 0A 1B
|
||
```
|
||
|
||
## 5. 人脸录入接口
|
||
|
||
用户名字段：
|
||
|
||
```text
|
||
user_name[32]
|
||
```
|
||
|
||
例如 `张三` 的 UTF-8 bytes 为：
|
||
|
||
```text
|
||
E5 BC A0 E4 B8 89
|
||
```
|
||
|
||
写入 `user_name[32]` 时格式为：
|
||
|
||
```text
|
||
E5 BC A0 E4 B8 89 00 00 ... 共 32 bytes
|
||
```
|
||
|
||
方向值：
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `01` | 正脸 |
|
||
| `02` | 向右 |
|
||
| `04` | 向左 |
|
||
| `08` | 向下 |
|
||
| `10` | 向上 |
|
||
|
||
### 5.1 交互录入 `ENROLL`
|
||
|
||
DATA：
|
||
|
||
```text
|
||
admin user_name[32] face_dir timeout
|
||
```
|
||
|
||
示例：非管理员、空用户名、正脸、20 秒：
|
||
|
||
```text
|
||
EF AA 13 00 23 00
|
||
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
||
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
||
01 14 25
|
||
```
|
||
|
||
成功回复 DATA：
|
||
|
||
```text
|
||
user_id[2] face_direction
|
||
```
|
||
|
||
录入成功后建议立即发送 `GET USER INFO` 确认：
|
||
|
||
```text
|
||
EF AA 22 00 02 00 01 21
|
||
```
|
||
|
||
### 5.2 单帧录入 `ENROLL_SINGLE`
|
||
|
||
DATA 同 `ENROLL`，MID 改为 `1D`。
|
||
|
||
示例：非管理员、空用户名、正脸、20 秒：
|
||
|
||
```text
|
||
EF AA 1D 00 23 00
|
||
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
||
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
||
01 14 2B
|
||
```
|
||
|
||
### 5.3 集成录入 `ENROLL_ITG`
|
||
|
||
Unity 当前 DATA 顺序：
|
||
|
||
```text
|
||
admin user_name[32] face_dir timeout single_frame duplicate_flag reserved
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `single_frame` | `01` 单帧，`00` 交互 |
|
||
| `duplicate_flag` | `00` 查重，`01` 不查重 |
|
||
| `reserved` | 固定 `00` |
|
||
|
||
成功回复 DATA：
|
||
|
||
```text
|
||
user_id[2] face_direction
|
||
```
|
||
|
||
### 5.4 抓拍人脸后注册 `ENROLL_SNAPFACEIMAGE`
|
||
|
||
DATA：
|
||
|
||
```text
|
||
admin user_name[32] 00 00
|
||
```
|
||
|
||
成功回复 DATA：
|
||
|
||
```text
|
||
user_id[2] face_direction
|
||
```
|
||
|
||
## 6. 用户管理接口
|
||
|
||
| 接口 | MID | DATA | 示例发送 Hex | 成功回复 DATA |
|
||
| --- | --- | --- | --- | --- |
|
||
| 删除用户 | `20` | `user_id[2]` | `EF AA 20 00 02 00 01 23` | 无 |
|
||
| 删除全部用户 | `21` | 无 | `EF AA 21 00 00 21` | 无 |
|
||
| 查询用户信息 | `22` | `user_id[2]` | `EF AA 22 00 02 00 01 21` | `user_id[2] user_name[32] admin` |
|
||
| 查询所有用户 ID | `24` | `page_index` | `EF AA 24 00 01 00 25` | `count[1] user_id[]` |
|
||
| 查询所有用户 ID 2 | `25` | `page_index` | `EF AA 25 00 01 00 24` | `count[2] user_id[]` |
|
||
|
||
分页说明：
|
||
|
||
- `page_index` 从 `00` 开始。
|
||
- 每页最多 100 个 ID。
|
||
- 当返回数量小于 100 时，表示最后一页。
|
||
|
||
## 7. 二维码接口
|
||
|
||
DATA：
|
||
|
||
```text
|
||
00 timeout
|
||
```
|
||
|
||
示例：扫描 10 秒：
|
||
|
||
```text
|
||
EF AA 70 00 02 00 0A 78
|
||
```
|
||
|
||
成功回复 DATA：
|
||
|
||
```text
|
||
QR 字符串 bytes
|
||
```
|
||
|
||
模组也可能通过 NOTE `NID=0F` 主动上报二维码内容。
|
||
|
||
## 8. 图片抓拍接口
|
||
|
||
| 接口 | MID | DATA | 示例发送 Hex | 回复说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 普通图片抓拍 | `71` | 无 | `EF AA 71 00 00 71` | 先回复图片长度，再用 MID `71` 分包上传图片 |
|
||
| 人脸图片抓拍 | `72` | 无 | `EF AA 72 00 00 72` | 先回复图片长度和用户 ID，再用 MID `72` 分包上传图片 |
|
||
| 大图抓拍 | `74` | `dpi` | `EF AA 74 00 01 00 75` | 先回复图片长度，再用 MID `74` 分包上传图片 |
|
||
|
||
大图 DPI：
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `00` | 480x640 |
|
||
| `01` | 600x800 |
|
||
| `02` | 1200x1600 |
|
||
|
||
图片 DATA 包由模组发送，Unity 按数据总长度拼接。
|
||
|
||
## 9. 照片注册接口
|
||
|
||
### 9.1 推荐照片注册 `ENROLL_WITH_PHOTO`
|
||
|
||
初始化包 DATA：
|
||
|
||
```text
|
||
00 00 file_size[4] bio_type name_len name_bytes duplicate_flag
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
| --- | --- |
|
||
| `file_size[4]` | 图片或特征文件总长度，大端 |
|
||
| `bio_type` | `00` 普通照片，`01` 加密照片，`02` 普通特征，`03` 压缩特征 |
|
||
| `name_len` | 用户名 UTF-8 byte 长度 |
|
||
| `name_bytes` | 用户名 UTF-8 bytes |
|
||
| `duplicate_flag` | `00` 查重，`01` 不查重 |
|
||
|
||
示例：文件长度 1024，普通照片，姓名 `张三`，查重：
|
||
|
||
```text
|
||
EF AA F7 00 0F 00 00 00 00 04 00 00 06 E5 BC A0 E4 B8 89 00 D6
|
||
```
|
||
|
||
后续文件分包 DATA：
|
||
|
||
```text
|
||
seq[2] file_bytes
|
||
```
|
||
|
||
说明：
|
||
|
||
- `seq` 从 `00 01` 开始。
|
||
- 每包最多 246 bytes。
|
||
- 每包 MID 仍为 `F7`。
|
||
- 最后一包发送完成后，成功回复 DATA 通常包含 `user_id[2]`。
|
||
|
||
### 9.2 指定 ID 照片注册 `ENROLL_WITH_PHOTO_AND_ID`
|
||
|
||
初始化包 DATA：
|
||
|
||
```text
|
||
00 00 user_id[2] file_size[4] bio_type name_len name_bytes duplicate_flag
|
||
```
|
||
|
||
后续文件分包规则同 `F7`，MID 为 `D7`。
|
||
|
||
## 10. 特征接口
|
||
|
||
### 10.1 读取特征 `READ_FEATURE`
|
||
|
||
DATA：
|
||
|
||
```text
|
||
00 00 user_id[2] feature_type
|
||
```
|
||
|
||
示例：读取用户 1 的彩色人脸特征：
|
||
|
||
```text
|
||
EF AA FA 00 05 00 00 00 01 01 FF
|
||
```
|
||
|
||
特征类型：
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `01` | 彩色人脸 |
|
||
| `02` | 彩色加红外人脸 |
|
||
| `03` | 手掌 |
|
||
|
||
回复说明：
|
||
|
||
- 首个 REPLY DATA 返回特征总长度。
|
||
- 后续模组用 MID `FA` 分包发送特征 bytes。
|
||
|
||
### 10.2 写入特征 `WRITE_FEATURE`
|
||
|
||
初始化包 DATA：
|
||
|
||
```text
|
||
00 00 feature_type name_len name_bytes
|
||
```
|
||
|
||
后续特征分包 DATA：
|
||
|
||
```text
|
||
seq[2] feature_bytes
|
||
```
|
||
|
||
说明：
|
||
|
||
- `seq` 从 `00 01` 开始。
|
||
- 每包最多 246 bytes。
|
||
- 每包 MID 仍为 `FB`。
|
||
- 最后一包成功后回复 `user_id[2]`。
|
||
|
||
## 11. UVC 与高级设置接口
|
||
|
||
| 接口 | MID | DATA | 示例发送 Hex | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 读取 UVC 参数 | `B0` | 无 | `EF AA B0 00 00 B0` | 返回 `usb_type bitrate quality attributes` |
|
||
| 设置 UVC 参数 | `B1` | `usb_type bitrate quality attributes` | `EF AA B1 00 04 20 08 50 00 CD` | 示例为 USB2.0、8Mbps、质量 80、无镜像旋转 |
|
||
| 设置人脸框显示 | `B5` | `visible` | `EF AA B5 00 01 01 B5` | `01` 显示，`00` 隐藏 |
|
||
| 设置 RGB 阈值 | `D4` | `level` | `EF AA D4 00 01 02 D7` | `level` 范围 0 到 4 |
|
||
| 设置查重 | `FC` | `check_flag` | `EF AA FC 00 01 00 FD` | `00` 查重，`01` 不查重 |
|
||
| 查询查重 | `FC` | 无 | `EF AA FC 00 00 FC` | 返回查重状态 |
|
||
| 设置 Demo Mode | `FE` | `enable` | `EF AA FE 00 01 01 FE` | `01` 开启，`00` 关闭 |
|
||
|
||
UVC `attributes`：
|
||
|
||
| bit | 说明 |
|
||
| --- | --- |
|
||
| bit0 | 镜像 |
|
||
| bit1 | 旋转 180 度 |
|
||
|
||
## 12. 加密接口
|
||
|
||
| 接口 | MID | DATA | 示例发送 Hex |
|
||
| --- | --- | --- | --- |
|
||
| 初始化加密 | `50` | `seed[4] mode` | `EF AA 50 00 05 00 01 02 03 00 55` |
|
||
| 设置 Release Key | `52` | `key[16]` | `EF AA 52 00 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 42` |
|
||
| 设置 Debug Key | `53` | `key[16]` | `EF AA 53 00 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 43` |
|
||
|
||
说明：
|
||
|
||
- Key 必须为 16 bytes。
|
||
- 初始化加密后，后续是否需要加密封包取决于模组固件配置和供应商协议细节。
|
||
|
||
## 13. 推荐人工测试顺序
|
||
|
||
1. `GET STATUS`：确认串口可通信。
|
||
2. `GET VERSION` / `GET SN`：确认设备信息读取正常。
|
||
3. `VERIFY`：无用户时应返回未找到用户或超时。
|
||
4. `ENROLL_SINGLE` 或 `ENROLL`：录入一个测试用户。
|
||
5. `GET ALL USER ID`：确认用户列表出现新 ID。
|
||
6. `GET USER INFO`：确认用户名、管理员标记正确，中文姓名不应显示为 `?`。
|
||
7. `VERIFY`：确认刚录入的人脸可以验证成功。
|
||
8. `SNAP_UPLOAD_IMAGE`：确认图片分包可以完整拼接。
|
||
9. `READ/WRITE FEATURE`、照片注册、UVC 参数、加密接口按需要继续验证。
|
||
|
||
## 14. 常见问题
|
||
|
||
| 现象 | 排查方向 |
|
||
| --- | --- |
|
||
| 串口打开但无回复 | 确认波特率、TX/RX 线序、供电、GND、是否收到 READY |
|
||
| 校验失败 | 重新计算 `CHECKSUM = MID ^ SIZE_H ^ SIZE_L ^ DATA...` |
|
||
| 中文姓名变成 `?` | 确认发送端使用 UTF-8，不要使用 ASCII |
|
||
| 录入成功但列表无用户 | 录入成功后立即发 `GET ALL USER ID` 和 `GET USER INFO` 确认 |
|
||
| 图片或特征不完整 | 串口助手需要保留二进制原始 bytes，不能按文本行读取 |
|
||
| 多包命令超时 | 分包 `seq` 从 `00 01` 开始，每包最大 246 bytes |
|
||
|