266 lines
9.4 KiB
Markdown
266 lines
9.4 KiB
Markdown
# SI-M1 Face SDK 接口文档
|
||
|
||
本文列出 SDK 对业务层推荐使用的公开 API。命名空间统一为 `Aisu.SIM1.Face.*`。
|
||
|
||
## 1. 命名空间
|
||
|
||
| 命名空间 | 说明 |
|
||
|---|---|
|
||
| `Aisu.SIM1.Face.Core` | Manager、配置、回调适配、日志、主线程调度 |
|
||
| `Aisu.SIM1.Face.Commands` | 业务服务、命令服务、加密接口 |
|
||
| `Aisu.SIM1.Face.Protocol` | 协议枚举、封包、拆包、编码工具 |
|
||
| `Aisu.SIM1.Face.Transport` | 通信接口、串口、Mock |
|
||
| `Aisu.SIM1.Face.Models` | Reply、Note、用户、验证、录入、图片、UVC 等模型 |
|
||
|
||
## 2. FaceModuleManager
|
||
|
||
`FaceModuleManager` 是 SDK 推荐的统一入口。
|
||
|
||
```csharp
|
||
using Aisu.SIM1.Face.Core;
|
||
```
|
||
|
||
### 属性
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `Basic` | `FaceBasicService` | 基础命令服务 |
|
||
| `Verify` | `FaceVerifyService` | 人脸验证服务 |
|
||
| `Enrollment` | `FaceEnrollmentService` | 人脸录入服务 |
|
||
| `Users` | `FaceUserService` | 用户管理服务 |
|
||
| `QrCode` | `FaceQrCodeService` | 二维码服务 |
|
||
| `Images` | `FaceImageService` | 图片抓拍与照片注册服务 |
|
||
| `Features` | `FaceFeatureService` | 特征读写服务 |
|
||
| `Uvc` | `FaceUvcService` | UVC 和高级参数服务 |
|
||
| `Encryption` | `FaceEncryptionService` | 加密相关服务 |
|
||
| `Callback` | `FaceModuleCallbackAdapter` | 回调式 API 适配 |
|
||
| `IsOpen` | `bool` | 通信是否打开 |
|
||
| `IsReady` | `bool` | 是否收到 READY |
|
||
| `CurrentStatus` | `FaceModuleStatus` | 当前模组状态 |
|
||
| `LastError` | `string` | 最近错误文本 |
|
||
| `CurrentCommand` | `string` | 当前命令名 |
|
||
| `Config` | `FaceModuleConfig` | 当前运行配置 |
|
||
| `Settings` | `FaceSdkSettings` | 当前绑定配置资产 |
|
||
|
||
### 方法
|
||
|
||
| 方法 | 说明 |
|
||
|---|---|
|
||
| `ConfigureTransport(IFaceModuleTransport transport)` | 注入自定义通信层 |
|
||
| `Configure(bool useMockInEditor, string portName, int baudRate)` | 兼容旧代码的快速配置入口 |
|
||
| `ApplySettings(FaceSdkSettings sdkSettings)` | 应用 ScriptableObject 配置并重建 transport |
|
||
| `Open()` | 打开通信 |
|
||
| `Close()` | 关闭通信 |
|
||
| `WaitReadyAsync(int timeoutMs = 5000)` | 等待 READY NOTE |
|
||
| `ProbeReadyByStatusAsync()` | 主动查询状态并标记 READY |
|
||
| `SendRawBytes(byte[] bytes)` | 发送原始协议 bytes |
|
||
| `RefreshStatus()` | 异步刷新 `CurrentStatus` |
|
||
|
||
### 事件
|
||
|
||
| 事件 | 说明 |
|
||
|---|---|
|
||
| `OnReady` | 首次 READY |
|
||
| `OnStatusChanged(FaceModuleStatus)` | 当前状态变化 |
|
||
| `OnReplyReceived(FaceReply)` | 收到 REPLY 包 |
|
||
| `OnNoteReceived(FaceNote)` | 收到 NOTE 包 |
|
||
| `OnFaceStateUpdated(FaceFaceStateNote)` | 收到人脸状态 NOTE |
|
||
| `OnQrCodeReceived(string)` | 收到二维码 NOTE |
|
||
| `OnFeatureReceived(byte[])` | 收到读取特征数据包 |
|
||
| `OnDataPacketReceived(FacePacket)` | 收到 ImageOrTemplate 数据包 |
|
||
| `OnError(FaceResultCode, string)` | 错误上报 |
|
||
| `OnRawLog(string)` | 原始 TX / RX 日志 |
|
||
|
||
## 3. 基础服务 FaceBasicService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Basic
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `ResetAsync()` | `Task<FaceReply>` | 复位模组 |
|
||
| `FaceResetAsync()` | `Task<FaceReply>` | 取消当前人脸流程 |
|
||
| `GetStatusAsync()` | `Task<FaceModuleStatus>` | 获取模组状态 |
|
||
| `GetVersionAsync()` | `Task<string>` | 获取固件版本 |
|
||
| `GetSnAsync()` | `Task<string>` | 获取设备序列号 |
|
||
| `SetDemoModeAsync(bool enable)` | `Task<FaceReply>` | 设置 Demo Mode |
|
||
| `UpgradeFirmwareAsync()` | `Task<FaceReply>` | 启动固件升级命令 |
|
||
|
||
## 4. 验证服务 FaceVerifyService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Verify
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `VerifyAsync(byte timeout, byte maxRecognitionTimes = 30)` | `Task<FaceVerifyResult>` | 单次人脸验证 |
|
||
| `AutoVerifyAsync(bool enable, byte timeout)` | `Task<FaceVerifyResult>` | 启用或关闭自动验证 |
|
||
|
||
## 5. 录入服务 FaceEnrollmentService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Enrollment
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `EnrollAsync(bool admin, string userName, FaceDirection direction, byte timeout)` | `Task<FaceEnrollResult>` | 交互式多方向录入 |
|
||
| `EnrollSingleAsync(bool admin, string userName, byte timeout)` | `Task<FaceEnrollResult>` | 单帧录入 |
|
||
| `EnrollIntegratedAsync(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame = false, bool duplicateCheck = true)` | `Task<FaceEnrollResult>` | 集成式录入 |
|
||
| `EnrollSnapFaceImageAsync(bool admin, string userName)` | `Task<FaceEnrollResult>` | 抓拍人脸后注册 |
|
||
|
||
## 6. 用户服务 FaceUserService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Users
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `DeleteUserAsync(int userId)` | `Task<FaceReply>` | 删除指定用户 |
|
||
| `DeleteAllAsync()` | `Task<FaceReply>` | 删除全部用户 |
|
||
| `GetUserInfoAsync(int userId)` | `Task<FaceUserInfo>` | 查询用户信息 |
|
||
| `GetAllUserIdsAsync()` | `Task<List<int>>` | 查询用户 ID 列表 |
|
||
| `GetAllUserIds2Async()` | `Task<List<int>>` | 使用扩展命令查询用户 ID 列表 |
|
||
| `GetAllUserInfosAsync()` | `Task<List<FaceUserInfo>>` | 查询全部用户详情 |
|
||
| `GetAllUserInfos2Async()` | `Task<List<FaceUserInfo>>` | 使用扩展命令查询全部用户详情 |
|
||
|
||
## 7. 二维码服务 FaceQrCodeService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.QrCode
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `ScanQrCodeAsync(byte timeout)` | `Task<string>` | 扫描二维码并返回内容 |
|
||
|
||
## 8. 图片服务 FaceImageService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Images
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `SnapUploadImageAsync()` | `Task<FaceImageResult>` | 抓拍普通图片 |
|
||
| `SnapUploadFaceImageAsync()` | `Task<FaceImageResult>` | 抓拍人脸图片 |
|
||
| `SnapUploadLargeImageAsync(ImageDpi dpi)` | `Task<FaceImageResult>` | 抓拍大图 |
|
||
| `EnrollWithPhotoAsync(byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 照片注册 |
|
||
| `EnrollWithPhotoAndIdAsync(int userId, byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 指定用户 ID 照片注册 |
|
||
|
||
## 9. 特征服务 FaceFeatureService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Features
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `ReadFeatureAsync(int userId, FeatureType type)` | `Task<byte[]>` | 读取指定用户特征 |
|
||
| `WriteFeatureAsync(byte[] featureBytes, FeatureType type, string userName = null, Action<int, int> onProgress = null)` | `Task<FaceEnrollResult>` | 写入特征并注册 |
|
||
|
||
## 10. UVC 和高级参数 FaceUvcService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Uvc
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `ReadUsbUvcParametersAsync()` | `Task<UsbUvcParameters>` | 读取 USB / UVC 参数 |
|
||
| `SetUsbUvcParametersAsync(UsbUvcParameters parameters)` | `Task<FaceReply>` | 设置 USB / UVC 参数 |
|
||
| `SetFaceLocationDisplayAsync(bool visible)` | `Task<FaceReply>` | 设置人脸框显示 |
|
||
| `SetRgbLevelAsync(byte level)` | `Task<FaceReply>` | 设置 RGB 阈值 |
|
||
| `SetDuplicateCheckAsync(bool enableCheck)` | `Task<FaceReply>` | 设置查重 |
|
||
| `ReadDuplicateCheckAsync()` | `Task<bool>` | 读取查重状态 |
|
||
|
||
## 11. 加密服务 FaceEncryptionService
|
||
|
||
访问路径：
|
||
|
||
```csharp
|
||
manager.Encryption
|
||
```
|
||
|
||
| 方法 | 返回 | 说明 |
|
||
|---|---|---|
|
||
| `SetReleaseEncryptionKeyAsync(byte[] key16)` | `Task<FaceReply>` | 设置 Release 加密密钥 |
|
||
| `SetDebugEncryptionKeyAsync(byte[] key16)` | `Task<FaceReply>` | 设置 Debug 加密密钥 |
|
||
| `InitEncryptionAsync(byte[] seed4, byte mode)` | `Task<FaceReply>` | 初始化加密流程 |
|
||
| `EnableEncryption(IFaceModuleCrypto crypto)` | `void` | 设置本地加密算法适配器 |
|
||
| `DisableEncryption()` | `void` | 关闭本地加密算法适配器 |
|
||
|
||
`IFaceModuleCrypto`：
|
||
|
||
```csharp
|
||
public interface IFaceModuleCrypto
|
||
{
|
||
byte[] Encrypt(byte[] plainBytes);
|
||
byte[] Decrypt(byte[] encryptedBytes);
|
||
byte[] GenerateSessionKey(byte[] seed4, byte[] encKey16);
|
||
}
|
||
```
|
||
|
||
## 12. 回调式 API
|
||
|
||
`FaceModuleManager.Callback` 适合 Unity Button、旧项目回调风格或不方便使用 `await` 的业务。
|
||
|
||
```csharp
|
||
manager.Callback.Verify(
|
||
timeout: 10,
|
||
success: result => Debug.Log(result.UserId),
|
||
error: message => Debug.LogError(message));
|
||
```
|
||
|
||
回调特点：
|
||
|
||
- 所有 API 统一使用 `success` 和 `error`。
|
||
- 照片注册、特征写入支持 `progress(current, total)`。
|
||
- 回调会通过 `FaceModuleMainThreadDispatcher` 回到 Unity 主线程。
|
||
|
||
## 13. 主要模型
|
||
|
||
| 类型 | 说明 |
|
||
|---|---|
|
||
| `FaceReply` | REPLY 包解析结果 |
|
||
| `FaceNote` | NOTE 包解析结果 |
|
||
| `FaceFaceStateNote` | 人脸状态 NOTE |
|
||
| `FaceUserInfo` | 用户 ID、姓名、管理员标记 |
|
||
| `FaceVerifyResult` | 验证结果、用户信息、开锁状态 |
|
||
| `FaceEnrollResult` | 录入结果、用户 ID、方向 |
|
||
| `FaceImageResult` | 图片 bytes、Texture2D、用户 ID |
|
||
| `UsbUvcParameters` | USB / UVC 参数 |
|
||
| `FaceCommandException` | 命令 REPLY 非成功时抛出的异常 |
|
||
|
||
## 14. 协议和通信底层
|
||
|
||
业务层通常不需要直接使用底层 API。需要协议调试或自定义通信时可使用：
|
||
|
||
| 类型 | 说明 |
|
||
|---|---|
|
||
| `FacePacketBuilder` | 封包 |
|
||
| `FacePacketParser` | 拆包 |
|
||
| `FaceProtocolEncoding` | 用户名、ID、结果文本等编码工具 |
|
||
| `IFaceModuleTransport` | 通信接口 |
|
||
| `SerialPortTransport` | 串口实现 |
|
||
| `MockFaceModuleTransport` | Mock 实现 |
|