# API Reference

This document covers the Unity-facing public API of AISU 830T Card Reader SDK v0.1.0. The namespace is `Aisu.CardReader`.

## CardReaderManager

`CardReaderManager` is the scene-level reader component. Add it to a GameObject and keep one instance in the scene.

### Main properties

```csharp
public static CardReaderManager Instance { get; }
public SerialDeviceOptions SerialOptions { get; set; }
public bool IsConnected { get; }
```

- `Instance`: the current scene Manager.
- `SerialOptions`: serial configuration used by the Inspector and by code.
- `IsConnected`: whether the reader is currently connected.

### Main methods

```csharp
public void OpenReader();
public void CloseReader();
```

`OpenReader()` starts the reader connection. `CloseReader()` closes the current connection and stops automatic reconnect; `OpenReader()` can be called again later.

### Events

```csharp
public UnityEvent OnConnected { get; }
public UnityEvent OnDisconnected { get; }
public UnityEvent<SerialDeviceState> OnStateChanged { get; }
public UnityEvent<CardInfo> OnCardReceived { get; }
public UnityEvent<CardReaderErrorEventArgs> OnError { get; }
```

Use `AddListener` and `RemoveListener` for event subscription. UnityEvents raised through the Manager are dispatched on the Unity main thread.

## CardReaderApi

`CardReaderApi` is the static access point for the current `CardReaderManager` and is convenient for application scripts.

```csharp
public static bool IsConnected { get; }
public static void Open();
public static void Close();

public static UnityEvent OnConnected { get; }
public static UnityEvent OnDisconnected { get; }
public static UnityEvent<SerialDeviceState> OnStateChanged { get; }
public static UnityEvent<CardInfo> OnCardReceived { get; }
public static UnityEvent<CardReaderErrorEventArgs> OnError { get; }
```

`Open()` starts the connection and `Close()` closes it. Calling either method or accessing an event without an active `CardReaderManager` throws `InvalidOperationException`.

## SerialDeviceOptions

`SerialDeviceOptions` is the configuration type of `CardReaderManager.SerialOptions`. The currently exposed fields are:

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `PortName` | `string` | none | Windows COM-port name. |
| `BaudRate` | `int` | `9600` | Baud rate. |
| `Parity` | `Parity` | `None` | Parity mode. |
| `DataBits` | `int` | `8` | Number of data bits. |
| `StopBits` | `StopBits` | `One` | Stop-bit setting. |
| `Handshake` | `Handshake` | `None` | Handshake mode. |
| `ReadTimeout` | `int` | `100` | Read timeout in milliseconds. |
| `WriteTimeout` | `int` | `1000` | Write timeout in milliseconds. |
| `RtsEnable` | `bool` | `true` | Whether RTS is enabled. |
| `DtrEnable` | `bool` | `true` | Whether DTR is enabled. |
| `AutoReconnect` | `bool` | `true` | Whether to keep retrying after a connection failure. |
| `ReconnectInterval` | `int` | `1000` | Automatic reconnect interval in milliseconds. |
| `MaxPendingSendCount` | `int` | `256` | Pending-data capacity. |

The actual COM port and UART settings depend on the connected reader.

## CardInfo

`CardInfo` is the card data supplied by `OnCardReceived`:

```csharp
public CardType CardType { get; }
public byte CardTypeCode { get; }
public string CardNumber { get; }
```

- `CardType`: the currently mapped type is `CardType.EM4100`.
- `CardTypeCode`: the raw type code reported by the device. Unknown values are preserved.
- `CardNumber`: a decimal card-number string.

### CardNumber rules

`CardNumber` is a `string` containing the decimal card number. Its default minimum width is 10 digits: values shorter than 10 digits are left-padded with `0`, and values longer than 10 digits are not truncated.

## CardType

```csharp
public enum CardType
{
    Unknown = 0,
    EM4100 = 0x02
}
```

## Error events

`OnError` provides `CardReaderErrorEventArgs`:

```csharp
public CardReaderException Exception { get; }
```

`Exception` is the actual exception object. Common causes include a missing COM port, a port already in use, and a failed connection. Identical connection errors are not repeatedly emitted, while automatic reconnect continues when `AutoReconnect` is enabled.

## Event usage

Register listeners with `AddListener` in `OnEnable` and remove them with `RemoveListener` in `OnDisable`:

```csharp
private void OnEnable()
{
    CardReaderApi.OnCardReceived.AddListener(OnCardReceived);
}

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

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