card-reader-830t-package/README.en.md

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

```text
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`:

```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` 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:

- [Getting Started](Documentation~/GettingStarted.en.md)
- [API reference](Documentation~/API.en.md)
- [Basic Sample guide](Samples~/Basic/README.en.md)