Initial public release.

subapp-terminal/README.md

@@ -0,0 +1,132 @@
+# 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