Android-KTag-Apps/subapp-terminal

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:

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