SDK API Reference
中文说明见 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.
Namespaces
| Namespace |
Description |
Aisu.SIM1.Face.Core |
Manager, settings, callback adapter, logging, main-thread dispatch |
Aisu.SIM1.Face.Commands |
Business services, command service, encryption adapter |
Aisu.SIM1.Face.Protocol |
Protocol enums, packet build/parse helpers, encoding helpers |
Aisu.SIM1.Face.Transport |
Transport interface, serial transport, mock transport |
Aisu.SIM1.Face.Models |
Reply, note, user, verification, enrollment, image, and UVC models |
FaceModuleManager
Use FaceModuleManager as the recommended single entry point:
using Aisu.SIM1.Face.Core;
Properties
| Property |
Type |
Description |
Basic |
FaceBasicService |
Basic module commands |
Verify |
FaceVerifyService |
Face verification service |
Enrollment |
FaceEnrollmentService |
Face enrollment service |
Users |
FaceUserService |
User management service |
QrCode |
FaceQrCodeService |
QR code service |
Images |
FaceImageService |
Image capture and photo enrollment service |
Features |
FaceFeatureService |
Feature read/write service |
Uvc |
FaceUvcService |
UVC and advanced parameter service |
Encryption |
FaceEncryptionService |
Encryption service |
Callback |
FaceModuleCallbackAdapter |
Callback-style API adapter |
IsOpen |
bool |
Whether the transport is open |
IsReady |
bool |
Whether READY has been received |
CurrentStatus |
FaceModuleStatus |
Current module status |
LastError |
string |
Latest error message |
CurrentCommand |
string |
Current command name |
Config |
FaceModuleConfig |
Current runtime config |
Settings |
FaceSdkSettings |
Bound settings asset |
Methods
| Method |
Description |
ConfigureTransport(IFaceModuleTransport transport) |
Inject a custom transport |
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 |
WaitReadyAsync(int timeoutMs = 5000) |
Wait for READY note |
ProbeReadyByStatusAsync() |
Query status and mark manager ready |
SendRawBytes(byte[] bytes) |
Send raw protocol bytes |
RefreshStatus() |
Asynchronously refresh CurrentStatus |
Events
| Event |
Description |
OnReady |
First READY event |
OnStatusChanged(FaceModuleStatus) |
Module status changed |
OnReplyReceived(FaceReply) |
REPLY packet received |
OnNoteReceived(FaceNote) |
NOTE packet received |
OnFaceStateUpdated(FaceFaceStateNote) |
Face state NOTE received |
OnQrCodeReceived(string) |
QR code NOTE received |
OnFeatureReceived(byte[]) |
Feature data packet received |
OnDataPacketReceived(FacePacket) |
Image/template data packet received |
OnError(FaceResultCode, string) |
Error reported |
OnRawLog(string) |
Raw TX/RX log |
Async Services
FaceBasicService
Access path: manager.Basic
| Method |
Return |
Description |
ResetAsync() |
Task<FaceReply> |
Reset module |
FaceResetAsync() |
Task<FaceReply> |
Cancel current face flow |
GetStatusAsync() |
Task<FaceModuleStatus> |
Get module status |
GetVersionAsync() |
Task<string> |
Get firmware version |
GetSnAsync() |
Task<string> |
Get device serial number |
SetDemoModeAsync(bool enable) |
Task<FaceReply> |
Set Demo Mode |
UpgradeFirmwareAsync() |
Task<FaceReply> |
Start firmware upgrade command |
FaceVerifyService
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 |
FaceEnrollmentService
Access path: manager.Enrollment
| Method |
Return |
Description |
EnrollAsync(bool admin, string userName, FaceDirection direction, byte timeout) |
Task<FaceEnrollResult> |
Interactive multi-direction enrollment |
EnrollSingleAsync(bool admin, string userName, byte timeout) |
Task<FaceEnrollResult> |
Single-frame enrollment |
EnrollIntegratedAsync(bool admin, string userName, FaceDirection direction, byte timeout, bool singleFrame = false, bool duplicateCheck = true) |
Task<FaceEnrollResult> |
Integrated enrollment |
EnrollSnapFaceImageAsync(bool admin, string userName) |
Task<FaceEnrollResult> |
Capture face image and enroll |
FaceUserService
Access path: manager.Users
| Method |
Return |
Description |
DeleteUserAsync(int userId) |
Task<FaceReply> |
Delete a user |
DeleteAllAsync() |
Task<FaceReply> |
Delete all users |
GetUserInfoAsync(int userId) |
Task<FaceUserInfo> |
Query one user |
GetAllUserIdsAsync() |
Task<List<int>> |
Query all user IDs |
GetAllUserIds2Async() |
Task<List<int>> |
Query all user IDs with extended command |
GetAllUserInfosAsync() |
Task<List<FaceUserInfo>> |
Query all user details |
GetAllUserInfos2Async() |
Task<List<FaceUserInfo>> |
Query all user details with extended command |
FaceQrCodeService
Access path: manager.QrCode
| Method |
Return |
Description |
ScanQrCodeAsync(byte timeout) |
Task<string> |
Scan QR code and return content |
FaceImageService
Access path: manager.Images
| Method |
Return |
Description |
SnapUploadImageAsync() |
Task<FaceImageResult> |
Capture normal image |
SnapUploadFaceImageAsync() |
Task<FaceImageResult> |
Capture face image |
SnapUploadLargeImageAsync(ImageDpi dpi) |
Task<FaceImageResult> |
Capture large image |
EnrollWithPhotoAsync(byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null) |
Task<FaceEnrollResult> |
Enroll with photo |
EnrollWithPhotoAndIdAsync(int userId, byte[] photoBytes, BioType type, string userName = null, bool duplicateCheck = true, Action<int, int> onProgress = null) |
Task<FaceEnrollResult> |
Enroll photo with specified user ID |
FaceFeatureService
Access path: manager.Features
| Method |
Return |
Description |
ReadFeatureAsync(int userId, FeatureType type) |
Task<byte[]> |
Read user feature |
WriteFeatureAsync(byte[] featureBytes, FeatureType type, string userName = null, Action<int, int> onProgress = null) |
Task<FaceEnrollResult> |
Write feature and enroll |
FaceUvcService
Access path: manager.Uvc
| Method |
Return |
Description |
ReadUsbUvcParametersAsync() |
Task<UsbUvcParameters> |
Read USB/UVC parameters |
SetUsbUvcParametersAsync(UsbUvcParameters parameters) |
Task<FaceReply> |
Set USB/UVC parameters |
SetFaceLocationDisplayAsync(bool visible) |
Task<FaceReply> |
Set face rectangle display |
SetRgbLevelAsync(byte level) |
Task<FaceReply> |
Set RGB level |
SetDuplicateCheckAsync(bool enableCheck) |
Task<FaceReply> |
Set duplicate check |
ReadDuplicateCheckAsync() |
Task<bool> |
Read duplicate check state |
FaceEncryptionService
Access path: manager.Encryption
| Method |
Return |
Description |
SetReleaseEncryptionKeyAsync(byte[] key16) |
Task<FaceReply> |
Set release encryption key |
SetDebugEncryptionKeyAsync(byte[] key16) |
Task<FaceReply> |
Set debug encryption key |
InitEncryptionAsync(byte[] seed4, byte mode) |
Task<FaceReply> |
Initialize encryption |
EnableEncryption(IFaceModuleCrypto crypto) |
void |
Enable local crypto adapter |
DisableEncryption() |
void |
Disable local crypto adapter |
public interface IFaceModuleCrypto
{
byte[] Encrypt(byte[] plainBytes);
byte[] Decrypt(byte[] encryptedBytes);
byte[] GenerateSessionKey(byte[] seed4, byte[] encKey16);
}
Callback API
FaceModuleManager.Callback is useful for Unity UI, button events, legacy callback-style code, or workflows where await is inconvenient.
Callbacks use a consistent pattern:
success is invoked on success.error receives an error message on failure.- Photo enrollment and feature writing support
progress(current, total).
- Callbacks are dispatched back to the Unity main thread through
FaceModuleMainThreadDispatcher.
Lifecycle and Transport
| Method |
Success Callback |
Description |
ConfigureTransport(IFaceModuleTransport transport, Action success, Action<string> error) |
Action |
Inject custom transport |
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 |
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 |
Basic Commands
| Method |
Success Callback |
Description |
Reset(Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Reset module |
FaceReset(Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Cancel current face flow |
GetStatus(Action<FaceModuleStatus> success, Action<string> error) |
Action<FaceModuleStatus> |
Get module status |
GetVersion(Action<string> success, Action<string> error) |
Action<string> |
Get firmware version |
GetSn(Action<string> success, Action<string> error) |
Action<string> |
Get device serial number |
SetDemoMode(bool enable, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set Demo Mode |
UpgradeFirmware(Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Start firmware upgrade |
Verification and Enrollment
| 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 |
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 |
EnrollSnapFaceImage(bool admin, string userName, Action<FaceEnrollResult> success, Action<string> error) |
Action<FaceEnrollResult> |
Capture face image and enroll |
Users
| Method |
Success Callback |
Description |
DeleteUser(int userId, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Delete user |
DeleteAll(Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Delete all users |
GetUserInfo(int userId, Action<FaceUserInfo> success, Action<string> error) |
Action<FaceUserInfo> |
Query one user |
GetAllUserIds(Action<List<int>> success, Action<string> error) |
Action<List<int>> |
Query all user IDs |
GetAllUserIds2(Action<List<int>> success, Action<string> error) |
Action<List<int>> |
Query all user IDs with extended command |
GetAllUserInfos(Action<List<FaceUserInfo>> success, Action<string> error) |
Action<List<FaceUserInfo>> |
Query all user details |
GetAllUserInfos2(Action<List<FaceUserInfo>> success, Action<string> error) |
Action<List<FaceUserInfo>> |
Query all user details with extended command |
QR Code, Images, and Features
| Method |
Success Callback |
Description |
ScanQrCode(byte timeout, Action<string> success, Action<string> error) |
Action<string> |
Scan QR code |
SnapUploadImage(Action<FaceImageResult> success, Action<string> error) |
Action<FaceImageResult> |
Capture normal image |
SnapUploadFaceImage(Action<FaceImageResult> success, Action<string> error) |
Action<FaceImageResult> |
Capture face image |
SnapUploadLargeImage(ImageDpi dpi, Action<FaceImageResult> success, Action<string> error) |
Action<FaceImageResult> |
Capture large image |
EnrollWithPhoto(byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null) |
Action<FaceEnrollResult> |
Enroll with photo |
EnrollWithPhotoAndId(int userId, byte[] photoBytes, BioType type, string userName, bool duplicateCheck, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null) |
Action<FaceEnrollResult> |
Enroll photo with specified user ID |
ReadFeature(int userId, FeatureType type, Action<byte[]> success, Action<string> error) |
Action<byte[]> |
Read user feature |
WriteFeature(byte[] featureBytes, FeatureType type, string userName, Action<FaceEnrollResult> success, Action<string> error, Action<int, int> progress = null) |
Action<FaceEnrollResult> |
Write feature and enroll |
UVC and Encryption
| Method |
Success Callback |
Description |
ReadUsbUvcParameters(Action<UsbUvcParameters> success, Action<string> error) |
Action<UsbUvcParameters> |
Read USB/UVC parameters |
SetUsbUvcParameters(UsbUvcParameters parameters, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set USB/UVC parameters |
SetFaceLocationDisplay(bool visible, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set face rectangle display |
SetRgbLevel(byte level, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set RGB level |
SetDuplicateCheck(bool enableCheck, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set duplicate check |
ReadDuplicateCheck(Action<bool> success, Action<string> error) |
Action<bool> |
Read duplicate check state |
SetReleaseEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set release encryption key |
SetDebugEncryptionKey(byte[] key16, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Set debug encryption key |
InitEncryption(byte[] seed4, byte mode, Action<FaceReply> success, Action<string> error) |
Action<FaceReply> |
Initialize encryption |
EnableEncryption(IFaceModuleCrypto crypto, Action success, Action<string> error) |
Action |
Enable local crypto adapter |
DisableEncryption(Action success, Action<string> error) |
Action |
Disable local crypto adapter |
Main Models
| Type |
Description |
FaceReply |
REPLY packet parse result |
FaceNote |
NOTE packet parse result |
FaceFaceStateNote |
Face state NOTE |
FaceUserInfo |
User ID, name, and admin flag |
FaceVerifyResult |
Verification result, user info, unlock status |
FaceEnrollResult |
Enrollment result, user ID, direction |
FaceImageResult |
Image bytes, Texture2D, user ID |
UsbUvcParameters |
USB/UVC parameters |
FaceCommandException |
Exception thrown for unsuccessful command replies |
