607 lines
19 KiB
Markdown
607 lines
19 KiB
Markdown
# SI-M1 人脸识别算法模组通信协议 V2.63：文档功能总结
|
||
|
||
> 来源文档：`SI-M1人脸识别算法模组通信协议V2.63.pdf`
|
||
> 整理目的：把通信协议、功能命令、返回消息、业务流程整理成可读的功能说明，便于后续 Unity 对接实现。
|
||
|
||
---
|
||
|
||
## 1. 文档定位
|
||
|
||
这份文档不是“人脸识别算法原理说明”，而是 **SI-M1 人脸识别算法模组的主控通信协议说明**。
|
||
|
||
核心关系：
|
||
|
||
```text
|
||
Unity / PC 主控程序 <----串口通信链路----> SI-M1 人脸识别算法模组
|
||
```
|
||
|
||
模组处于 **从属设备** 地位：
|
||
|
||
- 主控负责发送命令；
|
||
- 模组负责执行人脸识别、录入、删除、查询、抓拍、二维码识别、特征读写等动作；
|
||
- 模组通过 `REPLY`、`NOTE`、`ImageOrTemplate` 三类消息主动/被动返回结果。
|
||
|
||
---
|
||
|
||
## 2. 通信消息格式
|
||
|
||
所有消息统一使用以下帧格式：
|
||
|
||
| 字段 | 长度 | 说明 |
|
||
|---|---:|---|
|
||
| SyncWord | 2 bytes | 固定同步头：`0xEF 0xAA` |
|
||
| MsgID | 1 byte | 消息 ID / 命令 ID / 返回类型 |
|
||
| Size | 2 bytes | Data 长度，高字节在前，单位 byte |
|
||
| Data | N bytes | 命令参数或返回数据，N 可为 0 |
|
||
| ParityCheck | 1 byte | 校验码 |
|
||
|
||
### 2.1 校验规则
|
||
|
||
校验码计算方式：
|
||
|
||
```text
|
||
ParityCheck = MsgID ^ SizeHigh ^ SizeLow ^ Data[0] ^ Data[1] ^ ... ^ Data[N-1]
|
||
```
|
||
|
||
注意：
|
||
|
||
- 不包含 `SyncWord`；
|
||
- `Size` 是大端模式，即高八位在前；
|
||
- Data 为空时，只对 `MsgID + SizeHigh + SizeLow` 做 XOR；
|
||
- RESET 示例：`EF AA 10 00 00 10`
|
||
|
||
---
|
||
|
||
## 3. 主控发送给模组的命令功能
|
||
|
||
### 3.1 基础控制类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 复位 / 取消当前任务 | RESET | `0x10` | 无 | 取消录入、验证等正在执行的任务，使模组回到 Standby |
|
||
| 获取状态 | GET STATUS | `0x11` | 无 | 获取模组当前状态 |
|
||
| 清除录入状态 | FACE RESET | `0x23` | 无 | 终止录入流程并清除录入状态 |
|
||
| 获取版本 | GET VERSION | `0x30` | 无 | 获取软件版本信息 |
|
||
| 获取设备序列号 | MID_GET_SN | `0x93` | 无 | 获取设备唯一 SN，返回 32 bytes，前 8 bytes 有效 |
|
||
| Demo 模式 | DEMO MODE | `0xFE` | enable 1 byte | 进入演示模式，所有人可解锁，但仍做活体检测 |
|
||
|
||
---
|
||
|
||
### 3.2 人脸验证类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 人脸验证 | VERIFY | `0x12` | `pd_rightaway` + `timeout` + 可选 `Max_Recognition_times` | 启动一次人脸验证 |
|
||
| 低功耗自动探测验证 | AUTO_VERIFY | `0x12` | `at_verify` + `timeout` | AI-10 适用，检测到人脸或二维码后自动识别 |
|
||
|
||
#### VERIFY 参数
|
||
|
||
| 字段 | 长度 | 说明 |
|
||
|---|---:|---|
|
||
| pd_rightaway | 1 byte | 文档中作为保留字段，默认 0 |
|
||
| timeout | 1 byte | 解锁超时时间，单位秒，最大 255 |
|
||
| Max_Recognition_times | 1 byte，可选 | 最大识别尝试次数，不发送时默认 30 |
|
||
|
||
特殊注意：
|
||
|
||
- 照片注册后，第一次识别成功会补全红外模板并保存到 Flash；
|
||
- 主控在收到 REPLY 应答或超时后，应延时约 2 秒再断电。
|
||
|
||
---
|
||
|
||
### 3.3 人脸录入类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 交互录入 | ENROLL | `0x13` | admin + user_name + face_dir + timeout | 按指定方向录入人脸 |
|
||
| 单帧录入 | ENROLL_SINGLE | `0x1D` | admin + user_name + face_dir + timeout | 只需一张正脸即可注册 |
|
||
| 集成录入 | MID_ENROLL_ITG | `0x26` | admin + user_name + face_dir + enroll_type + enable_duplicate + timeout + reserved | ENROLL 的扩展版本，支持交互/单帧和重复录入策略 |
|
||
| 抓拍人脸后注册 | ENROLL_SNAPFACEIMAGE | `0x73` | admin + user_name + reserved + reserved | 配合 0x72 未搜索到本地用户时使用，不查重 |
|
||
|
||
#### ENROLL 参数
|
||
|
||
| 字段 | 长度 | 说明 |
|
||
|---|---:|---|
|
||
| admin | 1 byte | 是否管理员，1 是，0 否 |
|
||
| user_name | 32 bytes | 用户姓名 |
|
||
| face_dir | 1 byte | 录入方向 |
|
||
| timeout | 1 byte | 录入超时时间，单位秒 |
|
||
|
||
#### 人脸方向定义
|
||
|
||
| 方向 | Code | 说明 |
|
||
|---|---:|---|
|
||
| FACE_DIRECTION_UP | `0x10` | 朝上 |
|
||
| FACE_DIRECTION_DOWN | `0x08` | 朝下 |
|
||
| FACE_DIRECTION_LEFT | `0x04` | 朝左 |
|
||
| FACE_DIRECTION_RIGHT | `0x02` | 朝右 |
|
||
| FACE_DIRECTION_MIDDLE | `0x01` | 正脸 |
|
||
| FACE_DIRECTION_UNDEFINE | `0x00` | 未定义，默认正脸 |
|
||
|
||
#### 交互录入说明
|
||
|
||
录入过程中：
|
||
|
||
1. 主控发送指定方向录入命令；
|
||
2. 模组通过 NOTE 返回人脸状态、位置、姿态；
|
||
3. Unity 根据 NOTE 信息提示用户调整姿态；
|
||
4. 模组通过 REPLY 返回最终录入结果；
|
||
5. 录入中可通过 FACE RESET 终止；
|
||
6. 录入过程中突然断电，之前录入的人脸不会保存。
|
||
|
||
#### 录入角度说明
|
||
|
||
| 方向 | 推荐偏转角度 |
|
||
|---|---|
|
||
| 正脸 | 正对摄像头 |
|
||
| 向上 | 正脸向上偏转 5~55 度 |
|
||
| 向下 | 正脸向下偏转 5~55 度 |
|
||
| 向右 | 正脸向右偏转 8~60 度 |
|
||
| 向左 | 正脸向左偏转 8~60 度 |
|
||
|
||
不建议使用 Roll 倾斜头部方式录入，应缓慢转头并保持偏转。
|
||
|
||
---
|
||
|
||
### 3.4 用户管理类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 删除指定用户 | DELETE USER | `0x20` | user_id 高字节 + 低字节 | 删除一个已注册用户 |
|
||
| 删除全部用户 | DELETE ALL | `0x21` | 无 | 删除所有注册用户 |
|
||
| 查询用户信息 | GET USER INFO | `0x22` | user_id 高字节 + 低字节 | 返回用户 ID、姓名、管理员标志 |
|
||
| 获取所有用户 ID | MID_GET_ALL_USERID | `0x24` | alluserid_index | 每包最多 100 个用户 ID |
|
||
| 获取所有用户 ID 2 | MID_GET_ALL_USERID2 | `0x25` | alluserid_index | AI-10 适用，user_counts 为 2 bytes |
|
||
|
||
---
|
||
|
||
### 3.5 加密通信类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 初始化加密 | INIT ENCRYPTION | `0x50` | seed[4] + mode | 主控发送随机数 |
|
||
| 设置 Release 加密序列 | MID_SET_RELEASE_ENC_KEY | `0x52` | enc_key_number[16] | 设置正式协议加密序列 |
|
||
| 设置 Debug 加密序列 | MID_SET_DEBUG_ENC_KEY | `0x53` | enc_key_number[16] | 设置调试协议加密序列 |
|
||
|
||
加密流程：
|
||
|
||
1. 主控给模组上电；
|
||
2. 模组发送明文 READY；
|
||
3. 第一次使用需设置 16 bytes Release 加密序列；
|
||
4. 主控生成 4 bytes 随机数发送给模组；
|
||
5. 双方基于随机数和私有协议生成 16 bytes 会话密码；
|
||
6. 后续通信使用 AES/SMPL 加密；
|
||
7. 主控解密设备 ID 并确认设备身份；
|
||
8. 后续录入、验证等命令均按加密方式发送和接收。
|
||
|
||
> 实现注意：文档没有给出完整私有密钥派生算法和 AES/SMPL 细节，Unity 侧如需启用加密通信，需要供应商提供 SDK、算法源码或加密协议补充文档。
|
||
|
||
---
|
||
|
||
### 3.6 USB / 图像参数类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 读取 USB UVC 参数 | READ_USB_UVC_PARAMETERS | `0xB0` | 无 | 读取传图参数 |
|
||
| 设置 USB UVC 参数 | SET_USB_UVC_PARAMETERS | `0xB1` | USB Type + UVC 码率 + MJPG 质量 + 图像属性 | 设置传图模式、码率、质量、镜像/倒转 |
|
||
| 设置人脸框显示 | SET_FACE_LOCATION_DISPLAY | `0xB5` | 0/1 | 设置是否显示人脸框 |
|
||
|
||
USB Type 示例：
|
||
|
||
| 值 | 含义 |
|
||
|---:|---|
|
||
| `0x11` | USB1.1 + Bulk |
|
||
| `0x20` | USB2.0 + Bulk |
|
||
| `0x91` | USB1.1 + ISOC |
|
||
| `0xA0` | USB2.0 + ISOC |
|
||
|
||
图像属性：
|
||
|
||
| Bit | 说明 |
|
||
|---|---|
|
||
| BIT0 | 1 启用镜像 |
|
||
| BIT1 | 1 启用 180 度倒转 |
|
||
|
||
---
|
||
|
||
### 3.7 二维码识别类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 扫描二维码 | MID_SCAN_QR_CODE | `0x70` | 0x00 + timeout | 读取二维码信息 |
|
||
| 自动探测二维码 | AUTO_VERIFY | `0x12` | at_verify + timeout | AI-10 低功耗自动探测模式下自动识别二维码 |
|
||
|
||
二维码 NOTE：
|
||
|
||
- `NID_QR_DATA_FLAGS = 15` 表示 QR 数据；
|
||
- 可识别二维码不大于 250 bytes ASCII；
|
||
- 不包含中文。
|
||
|
||
---
|
||
|
||
### 3.8 抓拍与图片上传类
|
||
|
||
| 功能 | 命令 | Code | 数据包规则 | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 抓拍普通图片 | MID_SNAP&UPLOAD_IMAGE | `0x71` | 每包 1024 bytes，最后一包按实际长度 | 240×320 图片 |
|
||
| 抓拍人脸图片 | MID_SNAP&UPLOAD_FACEIMAGE | `0x72` | 每包 1024 bytes，最后一包按实际长度 | 320×320 人脸图，本地比对后上传 |
|
||
| 抓拍全视角大图 | MID_SNAP&UPLOAD_IMAGE_B | `0x74` | 每包 1024 bytes，支持 DPI 参数 | 480×640 / 600×800 / 1200×1600 |
|
||
|
||
0x74 DPI 参数：
|
||
|
||
| DPI | 分辨率 |
|
||
|---:|---|
|
||
| 0 | 480×640 |
|
||
| 1 | 600×800 |
|
||
| 2 | 1200×1600，仅 AI-10 有效 |
|
||
|
||
---
|
||
|
||
### 3.9 照片 / 特征下发注册类
|
||
|
||
| 功能 | 命令 | Code | 说明 |
|
||
|---|---|---:|---|
|
||
| 照片/特征注册，指定 ID | MID_ENROLL_WITH_PHOTO&ID | `0xD7` | 文档建议优先使用 0xF7 |
|
||
| 照片/特征注册 | MID_ENROLL_WITH_PHOTO | `0xF7` | 推荐使用 |
|
||
| 设置彩色识别阈值 | RGB_LEVEL | `0xD4` | 彩色识别阈值 0~4，默认 2 |
|
||
|
||
#### MID_ENROLL_WITH_PHOTO 0xF7 流程
|
||
|
||
1. 第一包：`Seq = 0`；
|
||
2. Data 包含：
|
||
- `00`
|
||
- `00`
|
||
- 照片/特征长度，4 bytes，大端；
|
||
- BioType；
|
||
- 可选姓名长度；
|
||
- 可选姓名字符串；
|
||
- 可选重复检查标志；
|
||
3. 模组返回 Result 和 Seq；
|
||
4. Result 成功后，主控从 `Seq = 1` 开始发送数据；
|
||
5. 每包数据最大 MTU ≤ 246 bytes；
|
||
6. 最后一包不足 246 bytes 时按实际长度发送；
|
||
7. 发送完成后，模组返回最终注册结果和 UserID。
|
||
|
||
#### BioType 定义
|
||
|
||
| 值 | 说明 |
|
||
|---:|---|
|
||
| 0 | 普通照片 |
|
||
| 1 | 加密照片 |
|
||
| 2 | 普通特征码：2048 bytes 彩色，或 4096 bytes 彩色+红外 |
|
||
| 3 | 压缩特征码：1024 bytes |
|
||
|
||
特征文件长度：
|
||
|
||
| 类型 | 文件总长度 | 内容 |
|
||
|---|---:|---|
|
||
| 彩色+红外特征 | 4100 bytes | 4096 bytes 特征码 + 4 bytes CRC32 |
|
||
| 彩色特征 | 2052 bytes | 2048 bytes 特征码 + 4 bytes CRC32 |
|
||
| 压缩特征 | 1028 bytes | 1024 bytes 特征码 + 4 bytes CRC32 |
|
||
|
||
CRC32 初始向量值：`0xFFFFFFFF`。
|
||
|
||
---
|
||
|
||
### 3.10 特征读写类（AI-10）
|
||
|
||
| 功能 | 命令 | Code | 说明 |
|
||
|---|---|---:|---|
|
||
| 读取特征 | MID_READ_FEATURE | `0xFA` | 按用户 ID 和特征类型读取模板 |
|
||
| 写入特征 | MID_WRITE_FEATURE | `0xFB` | 分包写入模板数据 |
|
||
|
||
Feature Type：
|
||
|
||
| 值 | 说明 |
|
||
|---:|---|
|
||
| 1 | 彩色人脸模板 |
|
||
| 2 | 彩色 + 红外人脸模板 |
|
||
| 3 | 掌纹掌静脉模板 |
|
||
|
||
分包规则：
|
||
|
||
- 每包 246 bytes；
|
||
- 从包序号 1 开始递增；
|
||
- 最后一包按实际剩余长度；
|
||
- 读取特征时先返回特征长度，再按包上传；
|
||
- 写入特征时先发送特征类型，再分包写入。
|
||
|
||
---
|
||
|
||
### 3.11 查重配置类
|
||
|
||
| 功能 | 命令 | Code | Data | 说明 |
|
||
|---|---|---:|---|---|
|
||
| 设置查重 | MID_DUPLICATE_CHECK | `0xFC` | Checkflag | 设置本地注册是否查重 |
|
||
| 查询查重状态 | MID_READ_DUPLICATE_CHECK | `0xFC` | 无 | 不带参数时查询当前查重状态 |
|
||
|
||
Checkflag：
|
||
|
||
| 值 | 文档说明 |
|
||
|---:|---|
|
||
| 0 | 查重 |
|
||
| 1 | 不查重 |
|
||
|
||
说明：
|
||
|
||
- 默认查重；
|
||
- 设置后立即生效并保存到 Flash；
|
||
- 重启后仍有效；
|
||
- SI-M1 V2.10 以上支持。
|
||
|
||
---
|
||
|
||
### 3.12 固件升级类
|
||
|
||
| 功能 | 命令 | Code | 说明 |
|
||
|---|---|---:|---|
|
||
| U 盘升级固件 | MID_UPGRADE_FW | `0xF6` | 启动通过 U 盘升级模组固件 |
|
||
|
||
返回数据中包含升级进度百分比。
|
||
|
||
---
|
||
|
||
## 4. 模组返回给主控的消息
|
||
|
||
模组主要返回三类消息：
|
||
|
||
| 类型 | MsgID | 说明 |
|
||
|---|---:|---|
|
||
| REPLY | `0x00` | 命令最终执行结果 |
|
||
| NOTE | `0x01` | 模组主动通知，例如 READY、人脸状态、二维码数据 |
|
||
| ImageOrTemplate | 业务 mid | 图片或特征模板数据流 |
|
||
|
||
---
|
||
|
||
## 5. REPLY 消息
|
||
|
||
### 5.1 REPLY 格式
|
||
|
||
```text
|
||
SyncWord MsgID=0x00 Size Data Checksum
|
||
Data = mid + result + data[n]
|
||
```
|
||
|
||
| 字段 | 说明 |
|
||
|---|---|
|
||
| mid | 被回复的命令 ID |
|
||
| result | 命令执行结果 |
|
||
| data | 不同命令对应的返回数据 |
|
||
|
||
### 5.2 常见 REPLY 返回数据
|
||
|
||
| mid | Code | 成功时返回 |
|
||
|---|---:|---|
|
||
| MID_GETSTATUS | `0x11` | status |
|
||
| MID_VERIFY | `0x12` | user_id + user_name + admin + unlockStatus |
|
||
| MID_ENROLL | `0x13` | user_id + face_direction |
|
||
| MID_ENROLL_SINGLE | `0x1D` | user_id + face_direction |
|
||
| MID_GETUSERINFO | `0x22` | user_id + user_name + admin |
|
||
| MID_GET_ALL_USERID | `0x24` | user_counts + users_id[] |
|
||
| MID_GET_VERSION | `0x30` | version data |
|
||
| MID_INIT_ENCRYPTION | `0x50` | device_id[20] |
|
||
| MID_GET_SN | `0x93` | Device_SN[32]，前 8 bytes 有效 |
|
||
| MID_SCAN_QR_CODE | `0x70` | QR CODE |
|
||
| MID_SNAP_UPLOAD_IMAGE | `0x71` | result + photo_len 或图片数据 |
|
||
| MID_SNAP_UPLOAD_FACEIMAGE | `0x72` | result + photo_len + user_id 或图片数据 |
|
||
| MID_ENROLL_WITH_PHOTO | `0xF7` | seq + user_id |
|
||
| MID_READ_FEATURE | `0xFA` | result + seq + feature_len 或特征数据 |
|
||
| MID_WRITE_FEATURE | `0xFB` | result + seq + user_id |
|
||
| MID_READ_DUPLICATE_CHECK | `0xFC` | state + duplicate |
|
||
|
||
---
|
||
|
||
## 6. Result 结果码
|
||
|
||
| Code | 名称 | 说明 |
|
||
|---:|---|---|
|
||
| 0 | MR_SUCCESS | 成功 |
|
||
| 1 | MR_REJECTED | 模组拒绝命令 |
|
||
| 2 | MR_ABORTED | 录入/验证算法终止 |
|
||
| 4 | MR_FAILED4_CAMERA | 相机打开失败 |
|
||
| 5 | MR_FAILED4_UNKNOWNREASON | 未知错误 |
|
||
| 6 | MR_FAILED4_INVALIDPARAM | 参数无效 |
|
||
| 7 | MR_FAILED4_NOMEMORY | 内存不足 |
|
||
| 8 | MR_FAILED4_UNKNOWNUSER | 没有已录入用户 |
|
||
| 9 | MR_FAILED4_MAXUSER | 超过最大用户数量 |
|
||
| 10 | MR_FAILED4_FACEENROLLED | 人脸已录入 |
|
||
| 12 | MR_FAILED4_LIVENESSCHECK | 活体检测失败 |
|
||
| 13 | MR_FAILED4_TIMEOUT | 录入或解锁超时 |
|
||
| 14 | MR_FAILED4_AUTHORIZATION | 加密芯片授权失败 |
|
||
| 19 | MR_FAILED4_READ_FILE | 读文件失败 |
|
||
| 20 | MR_FAILED4_WRITE_FILE | 写文件失败 |
|
||
| 21 | MR_FAILED4_NO_ENCRYPT | 通信协议未加密 |
|
||
| 23 | MR_FAILED4_NO_RGBIMAGE | RGB 图像没有 ready |
|
||
| 24 | MR_FAILED4_JPGPHOTO_LARGE | JPG 照片过大 |
|
||
| 25 | MR_FAILED4_JPGPHOTO_SMALL | JPG 照片过小 |
|
||
| 26 | MR_FAILED4_DETECT_QR | 识别过程中扫描并解码了二维码 |
|
||
|
||
---
|
||
|
||
## 7. NOTE 消息
|
||
|
||
### 7.1 NOTE 格式
|
||
|
||
```text
|
||
SyncWord MsgID=0x01 Size Data Checksum
|
||
Data = nid + data[n]
|
||
```
|
||
|
||
### 7.2 NID 定义
|
||
|
||
| NID | Code | 说明 |
|
||
|---|---:|---|
|
||
| NID_READY | 0 | 模组已准备好 |
|
||
| NID_FACE_STATE | 1 | 返回人脸状态、位置、姿态 |
|
||
| NID_UNKNOWNERROR | 2 | 未知错误 |
|
||
| NID_OTA_DONE | 3 | OTA 完成 |
|
||
| NID_EYE_STATE | 4 | 眼睛状态 |
|
||
| NID_AUTO_VERIFY | 10 | 自动检测状态 |
|
||
| NID_QR_DATA_FLAGS | 15 | 二维码数据 |
|
||
|
||
---
|
||
|
||
## 8. NID_FACE_STATE 人脸状态数据
|
||
|
||
数据结构：
|
||
|
||
| 字段 | 类型 | 长度 | 说明 |
|
||
|---|---|---:|---|
|
||
| state | int16 | 2 bytes | 人脸状态 |
|
||
| left | int16 | 2 bytes | 人脸框左侧距离 |
|
||
| top | int16 | 2 bytes | 人脸框上方距离 |
|
||
| right | int16 | 2 bytes | 人脸框右侧距离 |
|
||
| bottom | int16 | 2 bytes | 人脸框下方距离 |
|
||
| yaw | int16 | 2 bytes | 左右转头角度，负为左转，正为右转 |
|
||
| pitch | int16 | 2 bytes | 上下抬头/低头，负为抬头，正为低头 |
|
||
| roll | int16 | 2 bytes | 歪头角度，负为右歪，正为左歪 |
|
||
|
||
### 8.1 Face State Code
|
||
|
||
| Code | 名称 | 说明 |
|
||
|---:|---|---|
|
||
| 0 | FACE_STATE_NORMAL | 人脸正常 |
|
||
| 1 | FACE_STATE_NOFACE | 未检测到人脸 |
|
||
| 2 | FACE_STATE_TOOUP | 太靠近上边沿 |
|
||
| 3 | FACE_STATE_TOODOWN | 太靠近下边沿 |
|
||
| 4 | FACE_STATE_TOOLEFT | 太靠近左边沿 |
|
||
| 5 | FACE_STATE_TOORIGHT | 太靠近右边沿 |
|
||
| 6 | FACE_STATE_FAR | 距离太远 |
|
||
| 7 | FACE_STATE_CLOSE | 距离太近 |
|
||
| 8 | FACE_STATE_EYEBROW_OCCLUSION | 眉毛遮挡 |
|
||
| 9 | FACE_STATE_EYE_OCCLUSION | 眼睛遮挡 |
|
||
| 10 | FACE_STATE_FACE_OCCLUSION | 脸部遮挡 |
|
||
| 11 | FACE_STATE_DIRECTION_ERROR | 录入方向错误 |
|
||
| 12 | FACE_STATE_EYE_CLOSE_STATUS_OPEN_EYE | 闭眼模式检测到睁眼 |
|
||
| 13 | FACE_STATE_EYE_CLOSE_STATUS | 闭眼状态 |
|
||
| 14 | FACE_STATE_EYE_CLOSE_UNKNOWN_STATUS | 无法判定睁闭眼 |
|
||
| 128 | PV_STATE_NORMAL | 检测到手掌信息 |
|
||
|
||
---
|
||
|
||
## 9. 核心业务流程
|
||
|
||
### 9.1 主控接收消息流程
|
||
|
||
```text
|
||
串口接收字节流
|
||
↓
|
||
查找同步头 EF AA
|
||
↓
|
||
读取 MsgID
|
||
↓
|
||
读取 Size 高低字节
|
||
↓
|
||
读取 Data
|
||
↓
|
||
读取 Checksum 并校验
|
||
↓
|
||
根据 MsgID 分发：
|
||
- 0x00：REPLY
|
||
- 0x01：NOTE
|
||
- 其他：ImageOrTemplate
|
||
```
|
||
|
||
### 9.2 一般命令处理流程
|
||
|
||
```text
|
||
主控发送命令
|
||
↓
|
||
模组执行命令
|
||
↓
|
||
期间可能持续返回 NOTE
|
||
↓
|
||
最终返回 REPLY
|
||
↓
|
||
主控根据 result 判断成功/失败
|
||
```
|
||
|
||
如果超时或无结果：
|
||
|
||
- 主控可发送 GET STATUS 查询状态；
|
||
- 如果模组仍 BUSY，可等待、取消或 RESET；
|
||
- 如果出现 ERROR/INVALID，应提示异常或重新上电。
|
||
|
||
### 9.3 上下电流程
|
||
|
||
```text
|
||
主控给模组上电
|
||
↓
|
||
模组初始化
|
||
↓
|
||
模组发送 NOTE:READY
|
||
↓
|
||
主控开始发送业务命令
|
||
↓
|
||
模组处理并返回结果
|
||
↓
|
||
主控确认无消息或超时后可断电
|
||
```
|
||
|
||
### 9.4 录入流程
|
||
|
||
```text
|
||
发送 ENROLL / ENROLL_ITG
|
||
↓
|
||
模组返回 NOTE:FACE_STATE
|
||
↓
|
||
Unity 提示用户调整距离、方向、姿态
|
||
↓
|
||
模组返回 REPLY:ENROLL
|
||
↓
|
||
成功：记录 user_id 和 face_direction
|
||
失败：显示 result 对应原因
|
||
```
|
||
|
||
### 9.5 验证流程
|
||
|
||
```text
|
||
发送 VERIFY
|
||
↓
|
||
模组返回 NOTE:FACE_STATE
|
||
↓
|
||
Unity 实时显示检测状态
|
||
↓
|
||
模组返回 REPLY:VERIFY
|
||
↓
|
||
成功：得到 user_id / user_name / admin
|
||
失败：显示错误原因
|
||
```
|
||
|
||
### 9.6 照片下发注册流程
|
||
|
||
```text
|
||
发送 0xF7 第一包：Seq=0 + PhotoLen + BioType + 可选扩展参数
|
||
↓
|
||
模组 ACK
|
||
↓
|
||
主控 Seq 从 1 开始分包发送照片/特征数据
|
||
↓
|
||
每包 MTU ≤ 246 bytes
|
||
↓
|
||
模组逐包 ACK
|
||
↓
|
||
最后返回 UserID
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 文档中的关键实现风险
|
||
|
||
| 风险 | 说明 | 建议 |
|
||
|---|---|---|
|
||
| 加密协议不完整 | 文档未给出私有密钥派生算法和 AES/SMPL 细节 | 向供应商索取 SDK 或补充协议 |
|
||
| 0x12 同时用于 VERIFY 和 AUTO_VERIFY | 同一 MsgID 下 Data 结构不同 | Unity API 层必须区分调用场景 |
|
||
| 0x71 / 0x72 / 0x74 返回数据有两阶段 | 第一阶段返回长度，第二阶段返回图片包 | 需要做图片接收状态机 |
|
||
| 0xF7 照片注册需要分包 | 每包 ≤246 bytes，需等待 ACK 后继续 | 必须实现可靠分包发送队列 |
|
||
| 图片包为二进制流 | Unity 需要缓存 byte[] 并转换 Texture2D | 注意主线程 UI 更新 |
|
||
| 中文姓名编码未明确 | 文档仅说明 user_name 32 bytes / NameString 长度 | 建议先按 ASCII/UTF-8 测试，最终以供应商确认为准 |
|
||
| UVC 视频预览与串口协议是两条链路 | 文档里有 USB UVC 参数，但协议数据只负责控制 | Unity 视频画面需要单独使用 UVC/USB 摄像头方案 |
|
||
|
||
---
|
||
|
||
## 11. 一句话总结
|
||
|
||
这份文档定义了 **主控与 SI-M1 人脸识别模组之间的二进制通信协议**，主控通过固定帧格式发送录入、验证、删除、查询、抓拍、二维码、照片注册、特征读写、加密、UVC 参数、升级等命令；模组通过 REPLY 返回最终结果，通过 NOTE 主动上报状态，通过 ImageOrTemplate 分包上传图片或特征模板。
|
||
|