# KTag Terminal Subapp

A Jetpack Compose Android application providing a serial terminal for USB-connected KTag devices.

## Overview

The Terminal app connects to KTag devices via USB serial, allowing you to:

- Send commands to the device
- View debug output and responses
- Monitor device state in real-time
- Share terminal logs for debugging

This is primarily a development and debugging tool for working with KTag firmware.

## Architecture

The app follows a simple architecture with a manager class handling USB serial communication.

```
┌─────────────────────────────────────────────────────────┐
│                  TerminalActivity                       │
│                  (Compose Host)                         │
│  • Device selection dropdown                            │
│  • Terminal output display                              │
│  • Command input field                                  │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                 UsbSerialManager                        │
│  • USB device detection & permissions                   │
│  • Serial port connection management                    │
│  • Read/Write operations                                │
│  • Connection state callbacks                           │
└─────────────────────────────────────────────────────────┘
```

## File Structure

```
src/main/java/club/clubk/ktag/apps/terminal/
├── TerminalActivity.kt     # Main terminal UI
├── UsbSerialManager.kt     # USB serial communication
├── TerminalSubApp.kt       # Subapp registration
└── TerminalInitializer.kt
```

## Features

### Terminal Display

- **Monospace font**: Proper terminal appearance
- **ANSI color support**: Full 256-color parsing
- **Directional indicators**:
  - `>>` prefix for sent commands (blue)
  - `--` prefix for system messages (gray)
  - No prefix for received data (light gray)
- **Auto-scroll**: Follows new output
- **Line buffering**: Properly handles `\r\n` line endings
- **10,000 line limit**: Prevents memory issues

### Device Connection

- **Auto-detection**: Lists available USB serial devices
- **Hot-plug support**: Detects connect/disconnect events
- **Permission handling**: Automatic USB permission requests
- **Driver support**: Works with common USB-serial chips via usb-serial-for-android

### Actions

- **Send**: Transmit commands with Enter key or send button
- **Clear**: Reset terminal history
- **Share**: Export terminal log as text
- **Refresh**: Re-scan for USB devices

## Key Components

### TerminalActivity

Main Compose screen containing:

- `TopAppBar` with refresh, share, and clear actions
- Device selection `DropdownMenu`
- Connect/Disconnect `Button`
- `LazyColumn` terminal display with `TerminalLineRow`
- `OutlinedTextField` for command input

### UsbSerialManager

Handles all USB serial operations:

```kotlin
interface Listener {
    fun onDataReceived(data: ByteArray)
    fun onConnectionStateChanged(state: ConnectionState)
    fun onError(message: String)
    fun onDevicesChanged(devices: List<UsbSerialDriver>)
}

enum class ConnectionState {
    DISCONNECTED,
    AWAITING_PERMISSION,
    CONNECTING,
    CONNECTED,
    ERROR
}
```

### ANSI Color Parsing

The `parseAnsi()` function supports:

- Standard colors (30-37, 40-47)
- Bright colors (90-97)
- 256-color mode (38;5;n, 48;5;n)
- Bold, italic, underline, dim styles

## Serial Settings

| Parameter | Value |
|-----------|-------|
| Baud Rate | 115200 |
| Data Bits | 8 |
| Stop Bits | 1 |
| Parity | None |
| Line Ending | `\r\n` |

## Dependencies

- Jetpack Compose (Material3)
- usb-serial-for-android (USB serial drivers)
- Material Icons