# 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 |