aisu-sdk/si-m1-face-package
1
0
Fork 0
Code Releases Wiki Activity

chore: refresh face package docs and samples

Browse Source
This commit is contained in:
su 2026-08-20 11:31:27 +08:00
parent e82250b5e7
commit 29e8ebdcf1
69 changed files with 406 additions and 497 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Documentation~/README_UI.md
View File

@ -2,12 +2,41 @@
中文说明见 [README_UI.zh-CN.md](README_UI.zh-CN.md).
The public DLL-only UPM package does not include Demo UI source files or importable sample scenes.
Use the SDK from your own Unity scene by creating a `FaceModuleManager` through:
## Scenes
```text
AISU/SI-M1 Face SDK/Create Manager GameObject
Packages/xin.aisu.si-m1.face/Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```
For Demo UI source, sample scenes, or internal validation tests, use the private development SDK repository.
## SI-M1 Face Demo
This scene covers the main SDK commands:
- Connection and basic status
- Protocol debug
- Face verification
- Face enrollment
- User management
- QR code
- Image capture
- Photo and feature enrollment
- Feature management
- UVC settings
- Advanced settings
## Face Detection Demo
This scene provides a compact workflow for:
- Camera enumeration and preview
- Serial port selection
- Module connection and disconnection
- Face enrollment
- Face verification
- User list refresh and deletion
- Operation log display
## Mock Mode
Enable `Use Mock In Editor` in `FaceSdkSettings` to test UI flow without real SI-M1 hardware.

39
Documentation~/README_UI.zh-CN.md
View File

@ -2,12 +2,41 @@
English documentation: [README_UI.md](README_UI.md).
公开 DLL-only UPM 包不包含 Demo UI 源码，也不包含可导入的示例场景。
请在自己的 Unity 场景中通过以下菜单创建 `FaceModuleManager`：
## 场景
```text
AISU/SI-M1 Face SDK/Create Manager GameObject
Packages/xin.aisu.si-m1.face/Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```
如需 Demo UI 源码、示例场景或内部验证测试，请使用私有开发 SDK 仓库。
## SI-M1 Face Demo
该场景覆盖主要 SDK 命令：
- 连接和基础状态
- 协议调试
- 人脸验证
- 人脸录入
- 用户管理
- 二维码
- 图片抓拍
- 照片和特征录入
- 特征管理
- UVC 设置
- 高级设置
## Face Detection Demo
该场景提供最小测试流程：
- 摄像头枚举和预览
- 串口选择
- 模组连接和断开
- 人脸录入
- 人脸验证
- 用户列表刷新和删除
- 操作日志显示
## Mock 模式
在 `FaceSdkSettings` 中启用 `Use Mock In Editor`，可以在没有真实 SI-M1 硬件时测试 UI 流程。

20
Documentation~/SDK_API_Reference.md
View File

