Initial public release.

subapp-medic/README.md

@@ -0,0 +1,116 @@
+# KTag Medic Subapp
+
+A Jetpack Compose Android application for healing "tagged out" KTag devices via BLE advertising.
+
+## Overview
+
+The Medic app scans for KTag devices broadcasting their status via BLE. When a device reports zero health ("tagged out"), it appears in the list. Tapping a device "heals" it by broadcasting a Tag packet, which restores the device's health.
+
+## Architecture
+
+The app follows the **MVVM (Model-View-ViewModel)** pattern with Jetpack Compose for the UI layer.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    MedicActivity                        │
+│                   (Compose Host)                        │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────┐
+│                   MedicViewModel                        │
+│  • BLE scanning & advertising                           │
+│  • Device list management                               │
+│  • MQTT integration (KOTH possession)                   │
+│  • Auto-heal logic                                      │
+└─────────────────────┬───────────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────────┐
+│                    UI Layer                             │
+│  MedicScreen → KothStatusBar + LazyColumn[DeviceCard]   │
+└─────────────────────────────────────────────────────────┘
+```
+
+## File Structure
+
+```
+src/main/java/club/clubk/ktag/apps/medic/
+├── MedicActivity.kt        # Compose activity with permissions
+├── MedicViewModel.kt       # State management, BLE, MQTT
+├── DeviceModel.kt          # Device data class + AutoHealSetting enum
+├── ColorUtils.kt           # Color manipulation utilities
+├── MedicSubApp.kt          # Subapp registration
+├── MedicSettingsActivity.kt
+├── MedicInitializer.kt
+├── HexUtils.java           # Hex string conversion (kept as Java)
+├── ble/
+│   └── Packet.java         # BLE packet parsing/creation (kept as Java)
+├── mqtt/
+│   ├── KTagMQTTServer.java # MQTT client (kept as Java)
+│   └── KingOfTheHillEventListener.java
+└── ui/
+    ├── MedicScreen.kt      # Main screen composable
+    ├── DeviceCard.kt       # Device list item
+    ├── KothStatusBar.kt    # KOTH possession display
+    └── theme/
+        ├── Theme.kt
+        ├── Color.kt
+        └── Type.kt
+```
+
+## Key Components
+
+### MedicViewModel
+
+Manages all application state and business logic:
+
+- **BLE Scanning**: Listens for KTag Status packets, filters by health and RSSI
+- **Device List**: Maintains list of tagged-out devices with TTL-based expiration
+- **Healing**: Broadcasts Tag packets to restore device health
+- **Auto-Heal**: Automatically heals devices based on team color settings
+- **MQTT**: Subscribes to KOTH possession updates
+
+### DeviceModel
+
+Immutable data class representing a detected device:
+
+```kotlin
+data class DeviceModel(
+    val name: String,
+    val bleAddress: String,
+    val rssi: Int,
+    val color: Color,
+    val timeToLiveMs: Int
+)
+```
+
+### UI Composables
+
+| Composable | Purpose |
+|------------|---------|
+| `MedicScreen` | Main layout with status bar and device list |
+| `KothStatusBar` | Shows KOTH flag and possession text |
+| `DeviceCard` | Clickable card for each tagged-out device |
+
+## Features
+
+- **Device Detection**: Scans for KTag devices with zero health
+- **RSSI Filtering**: Only shows devices within configurable range
+- **One-Tap Healing**: Tap a device card to heal it
+- **Auto-Heal Modes**: None, Red team, Blue team, or All
+- **KOTH Integration**: Displays current hill possession via MQTT
+- **Visual Feedback**: Background color indicates auto-heal mode
+
+## Settings
+
+| Setting | Description |
+|---------|-------------|
+| `min_rssi` | Minimum RSSI threshold for device detection |
+| `auto_heal` | Auto-heal mode (0=None, 1=Red, 2=Blue, 3=All) |
+| `mqtt_*` | MQTT server configuration |
+
+## Dependencies
+
+- Jetpack Compose (Material3)
+- ViewModel + Compose integration
+- BLE (BluetoothLeScanner, BluetoothLeAdvertiser)
+- MQTT (Paho Android client)