si-m1-face-package/Documentation~/SDK_Configuration.md

SI-M1 Face SDK 配置与 Editor 工具

SDK 使用 FaceSdkSettings 作为推荐配置方式。该配置是 ScriptableObject，可在项目中复用，并可同步到场景中的 FaceModuleManager。

1. 默认配置资产

默认路径：

Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset

打开菜单 AISU/SI-M1 Face SDK/Settings 后，Editor 会加载该路径。若文件不存在，点击 Load Default 会创建默认资产。

2. FaceSdkSettings 字段

字段	类型	说明
TransportMode	FaceTransportMode	通信模式：Auto、SerialPort、Mock
UseMockInEditor	bool	Editor 下是否强制使用 Mock
PortName	string	Player / 运行时串口号
BaudRate	int	Player / 运行时波特率
ReadBufferSize	int	Player / 运行时读取缓冲区
UseEditorSerialDebugParameters	bool	Editor 下连接真实串口时是否使用单独参数
EditorPortName	string	Editor 调试串口号
EditorBaudRate	int	Editor 调试波特率
EditorReadBufferSize	int	Editor 调试读取缓冲区
MockResponseDelayFrames	int	Mock 响应延迟帧数
AutoVerifyOnOpen	bool	READY 后是否自动开启验证
AutoVerifyTimeout	byte	自动验证协议超时时间，单位秒
AutoVerifyResultIntervalMs	int	自动验证结果最小派发间隔，0 表示不节流
StopAutoVerifyBeforeExclusiveCommand	bool	独占业务命令前是否自动关闭自动验证
ExclusiveCommandPolicy	FaceExclusiveCommandPolicy	自动验证开启时的独占命令处理策略
DebugLogEnabled	bool	是否启用 SDK Debug 日志
RawLogEnabled	bool	是否派发原始 TX / RX 日志
LogPrefix	string	日志前缀

3. TransportMode 选择

模式	行为
Auto	Editor 根据 UseMockInEditor 选择 Mock 或串口；Player 使用串口
SerialPort	使用 SerialPortTransport
Mock	使用 MockFaceModuleTransport

Editor 下有一个额外优先级：

UseMockInEditor = true 时，强制使用 Mock，不打开真实串口。

因此 Editor 中如果需要连接真实串口，必须将 UseMockInEditor 设为 false。

4. Editor Serial Debug 参数

Editor 连接真实硬件时，建议开启：

UseEditorSerialDebugParameters = true

开启后，Editor 中串口使用：

• EditorPortName
• EditorBaudRate
• EditorReadBufferSize

Player 中仍使用：

• PortName
• BaudRate
• ReadBufferSize

这样可以避免 Editor 调试口和发布运行口互相覆盖。

5. Editor 工具按钮

配置窗口按钮：

按钮	行为
Load Default	固定加载或创建默认路径的 FaceSdkSettings.asset
Save	保存当前配置并同步场景中的 Manager
Save and Create/Update Manager	保存配置后创建或更新场景 Manager

同步 Manager 时会写入：

• m_settings
• m_config.TransportMode
• m_config.UseMockInEditor
• 串口参数
• Editor 串口参数
• Mock 延迟
• 自动验证配置
• Raw Log 开关

PlayMode 中同步配置时，会调用 FaceModuleManager.ApplySettings(settings)，立即重建当前 transport。

6. Manager 配置方式

推荐方式：

manager.ApplySettings(settings);
manager.Open();

兼容方式：

manager.Configure(useMockInEditor: true, portName: "COM3", baudRate: 115200);
manager.Open();

外部通信层注入：

manager.ConfigureTransport(customTransport);
manager.Open();

7. 场景约束

每个场景建议只保留一个 FaceModuleManager。

多个 Manager 可能导致：

• 多次打开同一串口。
• 重复接收和派发事件。
• UI 状态不一致。

Create Manager GameObject 菜单会校验 Manager 数量，并在存在多个 Manager 时停止创建。

8. 自动验证配置

AutoVerifyTimeout 是发送给模组的协议超时时间，不是结果间隔。

AutoVerifyResultIntervalMs 是 Unity SDK 侧的事件节流间隔。自动验证开启后，硬件可能持续通过 NOTE 上报识别结果，SDK 会按该间隔派发 OnAutoVerifyResult，避免 UI 或业务层被连续结果刷爆。

关闭连接时，FaceModuleManager.Close() 和 CloseAsync() 会先尝试关闭自动验证，再执行 FaceResetAsync()，最后关闭串口。OnApplicationQuit() 也会走同一套安全关闭流程，避免应用退出后硬件继续检测。

9. 独占命令策略

自动验证开启后，模组会持续进行检测。录入、删除、查询、照片注册等业务命令可能与自动验证互相冲突。FaceExclusiveCommandPolicy 用于控制 SDK 在执行这些命令前如何处理自动验证状态。

值	行为	适用场景
RejectWhenAutoVerifyEnabled	自动验证开启时直接拒绝独占命令	希望业务层显式控制状态切换
StopAutoVerify	SDK 在独占命令前自动关闭自动验证	默认推荐，减少业务层重复处理
Ignore	SDK 不处理自动验证状态	调试或自定义流程，业务层自行保证不冲突

10. 运行时状态码入口

配置项会影响以下运行时状态和返回值，详细枚举表见 SDK_API_Reference.md。

类型	使用位置	说明
FaceResultCode	ResultCode、OnError、FaceCommandException	命令和业务结果码
FaceStateCode	OnFaceStateUpdated	人脸位置、遮挡、闭眼等状态
FaceModuleStatus	CurrentStatus、GetStatusAsync()	模组待机、忙碌、错误状态
FaceTransportMode	FaceSdkSettings.TransportMode	通信模式
FaceExclusiveCommandPolicy	FaceSdkSettings.ExclusiveCommandPolicy	自动验证与独占命令冲突策略