Android-KTag-Apps/subapp-medic

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:

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)