aisu-sdk/si-m1-face-package

Fork 0

su 249fe589c7 Release DLL-only UPM package v0.1.2 docs

2026-08-04 19:08:10 +08:00

15 KiB

Raw Blame History

SDK API 参考

English documentation: SDK_API_Reference.md.

本文列出 xin.aisu.si-m1.face 对外公开的业务层 API。公开包为 DLL-only 形式，不包含 SDK 源码。

命名空间

命名空间	说明
`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 等模型

FaceModuleManager

推荐使用 FaceModuleManager 作为统一入口：

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)`	收到图片或模板数据包
`OnError(FaceResultCode, string)`	错误上报
`OnRawLog(string)`	原始 TX/RX 日志

异步服务 API

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>`	启动固件升级命令

FaceVerifyService

访问路径：manager.Verify

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

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>`	抓拍人脸后注册

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>>`	使用扩展命令查询全部用户信息

FaceQrCodeService

访问路径：manager.QrCode

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

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 照片注册

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>`	写入特征并注册

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>`	读取查重状态

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`	关闭本地加密算法适配器

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

回调式 API

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

回调规则：

成功时调用 success。
失败时调用 error 并传入错误信息。
照片注册和特征写入支持 progress(current, total)。
回调会通过 FaceModuleMainThreadDispatcher 回到 Unity 主线程。

生命周期与通信

方法	成功回调	说明
`ConfigureTransport(IFaceModuleTransport transport, Action success, Action<string> error)`	`Action`	注入自定义通信层
`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`	关闭通信
`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

基础命令

方法	成功回调	说明
`Reset(Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	复位模组
`FaceReset(Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	取消当前人脸流程
`GetStatus(Action<FaceModuleStatus> success, Action<string> error)`	`Action<FaceModuleStatus>`	获取模组状态
`GetVersion(Action<string> success, Action<string> error)`	`Action<string>`	获取固件版本
`GetSn(Action<string> success, Action<string> error)`	`Action<string>`	获取设备序列号
`SetDemoMode(bool enable, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置 Demo Mode
`UpgradeFirmware(Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	启动固件升级

验证与录入

方法	成功回调	说明
`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>`	启用或关闭自动验证
`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>`	集成式录入
`EnrollSnapFaceImage(bool admin, string userName, Action<FaceEnrollResult> success, Action<string> error)`	`Action<FaceEnrollResult>`	抓拍人脸后注册

用户管理

方法	成功回调	说明
`DeleteUser(int userId, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	删除指定用户
`DeleteAll(Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	删除全部用户
`GetUserInfo(int userId, Action<FaceUserInfo> success, Action<string> error)`	`Action<FaceUserInfo>`	查询指定用户
`GetAllUserIds(Action<List<int>> success, Action<string> error)`	`Action<List<int>>`	查询全部用户 ID
`GetAllUserIds2(Action<List<int>> success, Action<string> error)`	`Action<List<int>>`	使用扩展命令查询全部用户 ID
`GetAllUserInfos(Action<List<FaceUserInfo>> success, Action<string> error)`	`Action<List<FaceUserInfo>>`	查询全部用户信息
`GetAllUserInfos2(Action<List<FaceUserInfo>> success, Action<string> error)`	`Action<List<FaceUserInfo>>`	使用扩展命令查询全部用户信息

二维码、图片与特征

方法	成功回调	说明
`ScanQrCode(byte timeout, Action<string> success, Action<string> error)`	`Action<string>`	扫描二维码
`SnapUploadImage(Action<FaceImageResult> success, Action<string> error)`	`Action<FaceImageResult>`	抓拍普通图片
`SnapUploadFaceImage(Action<FaceImageResult> success, Action<string> error)`	`Action<FaceImageResult>`	抓拍人脸图片
`SnapUploadLargeImage(ImageDpi dpi, Action<FaceImageResult> success, Action<string> error)`	`Action<FaceImageResult>`	抓拍大图
`EnrollWithPhoto(byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)`	`Action<FaceEnrollResult>`	照片注册
`EnrollWithPhotoAndId(int userId, byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)`	`Action<FaceEnrollResult>`	指定用户 ID 照片注册
`ReadFeature(int userId, FeatureType type, Action<byte[]> success, Action<string> error)`	`Action<byte[]>`	读取用户特征
`WriteFeature(byte[] featureBytes, FeatureType type, string userName, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null)`	`Action<FaceEnrollResult>`	写入特征并注册

UVC 与加密

方法	成功回调	说明
`ReadUsbUvcParameters(Action<UsbUvcParameters> success, Action<string> error)`	`Action<UsbUvcParameters>`	读取 USB/UVC 参数
`SetUsbUvcParameters(UsbUvcParameters parameters, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置 USB/UVC 参数
`SetFaceLocationDisplay(bool visible, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置人脸框显示
`SetRgbLevel(byte level, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置 RGB 等级
`SetDuplicateCheck(bool enableCheck, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置查重
`ReadDuplicateCheck(Action<bool> success, Action<string> error)`	`Action<bool>`	读取查重状态
`SetReleaseEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置 Release 加密密钥
`SetDebugEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	设置 Debug 加密密钥
`InitEncryption(byte[] seed4, byte mode, Action<FaceReply> success, Action<string> error)`	`Action<FaceReply>`	初始化加密
`EnableEncryption(IFaceModuleCrypto crypto, Action success, Action<string> error)`	`Action`	启用本地加密算法适配器
`DisableEncryption(Action success, Action<string> error)`	`Action`	关闭本地加密算法适配器

主要模型

类型	说明
`FaceReply`	REPLY 包解析结果
`FaceNote`	NOTE 包解析结果
`FaceFaceStateNote`	人脸状态 NOTE
`FaceUserInfo`	用户 ID、姓名、管理员标记
`FaceVerifyResult`	验证结果、用户信息、开锁状态
`FaceEnrollResult`	录入结果、用户 ID、方向
`FaceImageResult`	图片 bytes、`Texture2D`、用户 ID
`UsbUvcParameters`	USB/UVC 参数
`FaceCommandException`	命令 REPLY 非成功时抛出的异常

15 KiB Raw Blame History