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)

4.8 KiB Raw Permalink Blame History