# AISU 830T Card Reader SDK

AISU 830T Card Reader SDK 是一个面向 Unity 的 UPM Package，用于在 Windows 上连接 830T 读卡器，接收设备主动上报的卡片信息。

## 支持环境

- Unity 2021.3 或更高版本
- AISU 830T Card Reader
- Package ID：`xin.aisu.card-reader-830t`

当前不支持 Wiegand、主动寻卡/读卡/写卡命令或 ACK/NAK API。

## 安装

在 Unity Package Manager 中选择 **Add package from git URL...**，输入：

```text
https://git.aisu.xin/aisu-sdk/card-reader-830t-package.git
```

也可以将本地 Package 目录添加到 Unity 项目。安装后，在包详情的 **Samples** 区域导入 **Basic** 或 **Console Demo**。

## 快速开始

在场景中放置一个 `CardReaderManager`，在 Inspector 中配置 `SerialOptions`，然后使用 `CardReaderApi`：

```csharp
using Aisu.CardReader;
using UnityEngine;

public sealed class CardReaderExample : MonoBehaviour
{
    private void OnEnable()
    {
        CardReaderApi.OnConnected.AddListener(OnConnected);
        CardReaderApi.OnCardReceived.AddListener(OnCardReceived);
        CardReaderApi.OnError.AddListener(OnError);
    }

    private void Start()
    {
        CardReaderApi.Open();
    }

    private static void OnConnected()
    {
        Debug.Log("Card reader connected.");
    }

    private static void OnCardReceived(CardInfo card)
    {
        Debug.Log($"{card.CardType} ({card.CardTypeCode:X2}): {card.CardNumber}");
    }

    private static void OnError(CardReaderErrorEventArgs error)
    {
        Debug.LogError(error.Exception.Message);
    }

    private void OnDisable()
    {
        CardReaderApi.OnConnected.RemoveListener(OnConnected);
        CardReaderApi.OnCardReceived.RemoveListener(OnCardReceived);
        CardReaderApi.OnError.RemoveListener(OnError);
        CardReaderApi.Close();
    }
}
```

## CardReaderManager

`CardReaderManager` 是场景级入口。场景中应保持一个 Manager 实例。它提供 `SerialOptions`、`IsConnected`、`OpenReader()`、`CloseReader()` 以及连接、断开、状态、卡片和错误事件。

## Inspector 串口参数

`SerialOptions` 类型为 `SerialDeviceOptions`，当前公开字段如下：

- `PortName`：Windows COM 端口，例如 `COM3`。
- `BaudRate`：波特率，默认 `9600`。
- `Parity`：校验方式，默认 `None`。
- `DataBits`：数据位，默认 `8`。
- `StopBits`：停止位，默认 `One`。
- `Handshake`：握手方式，默认 `None`。
- `ReadTimeout`：读超时毫秒数，默认 `100`。
- `WriteTimeout`：写超时毫秒数，默认 `1000`。
- `RtsEnable` / `DtrEnable`：RTS/DTR，默认开启。
- `AutoReconnect`：连接异常后是否自动重连，默认开启。
- `ReconnectInterval`：重连间隔毫秒数，默认 `1000`。
- `MaxPendingSendCount`：发送队列容量，默认 `256`。

请根据实际设备参数配置 UART 字段。Sample 不包含固定的本地 COM 端口。

## CardReaderApi 与事件

`CardReaderApi` 是当前 Manager 的静态访问入口，提供：

- `Open()`：启动 Reader 连接。
- `Close()`：关闭当前连接并停止自动重连；之后可以再次 `Open()`。
- `IsConnected`：当前连接状态。
- `OnConnected`、`OnDisconnected`、`OnStateChanged`、`OnCardReceived`、`OnError`。

事件使用 `AddListener` 注册、`RemoveListener` 解除，建议在 `OnEnable` 和 `OnDisable` 中成对处理。没有活动的 `CardReaderManager` 时访问事件或调用 `Open`/`Close` 会抛出 `InvalidOperationException`。

## CardInfo 与 CardNumber

`CardInfo` 包含：

- `CardType`：当前已知类型为 `CardType.EM4100`。
- `CardTypeCode`：设备上报的原始类型码。
- `CardNumber`：类型为 `string` 的十进制卡号字符串。

`CardNumber` 默认最小长度为 10 位；不足 10 位时在左侧补 `0`，超过 10 位时不截断。

## 自动重连与错误处理

当 `AutoReconnect` 开启时，连接异常后 SDK 会按 `ReconnectInterval` 继续尝试连接。`OnError` 提供真实的 `Exception`，常见原因包括 COM 端口不存在、端口被占用或连接失败。相同的连接错误不会持续刷出重复事件，但 SDK 仍会继续自动重连。

## Samples

- **Basic**：完整 UI 操作、COM 端口选择、连接状态、卡片信息和错误日志显示。
- **Console Demo**：最小 API 调用和日志输出示例。

## 常见问题

### 找不到 COM 端口

确认设备已连接、驱动已安装，并在 Windows 设备管理器中查看实际 COM 名称。Basic Sample 的 **Refresh** 会重新扫描端口。

### COM 端口被占用

关闭其他串口工具或正在使用该端口的程序，然后重新选择端口并调用 `Open()`。

### 无法连接 Reader

检查 `PortName`、波特率、Parity、DataBits 和 StopBits 是否与设备设置一致，并确认设备没有被其他程序占用。

### 自动重连如何工作

开启 `AutoReconnect` 后，SDK 会按 `ReconnectInterval` 重试。调用 `Close()` 会停止当前连接和自动重连。

### Unity 退出后是否释放串口

`CardReaderManager` 在销毁或应用退出时会自动释放串口资源。

### 如何导入 Basic Sample

安装 Package 后，在 Package Manager 的包详情中找到 **Samples**，点击 **Import** 导入 **Basic**。导入路径带有版本目录是 Unity 的标准行为。

## 版本

当前文档对应 SDK `v0.1.0`。

更多内容：

- [快速开始](Documentation~/GettingStarted.zh-CN.md)
- [API 文档](Documentation~/API.zh-CN.md)
- [Basic Sample 文档](Samples~/Basic/README.md)