158 lines
5.4 KiB
Markdown
158 lines
5.4 KiB
Markdown
# 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)
|