137 lines
4.5 KiB
Markdown
137 lines
4.5 KiB
Markdown
# 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.
|