163 lines
5.8 KiB
Markdown
163 lines
5.8 KiB
Markdown
# SI-M1 Face SDK 配置与 Editor 工具
|
||
|
||
SDK 使用 `FaceSdkSettings` 作为推荐配置方式。该配置是 `ScriptableObject`，可在项目中复用，并可同步到场景中的 `FaceModuleManager`。
|
||
|
||
## 1. 默认配置资产
|
||
|
||
默认路径：
|
||
|
||
```text
|
||
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 下有一个额外优先级：
|
||
|
||
```text
|
||
UseMockInEditor = true 时，强制使用 Mock，不打开真实串口。
|
||
```
|
||
|
||
因此 Editor 中如果需要连接真实串口，必须将 `UseMockInEditor` 设为 `false`。
|
||
|
||
## 4. Editor Serial Debug 参数
|
||
|
||
Editor 连接真实硬件时，建议开启：
|
||
|
||
```text
|
||
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 配置方式
|
||
|
||
推荐方式：
|
||
|
||
```csharp
|
||
manager.ApplySettings(settings);
|
||
manager.Open();
|
||
```
|
||
|
||
兼容方式：
|
||
|
||
```csharp
|
||
manager.Configure(useMockInEditor: true, portName: "COM3", baudRate: 115200);
|
||
manager.Open();
|
||
```
|
||
|
||
外部通信层注入：
|
||
|
||
```csharp
|
||
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` | 自动验证与独占命令冲突策略 |
|