aisu-sdk/card-reader-830t-package

Fork 0

su 7d2b65ff38 feat: release card reader SDK v0.1.0

2026-09-08 17:55:28 +08:00

5.4 KiB

Raw Permalink Blame History

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...，输入：

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

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

快速开始

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

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。

5.4 KiB Raw Permalink Blame History Unescape Escape