289 lines
16 KiB
Markdown
289 lines
16 KiB
Markdown
# SDK API Reference
|
|
|
|
中文说明见 [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.
|
|
|
|
## 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:
|
|
|
|
```csharp
|
|
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 |
|
|
|
|
```csharp
|
|
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 |
|