si-m1-face-package/Documentation~/串口指令测试说明.md

SI-M1 串口指令测试说明

本文档用于串口助手或底层串口程序直接测试 SI-M1 人脸识别模组协议。Unity 端同样按本文的封包格式发送命令。

1. 基础封包格式

主控发送：

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] ^ ...

模组回复：

EF AA 00 SIZE_H SIZE_L MID RESULT DATA... CHECKSUM

主动通知：

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：

pd_rightaway timeout max_recognition_times

字段	示例	说明
pd_rightaway	00	普通验证
timeout	0A	超时时间，单位秒
max_recognition_times	1E	最大识别次数

示例发送：

EF AA 12 00 03 00 0A 1E 05

成功回复 DATA：

user_id[2] user_name[32] admin unlock_status

4.2 自动验证 AUTO_VERIFY

DATA：

at_verify timeout

字段	示例	说明
at_verify	01	01 开启，00 关闭
timeout	0A	超时时间，单位秒

示例发送：

EF AA 12 00 02 01 0A 1B

5. 人脸录入接口

用户名字段：

user_name[32]

例如 张三 的 UTF-8 bytes 为：

E5 BC A0 E4 B8 89

写入 user_name[32] 时格式为：

E5 BC A0 E4 B8 89 00 00 ... 共 32 bytes

方向值：

值	说明
01	正脸
02	向右
04	向左
08	向下
10	向上

5.1 交互录入 ENROLL

DATA：

admin user_name[32] face_dir timeout

示例：非管理员、空用户名、正脸、20 秒：

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：

user_id[2] face_direction

录入成功后建议立即发送 GET USER INFO 确认：

EF AA 22 00 02 00 01 21

5.2 单帧录入 ENROLL_SINGLE

DATA 同 ENROLL，MID 改为 1D。

示例：非管理员、空用户名、正脸、20 秒：

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 顺序：

admin user_name[32] face_dir timeout single_frame duplicate_flag reserved

字段	说明
single_frame	01 单帧，00 交互
duplicate_flag	00 查重，01 不查重
reserved	固定 00

成功回复 DATA：

user_id[2] face_direction

5.4 抓拍人脸后注册 ENROLL_SNAPFACEIMAGE

DATA：

admin user_name[32] 00 00

成功回复 DATA：

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：

00 timeout

示例：扫描 10 秒：

EF AA 70 00 02 00 0A 78

成功回复 DATA：

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：

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，普通照片，姓名 张三，查重：

EF AA F7 00 0F 00 00 00 00 04 00 00 06 E5 BC A0 E4 B8 89 00 D6

后续文件分包 DATA：

seq[2] file_bytes

说明：

• seq 从 00 01 开始。
• 每包最多 246 bytes。
• 每包 MID 仍为 F7。
• 最后一包发送完成后，成功回复 DATA 通常包含 user_id[2]。

9.2 指定 ID 照片注册 ENROLL_WITH_PHOTO_AND_ID

初始化包 DATA：

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：

00 00 user_id[2] feature_type

示例：读取用户 1 的彩色人脸特征：

EF AA FA 00 05 00 00 00 01 01 FF

特征类型：

值	说明
01	彩色人脸
02	彩色加红外人脸
03	手掌

回复说明：

• 首个 REPLY DATA 返回特征总长度。
• 后续模组用 MID FA 分包发送特征 bytes。

10.2 写入特征 WRITE_FEATURE

初始化包 DATA：

00 00 feature_type name_len name_bytes

后续特征分包 DATA：

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