# 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 分包上传图片或特征模板。