su c7b8ba0cef Prepare DLL-only UPM package v0.1.0

2026-08-04 15:38:28 +08:00

9.4 KiB

Raw Blame History

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 推荐的统一入口。

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

访问路径：

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

访问路径：

manager.Verify

方法	返回	说明
`VerifyAsync(byte timeout, byte maxRecognitionTimes = 30)`	`Task<FaceVerifyResult>`	单次人脸验证
`AutoVerifyAsync(bool enable, byte timeout)`	`Task<FaceVerifyResult>`	启用或关闭自动验证

5. 录入服务 FaceEnrollmentService

访问路径：

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

访问路径：

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

访问路径：

manager.QrCode

方法	返回	说明
`ScanQrCodeAsync(byte timeout)`	`Task<string>`	扫描二维码并返回内容

8. 图片服务 FaceImageService

访问路径：

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

访问路径：

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

访问路径：

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

访问路径：

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：

public interface IFaceModuleCrypto
{
    byte[] Encrypt(byte[] plainBytes);
    byte[] Decrypt(byte[] encryptedBytes);
    byte[] GenerateSessionKey(byte[] seed4, byte[] encKey16);
}

12. 回调式 API

FaceModuleManager.Callback 适合 Unity Button、旧项目回调风格或不方便使用 await 的业务。

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 实现

9.4 KiB Raw Blame History Unescape Escape

SI-M1 Face SDK 接口文档

1. 命名空间

2. FaceModuleManager

属性

方法

事件

3. 基础服务 FaceBasicService

4. 验证服务 FaceVerifyService

5. 录入服务 FaceEnrollmentService

6. 用户服务 FaceUserService

7. 二维码服务 FaceQrCodeService

8. 图片服务 FaceImageService

9. 特征服务 FaceFeatureService

10. UVC 和高级参数 FaceUvcService

11. 加密服务 FaceEncryptionService

12. 回调式 API

13. 主要模型

14. 协议和通信底层

9.4 KiB

Raw Blame History