@ -2,7 +2,7 @@
中文说明见 [SDK_API_Reference.zh-CN.md](SDK_API_Reference.zh-CN.md).
This document lists the public business-level API exposed by `xin.aisu.si-m1.face`. The package is DLL-only; source files are not included in the public release.
This document lists the business-level API exposed by `xin.aisu.si-m1.face`.
## Namespaces
@ -52,7 +52,11 @@ using Aisu.SIM1.Face.Core;
| `Configure(bool useMockInEditor, string portName, int baudRate)` | Quick configuration for legacy code |
| `ApplySettings(FaceSdkSettings sdkSettings)` | Apply ScriptableObject settings and rebuild transport |
| `Open()` | Open transport |
| `Close()` | Close transport |
| `Close()` | Stop active face operations and close transport |
| `CloseAsync()` | Stop active face operations and close transport asynchronously |
| `StopFaceOperationAsync()` | Stop auto verify or reset the current face flow |
| `StartAutoVerifyAsync(byte timeout)` | Start auto verify and return the control command result |
| `StopAutoVerifyAsync(byte timeout = 1)` | Stop auto verify and return the control command result |
| `WaitReadyAsync(int timeoutMs = 5000)` | Wait for READY note |
| `ProbeReadyByStatusAsync()` | Query status and mark manager ready |
| `SendRawBytes(byte[] bytes)` | Send raw protocol bytes |
@ -67,6 +71,7 @@ using Aisu.SIM1.Face.Core;
| `OnReplyReceived(FaceReply)` | REPLY packet received |
| `OnNoteReceived(FaceNote)` | NOTE packet received |
| `OnFaceStateUpdated(FaceFaceStateNote)` | Face state NOTE received |
| `OnAutoVerifyResult(FaceAutoVerifyResult)` | Auto verify result NOTE received |
| `OnQrCodeReceived(string)` | QR code NOTE received |
| `OnFeatureReceived(byte[])` | Feature data packet received |
| `OnDataPacketReceived(FacePacket)` | Image/template data packet received |
@ -96,7 +101,9 @@ Access path: `manager.Verify`
| Method | Return | Description |
|---|---|---|
| `VerifyAsync(byte timeout, byte maxRecognitionTimes = 30)` | `Task<FaceVerifyResult>` | Run one face verification |
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceVerifyResult>` | Enable or disable automatic verification |
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceReply>` | Low-level auto verify control command |
For application code, prefer `FaceModuleManager.StartAutoVerifyAsync()` and `FaceModuleManager.StopAutoVerifyAsync()`. Recognition results are delivered through `OnAutoVerifyResult`.
### FaceEnrollmentService
@ -205,6 +212,7 @@ Callbacks use a consistent pattern:
| `Configure(bool useMockInEditor, string portName, int baudRate, Action success, Action<string> error)` | `Action` | Configure default transport parameters |
| `Open(Action success, Action<string> error)` | `Action` | Open transport |
| `Close(Action success, Action<string> error)` | `Action` | Close transport |
| `StopFaceOperation(Action success, Action<string> error)` | `Action` | Stop auto verify or reset current face flow |
| `SendRawBytes(byte[] bytes, Action success, Action<string> error)` | `Action` | Send raw bytes |
| `WaitReady(int timeoutMs, Action success, Action<string> error)` | `Action` | Wait for READY |
| `ProbeReadyByStatus(Action<FaceModuleStatus> success, Action<string> error)` | `Action<FaceModuleStatus>` | Probe status and mark ready |
@ -226,7 +234,9 @@ Callbacks use a consistent pattern:
| Method | Success Callback | Description |
|---|---|---|
| `Verify(byte timeout, Action<FaceVerifyResult> success, Action<string> error, byte maxRecognitionTimes = 30)` | `Action<FaceVerifyResult>` | Run face verification |
| `AutoVerify(bool enable, byte timeout, Action<FaceVerifyResult> success, Action<string> error)` | `Action<FaceVerifyResult>` | Enable or disable auto verification |
| `AutoVerify(bool enable, byte timeout, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | Low-level auto verify control command |
| `StartAutoVerify(byte timeout, Action<FaceAutoVerifyControlResult> success, Action<string> error)` | `Action<FaceAutoVerifyControlResult>` | Start auto verify |
| `StopAutoVerify(byte timeout, Action<FaceAutoVerifyControlResult> success, Action<string> error)` | `Action<FaceAutoVerifyControlResult>` | Stop auto verify |
| `Enroll(bool admin, string userName, FaceDirection direction, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | Interactive enrollment |
| `EnrollSingle(bool admin, string userName, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | Single-frame enrollment |
| `EnrollIntegrated(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | Integrated enrollment |
@ -280,6 +290,8 @@ Callbacks use a consistent pattern:
| `FaceReply` | REPLY packet parse result |
| `FaceNote` | NOTE packet parse result |
| `FaceFaceStateNote` | Face state NOTE |
| `FaceAutoVerifyResult` | Auto verify recognition result |
| `FaceAutoVerifyControlResult` | Auto verify start/stop command result |
| `FaceUserInfo` | User ID, name, and admin flag |
| `FaceVerifyResult` | Verification result, user info, unlock status |
| `FaceEnrollResult` | Enrollment result, user ID, direction |

20
Documentation~/SDK_API_Reference.zh-CN.md
View File

@ -2,7 +2,7 @@
English documentation: [SDK_API_Reference.md](SDK_API_Reference.md).
本文列出 `xin.aisu.si-m1.face` 对外公开的业务层 API。公开包为 DLL-only 形式，不包含 SDK 源码。
本文列出 `xin.aisu.si-m1.face` 的业务层 API。
## 命名空间
@ -52,7 +52,11 @@ using Aisu.SIM1.Face.Core;
| `Configure(bool useMockInEditor, string portName, int baudRate)` | 兼容旧代码的快速配置入口 |
| `ApplySettings(FaceSdkSettings sdkSettings)` | 应用 ScriptableObject 配置并重建 transport |
| `Open()` | 打开通信 |
| `Close()` | 关闭通信 |
| `Close()` | 停止当前人脸流程并关闭通信 |
| `CloseAsync()` | 异步停止当前人脸流程并关闭通信 |
| `StopFaceOperationAsync()` | 停止自动验证或重置当前人脸流程 |
| `StartAutoVerifyAsync(byte timeout)` | 开启自动验证并返回控制命令结果 |
| `StopAutoVerifyAsync(byte timeout = 1)` | 关闭自动验证并返回控制命令结果 |
| `WaitReadyAsync(int timeoutMs = 5000)` | 等待 READY NOTE |
| `ProbeReadyByStatusAsync()` | 主动查询状态并标记 READY |
| `SendRawBytes(byte[] bytes)` | 发送原始协议 bytes |
@ -67,6 +71,7 @@ using Aisu.SIM1.Face.Core;
| `OnReplyReceived(FaceReply)` | 收到 REPLY 包 |
| `OnNoteReceived(FaceNote)` | 收到 NOTE 包 |
| `OnFaceStateUpdated(FaceFaceStateNote)` | 收到人脸状态 NOTE |
| `OnAutoVerifyResult(FaceAutoVerifyResult)` | 收到自动验证结果 NOTE |
| `OnQrCodeReceived(string)` | 收到二维码 NOTE |
| `OnFeatureReceived(byte[])` | 收到特征数据包 |
| `OnDataPacketReceived(FacePacket)` | 收到图片或模板数据包 |
@ -96,7 +101,9 @@ using Aisu.SIM1.Face.Core;
| 方法 | 返回 | 说明 |
|---|---|---|
| `VerifyAsync(byte timeout, byte maxRecognitionTimes = 30)` | `Task<FaceVerifyResult>` | 单次人脸验证 |
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceVerifyResult>` | 启用或关闭自动验证 |
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceReply>` | 底层自动验证控制命令 |
业务代码推荐使用 `FaceModuleManager.StartAutoVerifyAsync()` 和 `FaceModuleManager.StopAutoVerifyAsync()`。识别结果通过 `OnAutoVerifyResult` 获取。
### FaceEnrollmentService
@ -205,6 +212,7 @@ public interface IFaceModuleCrypto
| `Configure(bool useMockInEditor, string portName, int baudRate, Action success, Action<string> error)` | `Action` | 配置默认通信参数 |
| `Open(Action success, Action<string> error)` | `Action` | 打开通信 |
| `Close(Action success, Action<string> error)` | `Action` | 关闭通信 |
| `StopFaceOperation(Action success, Action<string> error)` | `Action` | 停止自动验证或重置当前人脸流程 |
| `SendRawBytes(byte[] bytes, Action success, Action<string> error)` | `Action` | 发送原始 bytes |
| `WaitReady(int timeoutMs, Action success, Action<string> error)` | `Action` | 等待 READY |
| `ProbeReadyByStatus(Action<FaceModuleStatus> success, Action<string> error)` | `Action<FaceModuleStatus>` | 主动探测状态并标记 READY |
@ -226,7 +234,9 @@ public interface IFaceModuleCrypto
| 方法 | 成功回调 | 说明 |
|---|---|---|
| `Verify(byte timeout, Action<FaceVerifyResult> success, Action<string> error, byte maxRecognitionTimes = 30)` | `Action<FaceVerifyResult>` | 人脸验证 |
| `AutoVerify(bool enable, byte timeout, Action<FaceVerifyResult> success, Action<string> error)` | `Action<FaceVerifyResult>` | 启用或关闭自动验证 |
| `AutoVerify(bool enable, byte timeout, Action<FaceReply> success, Action<string> error)` | `Action<FaceReply>` | 底层自动验证控制命令 |
| `StartAutoVerify(byte timeout, Action<FaceAutoVerifyControlResult> success, Action<string> error)` | `Action<FaceAutoVerifyControlResult>` | 开启自动验证 |
| `StopAutoVerify(byte timeout, Action<FaceAutoVerifyControlResult> success, Action<string> error)` | `Action<FaceAutoVerifyControlResult>` | 关闭自动验证 |
| `Enroll(bool admin, string userName, FaceDirection direction, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 交互式录入 |
| `EnrollSingle(bool admin, string userName, byte timeout, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 单帧录入 |
| `EnrollIntegrated(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error)` | `Action<FaceEnrollResult>` | 集成式录入 |
@ -280,6 +290,8 @@ public interface IFaceModuleCrypto
| `FaceReply` | REPLY 包解析结果 |
| `FaceNote` | NOTE 包解析结果 |
| `FaceFaceStateNote` | 人脸状态 NOTE |
| `FaceAutoVerifyResult` | 自动验证识别结果 |
| `FaceAutoVerifyControlResult` | 自动验证开启/关闭命令结果 |
| `FaceUserInfo` | 用户 ID、姓名、管理员标记 |
| `FaceVerifyResult` | 验证结果、用户信息、开锁状态 |
| `FaceEnrollResult` | 录入结果、用户 ID、方向 |

41
Documentation~/SDK_Configuration.md
View File

@ -2,17 +2,15 @@
中文说明见 [SDK_Configuration.zh-CN.md](SDK_Configuration.zh-CN.md).
The SDK uses `FaceSdkSettings` as the recommended configuration asset. It is a `ScriptableObject` created inside the importing Unity project and can be synchronized to scene `FaceModuleManager` instances.
The SDK uses `FaceSdkSettings` as the recommended configuration asset. `FaceModuleManager` can read this asset and synchronize the values into its runtime config.
## Default Settings Asset
Default path in the importing Unity project:
```text
Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
```
Open `AISU/SI-M1 Face SDK/Settings` to load or create this asset.
Open `AISU/SI-M1 Face SDK/Settings` to load, edit, and save the asset.
## FaceSdkSettings Fields
@ -20,14 +18,19 @@ Open `AISU/SI-M1 Face SDK/Settings` to load or create this asset.
|---|---|---|
| `TransportMode` | `FaceTransportMode` | `Auto`, `SerialPort`, or `Mock` |
| `UseMockInEditor` | `bool` | Force mock transport in Unity Editor |
| `PortName` | `string` | Runtime/player serial port |
| `BaudRate` | `int` | Runtime/player baud rate |
| `ReadBufferSize` | `int` | Runtime/player read buffer size |
| `PortName` | `string` | Runtime serial port |
| `BaudRate` | `int` | Runtime baud rate |
| `ReadBufferSize` | `int` | Runtime read buffer size |
| `UseEditorSerialDebugParameters` | `bool` | Use separate serial parameters in Editor |
| `EditorPortName` | `string` | Editor debug serial port |
| `EditorBaudRate` | `int` | Editor debug baud rate |
| `EditorReadBufferSize` | `int` | Editor debug read buffer size |
| `MockResponseDelayFrames` | `int` | Mock response delay in frames |
| `AutoVerifyOnOpen` | `bool` | Start auto verify after READY |
| `AutoVerifyTimeout` | `byte` | Auto verify protocol timeout in seconds |
| `AutoVerifyResultIntervalMs` | `int` | Minimum interval between auto verify result events |
| `StopAutoVerifyBeforeExclusiveCommand` | `bool` | Stop auto verify before exclusive commands |
| `ExclusiveCommandPolicy` | `FaceExclusiveCommandPolicy` | Policy when exclusive commands run during auto verify |
| `DebugLogEnabled` | `bool` | Enable SDK debug logs |
| `RawLogEnabled` | `bool` | Dispatch raw TX/RX logs |
| `LogPrefix` | `string` | Log prefix |
@ -40,37 +43,33 @@ Open `AISU/SI-M1 Face SDK/Settings` to load or create this asset.
| `SerialPort` | Use `SerialPortTransport` |
| `Mock` | Use `MockFaceModuleTransport` |
When `UseMockInEditor = true`, the Editor always uses mock transport and does not open a real serial port.
When `UseMockInEditor = true`, the Editor uses mock transport and does not open a real serial port.
## Editor Tools
## Auto Verify
| Menu | Purpose |
|---|---|
| `AISU/SI-M1 Face SDK/Settings` | Open SDK settings window |
| `AISU/SI-M1 Face SDK/Create Manager GameObject` | Create or update one scene `FaceModuleManager` |
| `AISU/SI-M1 Face SDK/Open Diagnostics` | Open diagnostics window |
`AutoVerifyTimeout` is sent to the SI-M1 module as the recognition timeout.
The public DLL-only package does not include importable demo samples. Any demo-related menu item should be treated as unavailable in the public release if it appears in the current Editor DLL.
`AutoVerifyResultIntervalMs` is handled by the Unity SDK. It limits how frequently `OnAutoVerifyResult` is dispatched when the module sends continuous auto verify NOTE packets. Set it to `0` to dispatch every result.
## Recommended Usage
`StopAutoVerifyBeforeExclusiveCommand` and `ExclusiveCommandPolicy` control how enrollment, user management, QR code, image capture, and feature operations behave while auto verify is active.
## Runtime Usage
```csharp
manager.ApplySettings(settings);
manager.Open();
```
Legacy quick configuration:
Quick configuration:
```csharp
manager.Configure(useMockInEditor: true, portName: "COM3", baudRate: 115200);
manager.Open();
```
Custom transport injection:
Custom transport:
```csharp
manager.ConfigureTransport(customTransport);
manager.Open();
```
Keep only one `FaceModuleManager` in each scene to avoid duplicate serial connections and duplicated events.

49
Documentation~/SDK_Configuration.zh-CN.md
View File

@ -1,33 +1,36 @@
# SDK 配置
# SDK 配置说明
English documentation: [SDK_Configuration.md](SDK_Configuration.md).
SDK 推荐使用 `FaceSdkSettings` 作为配置资产。该配置是 `ScriptableObject`，会创建在导入该包的 Unity 项目中，并可同步到场景里的 `FaceModuleManager`。
SDK 推荐使用 `FaceSdkSettings` 作为配置资产。`FaceModuleManager` 可以读取该资产，并同步到运行时配置。
## 默认配置资产
默认路径位于导入该包的 Unity 项目内：
```text
Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
```
打开 `AISU/SI-M1 Face SDK/Settings` 可加载或创建该配置资产。
打开 `AISU/SI-M1 Face SDK/Settings` 可以加载、编辑和保存配置。
## FaceSdkSettings 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| `TransportMode` | `FaceTransportMode` | `Auto`、`SerialPort` 或 `Mock` |
| `UseMockInEditor` | `bool` | Unity Editor 中强制使用 Mock 通信 |
| `PortName` | `string` | Runtime/Player 串口号 |
| `BaudRate` | `int` | Runtime/Player 波特率 |
| `ReadBufferSize` | `int` | Runtime/Player 读取缓冲区大小 |
| `UseEditorSerialDebugParameters` | `bool` | Editor 中是否使用单独串口参数 |
| `UseMockInEditor` | `bool` | Editor 下强制使用 Mock 通信 |
| `PortName` | `string` | 运行时串口号 |
| `BaudRate` | `int` | 运行时波特率 |
| `ReadBufferSize` | `int` | 运行时读取缓冲区 |
| `UseEditorSerialDebugParameters` | `bool` | Editor 下是否使用单独串口参数 |
| `EditorPortName` | `string` | Editor 调试串口号 |
| `EditorBaudRate` | `int` | Editor 调试波特率 |
| `EditorReadBufferSize` | `int` | Editor 调试读取缓冲区大小 |
| `EditorReadBufferSize` | `int` | Editor 调试读取缓冲区 |
| `MockResponseDelayFrames` | `int` | Mock 响应延迟帧数 |
| `AutoVerifyOnOpen` | `bool` | READY 后是否自动开启验证 |
| `AutoVerifyTimeout` | `byte` | 自动验证协议超时时间，单位秒 |
| `AutoVerifyResultIntervalMs` | `int` | 自动验证结果事件最小间隔 |
| `StopAutoVerifyBeforeExclusiveCommand` | `bool` | 独占命令前是否停止自动验证 |
| `ExclusiveCommandPolicy` | `FaceExclusiveCommandPolicy` | 自动验证期间执行独占命令的处理策略 |
| `DebugLogEnabled` | `bool` | 是否启用 SDK Debug 日志 |
| `RawLogEnabled` | `bool` | 是否派发原始 TX/RX 日志 |
| `LogPrefix` | `string` | 日志前缀 |
@ -40,37 +43,33 @@ Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
| `SerialPort` | 使用 `SerialPortTransport` |
| `Mock` | 使用 `MockFaceModuleTransport` |
当 `UseMockInEditor = true` 时，Editor 会始终使用 Mock 通信，不会打开真实串口。
当 `UseMockInEditor = true` 时，Editor 使用 Mock 通信，不会打开真实串口。
## Editor 工具
## 自动验证
| 菜单 | 用途 |
|---|---|
| `AISU/SI-M1 Face SDK/Settings` | 打开 SDK 配置窗口 |
| `AISU/SI-M1 Face SDK/Create Manager GameObject` | 创建或更新场景中的唯一 `FaceModuleManager` |
| `AISU/SI-M1 Face SDK/Open Diagnostics` | 打开诊断窗口 |
`AutoVerifyTimeout` 会发送给 SI-M1 模组，表示识别超时时间。
公开 DLL-only 包不包含可导入 Demo 示例。如果当前 Editor DLL 中仍出现 Demo 相关菜单，应视为公开版本不可用功能。
`AutoVerifyResultIntervalMs` 由 Unity SDK 处理，用于限制 `OnAutoVerifyResult` 的派发频率。设置为 `0` 时不做节流。
## 推荐用法
`StopAutoVerifyBeforeExclusiveCommand` 和 `ExclusiveCommandPolicy` 用于控制自动验证开启时，录入、用户管理、二维码、抓拍、特征等独占操作的行为。
## 运行时使用
```csharp
manager.ApplySettings(settings);
manager.Open();
```
兼容式快速配置：
快速配置：
```csharp
manager.Configure(useMockInEditor: true, portName: "COM3", baudRate: 115200);
manager.Open();
```
自定义通信层注入：
自定义通信层：
```csharp
manager.ConfigureTransport(customTransport);
manager.Open();
```
每个场景建议只保留一个 `FaceModuleManager`，避免重复打开串口和重复派发事件。

73
Documentation~/SDK_License_Request.md
View File

@ -1,73 +0,0 @@
# SI-M1 Face SDK License Request
This public DLL-only package requires a project-specific license file for real serial-port runtime usage. Mock mode does not require a license.
## License File Path
Place the license file at:
```text
Assets/StreamingAssets/si-m1_face.dat
```
The SDK reads this file through `Application.streamingAssetsPath`.
## Required Unity Binding Parameters
Provide these values from the Unity project that will run the SDK:
| Field | Unity Source |
|---|---|
| `identifier` | `Application.identifier` |
| `companyName` | `Application.companyName` |
| `productName` | `Application.productName` |
| `version` | `Application.version` |
| `unityVersion` | `Application.unityVersion` |
If any of these values changes, the existing license becomes invalid and a new license is required.
## Parameter Probe
Add this temporary script to the customer project and copy the Console output when requesting a license:
```csharp
using UnityEngine;
public sealed class FaceLicenseParameterPrinter : MonoBehaviour
{
private void Awake()
{
Debug.Log("identifier=" + Application.identifier);
Debug.Log("companyName=" + Application.companyName);
Debug.Log("productName=" + Application.productName);
Debug.Log("version=" + Application.version);
Debug.Log("unityVersion=" + Application.unityVersion);
}
}
```
## Request Information
Provide:
| Item | Example |
|---|---|
| Customer name | `customer-a` |
| Project name | `Face App` |
| Unity binding parameters | See above |
| License start time | `2026-08-10T00:00:00+08:00` |
| License expiry time | `2027-08-10T00:00:00+08:00` |
| Licensed features | `SerialRuntime,Basic,Verify,Enroll` |
License times use Beijing time and must use `yyyy-MM-ddTHH:mm:ss+08:00`.
## Common Failures
| Symptom | Cause |
|---|---|
| License file missing | `si-m1_face.dat` is not under `Assets/StreamingAssets` |
| Binding mismatch | One of the Unity binding parameters changed |
| Expired | Current Beijing time is after `expireAt` |
| Not yet valid | Current Beijing time is before `issuedAt` |
| Feature denied | The license does not include the requested SDK feature |
| Invalid signature | The file was modified or does not match this SDK build |

7
Documentation~/SDK_License_Request.md.meta
View File

@ -1,7 +0,0 @@
fileFormatVersion: 2
guid: 7f0d681e6f6b4d6a86f6a989cdf55091
TextScriptImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:

73
Documentation~/SDK_License_Request.zh-CN.md
View File

@ -1,73 +0,0 @@
# SI-M1 Face SDK 授权申请
DLL-only 公开包在真实串口运行时需要项目专用授权文件。Mock 模式不需要授权。
## 授权文件路径
授权文件必须放在客户 Unity 项目中：
```text
Assets/StreamingAssets/si-m1_face.dat
```
SDK 会通过 `Application.streamingAssetsPath` 读取该文件。
## 需要提供的 Unity 绑定参数
申请授权时需要提供运行 SDK 的 Unity 项目参数：
| 字段 | Unity 读取来源 |
|---|---|
| `identifier` | `Application.identifier` |
| `companyName` | `Application.companyName` |
| `productName` | `Application.productName` |
| `version` | `Application.version` |
| `unityVersion` | `Application.unityVersion` |
这些值任意变化后，已有授权会失效，需要重新申请授权。
## 参数打印脚本
客户可以在项目中临时添加以下脚本，并把 Console 输出发给授权人员：
```csharp
using UnityEngine;
public sealed class FaceLicenseParameterPrinter : MonoBehaviour
{
private void Awake()
{
Debug.Log("identifier=" + Application.identifier);
Debug.Log("companyName=" + Application.companyName);
Debug.Log("productName=" + Application.productName);
Debug.Log("version=" + Application.version);
Debug.Log("unityVersion=" + Application.unityVersion);
}
}
```
## 授权申请信息
建议提供：
| 项 | 示例 |
|---|---|
| 客户名称 | `customer-a` |
| 项目名称 | `Face App` |
| Unity 绑定参数 | 见上文 |
| 授权开始时间 | `2026-08-10T00:00:00+08:00` |
| 授权过期时间 | `2027-08-10T00:00:00+08:00` |
| 授权功能 | `SerialRuntime,Basic,Verify,Enroll` |
授权时间使用北京时间，格式必须为 `yyyy-MM-ddTHH:mm:ss+08:00`。
## 常见失败原因
| 现象 | 原因 |
|---|---|
| 授权文件不存在 | `si-m1_face.dat` 没有放在 `Assets/StreamingAssets` 下 |
| 授权绑定不匹配 | Unity 绑定参数发生变化 |
| 授权已过期 | 当前北京时间晚于 `expireAt` |
| 授权尚未生效 | 当前北京时间早于 `issuedAt` |
| 功能未授权 | 授权中不包含当前调用的 SDK 功能 |
| 签名无效 | 授权文件被修改，或与当前 SDK 构建不匹配 |

7
Documentation~/SDK_License_Request.zh-CN.md.meta
View File

@ -1,7 +0,0 @@
fileFormatVersion: 2
guid: 9204393b20cb4dd9a9edb6f230fe6d3b
TextScriptImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:

22
Documentation~/SDK_Mock_And_Testing.md
View File

@ -2,8 +2,6 @@
中文说明见 [SDK_Mock_And_Testing.zh-CN.md](SDK_Mock_And_Testing.zh-CN.md).
The public DLL-only package includes runtime mock support inside `Aisu.SIM1.Face.Runtime.dll`, but it does not include EditMode test source files.
## Editor Mock
For Editor integration without real hardware, enable mock mode in `FaceSdkSettings`:
@ -12,7 +10,14 @@ For Editor integration without real hardware, enable mock mode in `FaceSdkSettin
Use Mock In Editor = true
```
When this option is enabled, the SDK uses the built-in mock transport in the Unity Editor instead of opening a real serial port.
When this option is enabled, the SDK uses `MockFaceModuleTransport` in the Unity Editor instead of opening a real serial port.
Mock mode is useful for:
- UI flow testing
- Command callback testing
- User-list display testing
- Basic enrollment and verification workflow testing
## Hardware Validation
@ -20,9 +25,12 @@ For real SI-M1 hardware validation:
1. Set `Use Mock In Editor = false`.
2. Configure `Editor Port Name`, `Editor Baud Rate`, and `Editor Read Buffer Size`.
3. Create a `FaceModuleManager` in the scene.
4. Call `Open()`, then wait for `WaitReadyAsync()` or handle `OnReady`.
3. Open the scene that contains one `FaceModuleManager`.
4. Call `Open()`.
5. Wait for `WaitReadyAsync()` or handle `OnReady`.
## Automated Tests
## Logs
Internal EditMode tests are maintained in the private development SDK repository and are not distributed in this DLL-only public package.
Enable `RawLogEnabled` to receive raw TX/RX logs through `OnRawLog`.
Enable `DebugLogEnabled` to print SDK-level debug logs.

22
Documentation~/SDK_Mock_And_Testing.zh-CN.md
View File

@ -2,8 +2,6 @@
English documentation: [SDK_Mock_And_Testing.md](SDK_Mock_And_Testing.md).
公开 DLL-only 包在 `Aisu.SIM1.Face.Runtime.dll` 中包含运行时 Mock 支持，但不包含 EditMode 测试源码。
## Editor Mock
无真实硬件进行 Editor 联调时，在 `FaceSdkSettings` 中启用：
@ -12,7 +10,14 @@ English documentation: [SDK_Mock_And_Testing.md](SDK_Mock_And_Testing.md).
Use Mock In Editor = true
```
启用后，SDK 在 Unity Editor 中使用内置 Mock 通信层，不会打开真实串口。
启用后，SDK 在 Unity Editor 中使用 `MockFaceModuleTransport`，不会打开真实串口。
Mock 模式适用于：
- UI 流程测试
- 命令回调测试
- 用户列表显示测试
- 基础录入和验证流程测试
## 真实硬件验证
@ -20,9 +25,12 @@ Use Mock In Editor = true
1. 设置 `Use Mock In Editor = false`。
2. 配置 `Editor Port Name`、`Editor Baud Rate` 和 `Editor Read Buffer Size`。
3. 在场景中创建 `FaceModuleManager`。
4. 调用 `Open()`，然后等待 `WaitReadyAsync()` 或处理 `OnReady`。
3. 打开包含一个 `FaceModuleManager` 的场景。
4. 调用 `Open()`。
5. 等待 `WaitReadyAsync()` 或处理 `OnReady`。
## 自动化测试
## 日志
内部 EditMode 测试保留在私有开发 SDK 仓库中，不随 DLL-only 公开包发布。
启用 `RawLogEnabled` 后，可以通过 `OnRawLog` 接收原始 TX/RX 日志。
启用 `DebugLogEnabled` 后，可以输出 SDK 层 Debug 日志。

112
Documentation~/SDK_QuickStart.md
View File

@ -2,23 +2,7 @@
中文说明见 [SDK_QuickStart.zh-CN.md](SDK_QuickStart.zh-CN.md).
This public UPM package is distributed as compiled DLLs and does not include SDK source code, demo source code, test source code, or debug symbols.
## 1. Install
Add the package through Unity Package Manager:
```text
https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.2
```
Or add it to `Packages/manifest.json`:
```json
"xin.aisu.si-m1.face": "https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.2"
```
## 2. Create Settings
## 1. Settings
Open Unity menu:
@ -26,25 +10,26 @@ Open Unity menu:
AISU/SI-M1 Face SDK/Settings
```
The tool creates or loads this settings asset inside the importing Unity project:
The default settings asset path is:
```text
Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
```
Configure serial port, baud rate, mock mode, and logging options.
Configure:
## 3. Create Manager
- Transport mode
- Runtime serial port and baud rate
- Editor serial debug parameters
- Mock mode
- Auto verify options
- Debug and raw protocol logs
Open Unity menu:
## 2. Scene Manager
```text
AISU/SI-M1 Face SDK/Create Manager GameObject
```
Add one `FaceModuleManager` to the scene and bind the settings asset. Keep only one manager in a scene to avoid duplicate serial connections and duplicated callbacks.
Keep one `FaceModuleManager` in the scene to avoid duplicate serial connections and duplicate event dispatch.
## 4. Minimal Code
## 3. Minimal Code
```csharp
using Aisu.SIM1.Face.Core;
@ -57,24 +42,71 @@ public sealed class FaceExample : MonoBehaviour
private async void Start()
{
manager.Open();
await manager.WaitReadyAsync();
await manager.WaitReadyAsync(5000);
var status = await manager.Basic.GetStatusAsync();
var version = await manager.Basic.GetVersionAsync();
Debug.Log("SI-M1 version: " + version);
Debug.Log("Status: " + status);
Debug.Log("Version: " + version);
}
private void OnApplicationQuit()
{
manager?.Close();
}
}
```
## 5. Runtime Modes
## 4. Common Operations
| Scenario | Recommended Setting |
|---|---|
| Editor integration without hardware | `Use Mock In Editor = true` |
| Editor with real serial hardware | `Use Mock In Editor = false`, configure editor serial parameters |
| Windows Player | `Transport Mode = SerialPort` or `Auto`, configure runtime serial parameters |
Face verification:
## Notes
```csharp
var result = await manager.Verify.VerifyAsync(timeout: 10);
if (result.Success)
{
Debug.Log("UserId: " + result.UserId);
Debug.Log("UserName: " + result.UserName);
}
```
- Git URL packages may appear as `xin.aisu.si-m1.face@<commit-hash>` in Unity's package cache. This is normal.
- This DLL-only release does not include importable demo samples.
- Demo source and EditMode test source remain in the private development SDK repository.
Face enrollment:
```csharp
var enroll = await manager.Enrollment.EnrollSingleAsync(
admin: false,
userName: "Tester",
timeout: 20);
```
User list:
```csharp
var ids = await manager.Users.GetAllUserIdsAsync();
```
Auto verify:
```csharp
manager.OnAutoVerifyResult += result =>
{
Debug.Log("AutoVerify: " + result.ResultCode);
};
var control = await manager.StartAutoVerifyAsync(timeout: 10);
if (!control.Success)
{
Debug.LogError("AutoVerify start failed: " + control.ResultCode);
}
await manager.StopFaceOperationAsync();
```
## 5. Samples
Sample scenes:
```text
Packages/xin.aisu.si-m1.face/Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```

112
Documentation~/SDK_QuickStart.zh-CN.md
View File

@ -2,23 +2,7 @@
English documentation: [SDK_QuickStart.md](SDK_QuickStart.md).
公开 UPM 包以编译后的 DLL 形式发布，不包含 SDK 源码、Demo 源码、测试源码或调试符号。
## 1. 安装
通过 Unity Package Manager 添加 Git URL：
```text
https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.2
```
或写入 `Packages/manifest.json`：
```json
"xin.aisu.si-m1.face": "https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.2"
```
## 2. 创建配置
## 1. 配置
打开 Unity 菜单：
@ -26,25 +10,26 @@ https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.2
AISU/SI-M1 Face SDK/Settings
```
工具会在导入该包的 Unity 项目中创建或加载配置资产：
默认配置资产路径：
```text
Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
```
配置串口号、波特率、Mock 模式和日志选项。
常用配置：
## 3. 创建 Manager
- 通信模式
- 运行时串口号和波特率
- Editor 串口调试参数
- Mock 模式
- 自动验证选项
- Debug 日志和原始协议日志
打开 Unity 菜单：
## 2. 场景 Manager
```text
AISU/SI-M1 Face SDK/Create Manager GameObject
```
在场景中添加一个 `FaceModuleManager` 并绑定配置资产。每个场景只保留一个 Manager，避免重复打开串口和重复派发回调。
每个场景建议只保留一个 `FaceModuleManager`，避免重复打开串口和重复派发事件。
## 4. 最小代码
## 3. 最小代码
```csharp
using Aisu.SIM1.Face.Core;
@ -57,24 +42,71 @@ public sealed class FaceExample : MonoBehaviour
private async void Start()
{
manager.Open();
await manager.WaitReadyAsync();
await manager.WaitReadyAsync(5000);
var status = await manager.Basic.GetStatusAsync();
var version = await manager.Basic.GetVersionAsync();
Debug.Log("SI-M1 version: " + version);
Debug.Log("Status: " + status);
Debug.Log("Version: " + version);
}
private void OnApplicationQuit()
{
manager?.Close();
}
}
```
## 5. 运行模式
## 4. 常用操作
| 场景 | 推荐配置 |
|---|---|
| Editor 中无硬件联调 | `Use Mock In Editor = true` |
| Editor 中连接真实串口硬件 | `Use Mock In Editor = false`，并配置 Editor 串口参数 |
| Windows Player | `Transport Mode = SerialPort` 或 `Auto`，并配置运行时串口参数 |
人脸验证：
## 注意事项
```csharp
var result = await manager.Verify.VerifyAsync(timeout: 10);
if (result.Success)
{
Debug.Log("UserId: " + result.UserId);
Debug.Log("UserName: " + result.UserName);
}
```
- Unity 对 Git URL 包可能显示为 `xin.aisu.si-m1.face@<commit-hash>`，这是正常行为。
- DLL-only 公开版本不包含可导入 Demo 示例。
- Demo 源码和 EditMode 测试源码保留在私有开发 SDK 仓库中。
人脸录入：
```csharp
var enroll = await manager.Enrollment.EnrollSingleAsync(
admin: false,
userName: "Tester",
timeout: 20);
```
用户列表：
```csharp
var ids = await manager.Users.GetAllUserIdsAsync();
```
自动验证：
```csharp
manager.OnAutoVerifyResult += result =>
{
Debug.Log("AutoVerify: " + result.ResultCode);
};
var control = await manager.StartAutoVerifyAsync(timeout: 10);
if (!control.Success)
{
Debug.LogError("AutoVerify start failed: " + control.ResultCode);
}
await manager.StopFaceOperationAsync();
```
## 5. Samples
示例场景：
```text
Packages/xin.aisu.si-m1.face/Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```

BIN
Editor/Aisu.SIM1.Face.Editor.dll
View File

Binary file not shown.

60
README.md
View File

@ -1,8 +1,8 @@
# AISU SI-M1 Face SDK
`xin.aisu.si-m1.face` is a Unity UPM package for the AISU SI-M1 face recognition module. This public package is distributed as compiled DLLs and does not include SDK source code, demo source code, test source code, or debug symbols.
`xin.aisu.si-m1.face` is a Unity SDK for AISU SI-M1 face recognition modules. It provides serial communication, packet parsing, module lifecycle management, face verification, face enrollment, user management, image capture, QR code, UVC parameters, mock transport, and sample scenes.
中文说明见 [README.zh-CN.md](README.zh-CN.md).
中文说明见 [README.zh-CN.md](README.zh-CN.md)。
## Package Info
@ -10,34 +10,17 @@
|---|---|
| Package Name | `xin.aisu.si-m1.face` |
| Display Name | `AISU SI-M1 Face SDK` |
| Version | `0.1.5` |
| Runtime Assembly | `Aisu.SIM1.Face.Runtime.dll` |
| Editor Assembly | `Aisu.SIM1.Face.Editor.dll` |
| Unity Version | `2021.3` or newer |
| User Settings Asset | `Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset` in the importing Unity project |
## Install
Add the package through Unity Package Manager using this Git URL:
```text
https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.5
```
Or add it to `Packages/manifest.json`:
```json
"xin.aisu.si-m1.face": "https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.5"
```
Unity may display Git packages as `xin.aisu.si-m1.face@<commit-hash>` in `Library/PackageCache`. This is expected for Git URL packages; the package version remains defined by `package.json`.
| Settings Asset | `Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset` |
## Quick Start
1. Open `AISU/SI-M1 Face SDK/Settings` and create or load `FaceSdkSettings`.
2. Set serial port, baud rate, mock mode, and logging options.
3. Open `AISU/SI-M1 Face SDK/Create Manager GameObject` to create a `FaceModuleManager` in the current scene.
4. Reference the manager from your own scripts and call the SDK services.
1. Open `AISU/SI-M1 Face SDK/Settings`.
2. Configure serial port, baud rate, mock mode, auto verify, and logging options.
3. Add one `FaceModuleManager` to the scene and bind the settings asset.
4. Call SDK services through `FaceModuleManager`.
```csharp
using Aisu.SIM1.Face.Core;
@ -55,9 +38,25 @@ public sealed class FaceExample : MonoBehaviour
var version = await manager.Basic.GetVersionAsync();
Debug.Log("SI-M1 version: " + version);
}
private void OnApplicationQuit()
{
manager?.Close();
}
}
```
## Samples
Sample scenes are under:
```text
Packages/xin.aisu.si-m1.face/Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```
Use `SI-M1 Face Demo` for full SDK command testing. Use `Face Detection Demo` for a compact camera, serial, enrollment, verification, and user-list workflow.
## Documentation
| English | Chinese |
@ -65,14 +64,11 @@ public sealed class FaceExample : MonoBehaviour
| [Quick Start](Documentation~/SDK_QuickStart.md) | [快速开始](Documentation~/SDK_QuickStart.zh-CN.md) |
| [Configuration](Documentation~/SDK_Configuration.md) | [配置说明](Documentation~/SDK_Configuration.zh-CN.md) |
| [API Reference](Documentation~/SDK_API_Reference.md) | [API 参考](Documentation~/SDK_API_Reference.zh-CN.md) |
| [License Request](Documentation~/SDK_License_Request.md) | [授权申请](Documentation~/SDK_License_Request.zh-CN.md) |
| [Mock and Testing](Documentation~/SDK_Mock_And_Testing.md) | [Mock 与测试](Documentation~/SDK_Mock_And_Testing.zh-CN.md) |
| [Demo UI Notice](Documentation~/README_UI.md) | [Demo UI 说明](Documentation~/README_UI.zh-CN.md) |
| [Demo UI](Documentation~/README_UI.md) | [Demo UI](Documentation~/README_UI.zh-CN.md) |
## Public Package Scope
## Runtime Notes
- SDK source files are not included.
- `.pdb` debug symbols are not included.
- Demo and test source files are not included.
- Importable `Samples~` are not included in this DLL-only release.
- Sample source and internal validation tests are maintained in the private development SDK repository.
- Keep one `FaceModuleManager` in each scene.
- Use `Close()` or `CloseAsync()` when leaving a scene or quitting the app.
- When auto verify is enabled, use `StopFaceOperationAsync()` before enrollment, user management, QR scan, image capture, or other exclusive operations.

58
README.zh-CN.md
View File

@ -1,6 +1,6 @@
# AISU SI-M1 Face SDK
`xin.aisu.si-m1.face` 是面向 AISU SI-M1 人脸识别模组的 Unity UPM 包。公开发布包以编译后的 DLL 形式提供，不包含 SDK 源码、Demo 源码、测试源码或调试符号。
`xin.aisu.si-m1.face` 是面向 AISU SI-M1 人脸识别模组的 Unity SDK，提供串口通信、协议封包/拆包、模组生命周期管理、人脸验证、人脸录入、用户管理、图片抓拍、二维码、UVC 参数、Mock 通信和示例场景。
English documentation: [README.md](README.md).
@ -10,34 +10,17 @@ English documentation: [README.md](README.md).
|---|---|
| Package Name | `xin.aisu.si-m1.face` |
| Display Name | `AISU SI-M1 Face SDK` |
| Version | `0.1.5` |
| Runtime Assembly | `Aisu.SIM1.Face.Runtime.dll` |
| Editor Assembly | `Aisu.SIM1.Face.Editor.dll` |
| Unity Version | `2021.3` 或更高 |
| 用户项目配置资产 | 导入项目中的 `Assets/AISU/SI-M1 Face SDK/FaceSdkSettings.asset` |
## 安装
在 Unity Package Manager 中使用以下 Git URL 导入：
```text
https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.5
```
或写入 `Packages/manifest.json`：
```json
"xin.aisu.si-m1.face": "https://git.aisu.xin/aisu-sdk/si-m1-face-package.git#v0.1.5"
```
Unity 对 Git URL 包可能会在 `Library/PackageCache` 中显示为 `xin.aisu.si-m1.face@<commit-hash>`。这是 Git 包的正常行为；包版本仍由 `package.json` 中的 `version` 字段定义。
| 配置资产路径 | `Assets/Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset` |
## 快速开始
1. 打开 `AISU/SI-M1 Face SDK/Settings`，创建或加载 `FaceSdkSettings`。
2. 配置串口号、波特率、Mock 模式和日志选项。
3. 打开 `AISU/SI-M1 Face SDK/Create Manager GameObject`，在当前场景中创建 `FaceModuleManager`。
4. 在业务脚本中引用该 Manager 并调用 SDK 服务。
1. 打开 `AISU/SI-M1 Face SDK/Settings`。
2. 配置串口号、波特率、Mock 模式、自动验证和日志选项。
3. 在场景中保留一个 `FaceModuleManager`，并绑定配置资产。
4. 通过 `FaceModuleManager` 调用 SDK 服务。
```csharp
using Aisu.SIM1.Face.Core;
@ -55,9 +38,25 @@ public sealed class FaceExample : MonoBehaviour
var version = await manager.Basic.GetVersionAsync();
Debug.Log("SI-M1 version: " + version);
}
private void OnApplicationQuit()
{
manager?.Close();
}
}
```
## Samples
示例场景路径：
```text
Packages/xin.aisu.si-m1.face/Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```
`SI-M1 Face Demo` 用于完整 SDK 命令测试。`Face Detection Demo` 用于摄像头、串口、录入、识别和用户列表的最小流程测试。
## 文档
| English | 中文 |
@ -65,14 +64,11 @@ public sealed class FaceExample : MonoBehaviour
| [Quick Start](Documentation~/SDK_QuickStart.md) | [快速开始](Documentation~/SDK_QuickStart.zh-CN.md) |
| [Configuration](Documentation~/SDK_Configuration.md) | [配置说明](Documentation~/SDK_Configuration.zh-CN.md) |
| [API Reference](Documentation~/SDK_API_Reference.md) | [API 参考](Documentation~/SDK_API_Reference.zh-CN.md) |
| [License Request](Documentation~/SDK_License_Request.md) | [授权申请](Documentation~/SDK_License_Request.zh-CN.md) |
| [Mock and Testing](Documentation~/SDK_Mock_And_Testing.md) | [Mock 与测试](Documentation~/SDK_Mock_And_Testing.zh-CN.md) |
| [Demo UI Notice](Documentation~/README_UI.md) | [Demo UI 说明](Documentation~/README_UI.zh-CN.md) |
| [Demo UI](Documentation~/README_UI.md) | [Demo UI](Documentation~/README_UI.zh-CN.md) |
## 公开包范围
## 运行注意
- 不包含 SDK 源码。
- 不包含 `.pdb` 调试符号。
- 不包含 Demo 和测试源码。
- DLL-only 公开版本不包含可导入的 `Samples~`。
- 示例源码和内部验证测试保留在私有开发 SDK 仓库中。
- 每个场景只保留一个 `FaceModuleManager`。
- 离开场景或退出应用时调用 `Close()` 或 `CloseAsync()`。
- 开启自动验证后，录入、用户管理、二维码、抓拍等独占操作前调用 `StopFaceOperationAsync()`。

1
Resources/AISU/SI-M1 Face SDK/FaceSdkSettings.asset
View File

@ -24,6 +24,7 @@ MonoBehaviour:
m_mockResponseDelayFrames: 1
m_autoVerifyOnOpen: 0
m_autoVerifyTimeout: 10
m_autoVerifyResultIntervalMs: 1000
m_stopAutoVerifyBeforeExclusiveCommand: 1
m_exclusiveCommandPolicy: 1
m_debugLogEnabled: 1

BIN
Runtime/Aisu.SIM1.Face.Runtime.dll
View File

Binary file not shown.

0
Samples~.meta → Samples.meta
View File

0
Samples~/Face Detection Demo.meta → Samples/Face Detection Demo.meta
View File

0
Samples~/Face Detection Demo/Aisu.SIM1.Face.Samples.FaceDetectionDemo.asmdef → Samples/Face Detection Demo/Aisu.SIM1.Face.Samples.FaceDetectionDemo.asmdef
View File

0
Samples~/Face Detection Demo/Aisu.SIM1.Face.Samples.FaceDetectionDemo.asmdef.meta → Samples/Face Detection Demo/Aisu.SIM1.Face.Samples.FaceDetectionDemo.asmdef.meta
View File

4
Samples~/Face Detection Demo/README.md → Samples/Face Detection Demo/README.md
View File

@ -4,10 +4,10 @@
## 场景
通过 Package Manager 导入 `SI-M1 Face Demo`，或使用 `AISU/SI-M1 Face SDK/Generate Demo Scene` 后，场景会位于：
场景位于包内普通 `Samples` 目录：
```text
Assets/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
Packages/xin.aisu.si-m1.face/Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
```
打开该场景后运行，`FaceDetectionDemoBootstrap` 会自动生成单页 UGUI。

0
Samples~/Face Detection Demo/README.md.meta → Samples/Face Detection Demo/README.md.meta
View File

0
Samples~/Face Detection Demo/Scenes.meta → Samples/Face Detection Demo/Scenes.meta
View File

0
Samples~/Face Detection Demo/Scenes/FaceDetectionDemo.unity → Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity
View File

0
Samples~/Face Detection Demo/Scenes/FaceDetectionDemo.unity.meta → Samples/Face Detection Demo/Scenes/FaceDetectionDemo.unity.meta
View File

0
Samples~/Face Detection Demo/Scripts.meta → Samples/Face Detection Demo/Scripts.meta
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoBootstrap.cs → Samples/Face Detection Demo/Scripts/FaceDetectionDemoBootstrap.cs
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoBootstrap.cs.meta → Samples/Face Detection Demo/Scripts/FaceDetectionDemoBootstrap.cs.meta
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoCamera.cs → Samples/Face Detection Demo/Scripts/FaceDetectionDemoCamera.cs
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoCamera.cs.meta → Samples/Face Detection Demo/Scripts/FaceDetectionDemoCamera.cs.meta
View File

15
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoController.cs → Samples/Face Detection Demo/Scripts/FaceDetectionDemoController.cs
View File

@ -216,9 +216,16 @@ namespace Aisu.SIM1.Face.Samples.FaceDetectionDemo
/// </summary>
public void DisconnectModule()
{
m_manager?.Close();
LogInfo("模组连接已关闭");
RefreshStatus();
RunAsync(async () =>
{
if (m_manager != null)
{
await m_manager.CloseAsync();
}
LogInfo("模组连接已关闭");
RefreshStatus();
});
}
/// <summary>
@ -426,7 +433,7 @@ namespace Aisu.SIM1.Face.Samples.FaceDetectionDemo
{
try
{
await m_manager.Basic.FaceResetAsync();
await m_manager.StopFaceOperationAsync();
LogInfo(operationName + " 前已取消残留人脸流程");
}
catch (Exception ex)

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoController.cs.meta → Samples/Face Detection Demo/Scripts/FaceDetectionDemoController.cs.meta
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoLogger.cs → Samples/Face Detection Demo/Scripts/FaceDetectionDemoLogger.cs
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoLogger.cs.meta → Samples/Face Detection Demo/Scripts/FaceDetectionDemoLogger.cs.meta
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoUserList.cs → Samples/Face Detection Demo/Scripts/FaceDetectionDemoUserList.cs
View File

0
Samples~/Face Detection Demo/Scripts/FaceDetectionDemoUserList.cs.meta → Samples/Face Detection Demo/Scripts/FaceDetectionDemoUserList.cs.meta
View File

0
Samples~/SI-M1 Face Demo.meta → Samples/SI-M1 Face Demo.meta
View File

0
Samples~/SI-M1 Face Demo/Aisu.SIM1.Face.Samples.asmdef → Samples/SI-M1 Face Demo/Aisu.SIM1.Face.Samples.asmdef
View File

0
Samples~/SI-M1 Face Demo/Aisu.SIM1.Face.Samples.asmdef.meta → Samples/SI-M1 Face Demo/Aisu.SIM1.Face.Samples.asmdef.meta
View File

0
Samples~/SI-M1 Face Demo/Scenes.meta → Samples/SI-M1 Face Demo/Scenes.meta
View File

0
Samples~/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity → Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity
View File

0
Samples~/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity.meta → Samples/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity.meta
View File

0
Samples~/SI-M1 Face Demo/Scripts.meta → Samples/SI-M1 Face Demo/Scripts.meta
View File

0
Samples~/SI-M1 Face Demo/Scripts/Core.meta → Samples/SI-M1 Face Demo/Scripts/Core.meta
View File

12
Samples~/SI-M1 Face Demo/Scripts/Core/FaceModuleKeyboardTester.cs → Samples/SI-M1 Face Demo/Scripts/Core/FaceModuleKeyboardTester.cs
View File

@ -303,10 +303,14 @@ namespace Aisu.SIM1.Face.Core
/// <summary>
/// 关闭串口。
/// </summary>
public void CloseSerial()
public async void CloseSerial()
{
Manager.Close();
Log("串口已关闭。");
try
{
await Manager.CloseAsync();
Log("串口已关闭。");
}
catch (Exception ex) { LogError("关闭串口失败：" + ex.Message); }
}
/// <summary>
@ -379,7 +383,7 @@ namespace Aisu.SIM1.Face.Core
/// </summary>
public async void ResetModule()
{
try { await Manager.Basic.ResetAsync(); Log("RESET 成功。"); }
try { await Manager.StopFaceOperationAsync(); Log("已停止当前人脸流程。"); }
catch (Exception ex) { LogError("RESET 失败：" + ex.Message); }
}

0
Samples~/SI-M1 Face Demo/Scripts/Core/FaceModuleKeyboardTester.cs.meta → Samples/SI-M1 Face Demo/Scripts/Core/FaceModuleKeyboardTester.cs.meta
View File

0
Samples~/SI-M1 Face Demo/UI.meta → Samples/SI-M1 Face Demo/UI.meta
View File

0
Samples~/SI-M1 Face Demo/UI/Common.meta → Samples/SI-M1 Face Demo/UI/Common.meta
View File

0
Samples~/SI-M1 Face Demo/UI/Common/FaceModuleDemoBootstrap.cs → Samples/SI-M1 Face Demo/UI/Common/FaceModuleDemoBootstrap.cs
View File

0
Samples~/SI-M1 Face Demo/UI/Common/FaceModuleDemoBootstrap.cs.meta → Samples/SI-M1 Face Demo/UI/Common/FaceModuleDemoBootstrap.cs.meta
View File

0
Samples~/SI-M1 Face Demo/UI/Common/FaceModuleUiCommon.cs → Samples/SI-M1 Face Demo/UI/Common/FaceModuleUiCommon.cs
View File

0
Samples~/SI-M1 Face Demo/UI/Common/FaceModuleUiCommon.cs.meta → Samples/SI-M1 Face Demo/UI/Common/FaceModuleUiCommon.cs.meta
View File

0
Samples~/SI-M1 Face Demo/UI/Pages.meta → Samples/SI-M1 Face Demo/UI/Pages.meta
View File

0
Samples~/SI-M1 Face Demo/UI/Pages/FaceModuleAdvancedPages.cs → Samples/SI-M1 Face Demo/UI/Pages/FaceModuleAdvancedPages.cs
View File

0
Samples~/SI-M1 Face Demo/UI/Pages/FaceModuleAdvancedPages.cs.meta → Samples/SI-M1 Face Demo/UI/Pages/FaceModuleAdvancedPages.cs.meta
View File

27
Samples~/SI-M1 Face Demo/UI/Pages/FaceModulePages.cs → Samples/SI-M1 Face Demo/UI/Pages/FaceModulePages.cs
View File

@ -118,9 +118,12 @@ namespace Aisu.SIM1.Face.UI.Pages
/// </summary>
public void CloseConnection()
{
m_manager.Close();
RefreshState();
SetResult("连接已关闭");
RunAsync(async () =>
{
await m_manager.CloseAsync();
RefreshState();
SetResult("连接已关闭");
});
}
/// <summary>等待 READY NOTE。</summary>
@ -439,14 +442,7 @@ namespace Aisu.SIM1.Face.UI.Pages
RunAsync(async () =>
{
if (!RequireConnected()) return;
if (m_manager.IsAutoVerifyEnabled)
{
await m_manager.StopAutoVerifyAsync();
SetResult("自动验证已关闭");
return;
}
await m_manager.Basic.ResetAsync();
await m_manager.StopFaceOperationAsync();
SetResult("已停止验证");
});
}
@ -844,14 +840,7 @@ namespace Aisu.SIM1.Face.UI.Pages
RunAsync(async () =>
{
if (!RequireConnected()) return;
if (m_manager.IsAutoVerifyEnabled)
{
await m_manager.StopAutoVerifyAsync();
SetResult("自动探测已停止");
return;
}
await m_manager.Basic.ResetAsync();
await m_manager.StopFaceOperationAsync();
SetResult("已停止");
});
}

0
Samples~/SI-M1 Face Demo/UI/Pages/FaceModulePages.cs.meta → Samples/SI-M1 Face Demo/UI/Pages/FaceModulePages.cs.meta
View File

0
Samples~/SI-M1 Face Demo/UI/ViewModels.meta → Samples/SI-M1 Face Demo/UI/ViewModels.meta
View File

0
Samples~/SI-M1 Face Demo/UI/ViewModels/FaceModuleViewModels.cs → Samples/SI-M1 Face Demo/UI/ViewModels/FaceModuleViewModels.cs
View File

0
Samples~/SI-M1 Face Demo/UI/ViewModels/FaceModuleViewModels.cs.meta → Samples/SI-M1 Face Demo/UI/ViewModels/FaceModuleViewModels.cs.meta
View File

8
Samples~/SI-M1 Face Demo/Editor.meta
View File

@ -1,8 +0,0 @@
fileFormatVersion: 2
guid: 4ac476647a08a364289fa596d310bf3a
folderAsset: yes
DefaultImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:

19
Samples~/SI-M1 Face Demo/Editor/Aisu.SIM1.Face.Samples.Editor.asmdef
View File

@ -1,19 +0,0 @@
{
"name": "Aisu.SIM1.Face.Samples.Editor",
"rootNamespace": "Aisu.SIM1.Face.Editor",
"references": [
"Aisu.SIM1.Face.Runtime",
"Aisu.SIM1.Face.Samples"
],
"includePlatforms": [
"Editor"
],
"excludePlatforms": [],
"allowUnsafeCode": false,
"overrideReferences": false,
"precompiledReferences": [],
"autoReferenced": true,
"defineConstraints": [],
"versionDefines": [],
"noEngineReferences": false
}

7
Samples~/SI-M1 Face Demo/Editor/Aisu.SIM1.Face.Samples.Editor.asmdef.meta
View File

@ -1,7 +0,0 @@
fileFormatVersion: 2
guid: 73502db286784cc3ac4a9e71f06f1002
AssemblyDefinitionImporter:
externalObjects: {}
userData:
assetBundleName:
assetBundleVariant:

39
Samples~/SI-M1 Face Demo/Editor/FaceModuleDemoSceneGenerator.cs
View File

@ -1,39 +0,0 @@
#if UNITY_EDITOR
using System.IO;
using Aisu.SIM1.Face.Core;
using Aisu.SIM1.Face.UI.Common;
using UnityEditor;
using UnityEditor.SceneManagement;
using UnityEngine;
namespace Aisu.SIM1.Face.Editor
{
/// <summary>
/// 生成 SI-M1 全功能 Demo 场景。
/// </summary>
public static class FaceModuleDemoSceneGenerator
{
private const string ScenePath = "Assets/SI-M1 Face Demo/Scenes/FaceModuleDemo.unity"; // Demo 场景保存路径。
/// <summary>
/// 创建并保存 Demo 场景。
/// </summary>
[MenuItem("AISU/SI-M1 Face SDK/Regenerate Imported Demo Scene")]
public static void Generate()
{
Directory.CreateDirectory(Path.GetDirectoryName(ScenePath));
var scene = EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
var managerGo = new GameObject("FaceModuleManager");
managerGo.AddComponent<FaceModuleManager>();
var bootstrapGo = new GameObject("FaceModuleDemoBootstrap");
bootstrapGo.AddComponent<FaceModuleDemoBootstrap>();
EditorSceneManager.SaveScene(scene, ScenePath);
AssetDatabase.Refresh();
Selection.activeObject = bootstrapGo;
Debug.Log("FaceModule demo scene generated: " + ScenePath);
}
}
}
#endif

11
Samples~/SI-M1 Face Demo/Editor/FaceModuleDemoSceneGenerator.cs.meta
View File

@ -1,11 +0,0 @@
fileFormatVersion: 2
guid: 230f42ee40b783c4784659a677f2fc59
MonoImporter:
externalObjects: {}
serializedVersion: 2
defaultReferences: []
executionOrder: 0
icon: {instanceID: 0}
userData:
assetBundleName:
assetBundleVariant:

6
package.json
View File

@ -3,7 +3,7 @@
"displayName": "AISU SI-M1 Face SDK",
"version": "0.1.6",
"unity": "2021.3",
"description": "Unity UPM package for the AISU SI-M1 face recognition module protocol, transport, command services, lifecycle manager, tests, and demo sample.",
"description": "Unity UPM package for the AISU SI-M1 face recognition module protocol, transport, command services, lifecycle manager, and demo samples.",
"author": {
"name": "AISU"
},
@ -19,12 +19,12 @@
{
"displayName": "SI-M1 Face Demo",
"description": "Full demo scene and UI for connecting, registering, recognizing, querying, deleting, and releasing the SI-M1 face module.",
"path": "Samples~/SI-M1 Face Demo"
"path": "Samples/SI-M1 Face Demo"
},
{
"displayName": "Face Detection Demo",
"description": "Minimal camera preview, serial connection, enrollment, recognition, and user data test scene.",
"path": "Samples~/Face Detection Demo"
"path": "Samples/Face Detection Demo"
}
]
}