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

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

5.8 KiB

Raw Permalink Blame History

AISU 830T Card Reader SDK

AISU 830T Card Reader SDK is a Unity UPM package for connecting an 830T card reader and receiving card data reported by the device.

Supported environment

Unity 2021.3 or later
AISU 830T Card Reader
Package ID: xin.aisu.card-reader-830t

Android, Wiegand, active card search/read/write commands, and ACK/NAK APIs are not supported in this release.

Installation

In Unity Package Manager, choose Add package from git URL... and enter:

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

You can also add the package from a local folder. After installation, import Basic or Console Demo from the package's Samples section.

Quick start

Place one CardReaderManager in the scene, configure SerialOptions in the Inspector, and use 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 is the scene-level entry point. Keep one Manager instance in the scene. It exposes SerialOptions, IsConnected, OpenReader(), CloseReader(), and connection, disconnection, state, card, and error events.

Inspector serial settings

SerialOptions uses SerialDeviceOptions. The currently exposed fields are:

PortName: Windows COM port, for example COM3.
BaudRate: baud rate, default 9600.
Parity: parity mode, default None.
DataBits: data bits, default 8.
StopBits: stop bits, default One.
Handshake: handshake mode, default None.
ReadTimeout: read timeout in milliseconds, default 100.
WriteTimeout: write timeout in milliseconds, default 1000.
RtsEnable / DtrEnable: RTS/DTR flags, enabled by default.
AutoReconnect: whether to retry after a connection failure, enabled by default.
ReconnectInterval: retry interval in milliseconds, default 1000.
MaxPendingSendCount: send queue capacity, default 256.

Configure the UART fields for the actual device. The Samples do not contain a fixed local COM port.

CardReaderApi and events

CardReaderApi is the static access point for the current Manager. It provides:

Open(): starts the reader connection.
Close(): closes the current connection and stops automatic reconnect; Open() can be called again later.
IsConnected: current connection state.
OnConnected, OnDisconnected, OnStateChanged, OnCardReceived, and OnError.

Use AddListener to subscribe and RemoveListener to unsubscribe. Pair them in OnEnable and OnDisable. Accessing events or calling Open/Close without an active CardReaderManager throws InvalidOperationException.

CardInfo and CardNumber

CardInfo contains:

CardType: the currently mapped type is CardType.EM4100.
CardTypeCode: the raw type code reported by the device.
CardNumber: a decimal card-number string of type string.

CardNumber has a default minimum width of 10 digits. Values shorter than 10 digits are left-padded with 0; longer values are not truncated.

Automatic reconnect and errors

When AutoReconnect is enabled, the SDK continues retrying after a connection failure according to ReconnectInterval. OnError provides the actual Exception; common causes include a missing COM port, a port already in use, or a failed connection. Identical connection errors are not repeatedly emitted, while automatic reconnect continues.

Samples

Basic: full UI controls, COM-port selection, connection state, card information, and error log display.
Console Demo: minimal API calls and console logging.

Frequently asked questions

No COM port is listed

Confirm that the reader is connected and its driver is installed. Check the actual COM name in Windows Device Manager. The Basic Sample's Refresh button rescans available ports.

The COM port is already in use

Close other serial tools or applications using the port, then select it again and call Open().

The reader cannot connect

Check PortName, baud rate, parity, data bits, and stop bits against the device settings. Also confirm that no other program owns the port.

How does automatic reconnect work?

With AutoReconnect enabled, the SDK retries at ReconnectInterval. Calling Close() stops the current connection and automatic reconnect.

Are serial resources released when Unity exits?

CardReaderManager releases the serial resources when it is destroyed or when the application exits.

How do I import the Basic Sample?

After installing the package, open its details in Package Manager, find Samples, and click Import for Basic. A version directory in the imported path is standard Unity behavior.

Version

This documentation describes SDK v0.1.0.

More information:

5.8 KiB Raw Permalink Blame History