# KTag BLE Tool Subapp

A Jetpack Compose Android application for testing and debugging KTag BLE protocol packets.

## Overview

The BLE Tool provides two main functions:

1. **Advertiser**: Craft and broadcast custom KTag BLE advertisement packets
2. **Scanner**: Scan for and decode KTag devices broadcasting status packets

This tool is essential for development, testing, and debugging KTag devices and the protocol specification.

## Architecture

The app uses a simple activity-based architecture with Compose UI.

```
┌─────────────────────────────────────────────────────────┐
│                   BleToolActivity                       │
│              (Advertiser Tab - Main)                    │
│  • Byte grid editor for packet construction             │
│  • Preset packet templates                              │
│  • Start/Stop broadcasting                              │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                   ScannerActivity                       │
│              (Scanner Tab)                              │
│  • BLE scanning for KTag packets                        │
│  • Real-time packet decoding                            │
│  • Device list with parsed fields                       │
└─────────────────────────────────────────────────────────┘
```

## File Structure

```
src/main/java/club/clubk/ktag/apps/bletool/
├── BleToolActivity.kt      # Main advertiser screen
├── ScannerActivity.kt      # Scanner screen + packet parsing
├── AdvertisementPreset.kt  # Preset packet definitions
├── ByteCellData.kt         # Byte cell display data
├── PacketFieldUtils.kt     # Field descriptions & colors
├── BleToolSubApp.kt        # Subapp registration
├── BleToolInitializer.kt
└── ui/                     # (Composables in main files)
```

## Features

### Advertiser

- **31-byte packet editor**: Visual grid showing all packet bytes
- **Header protection**: First 8 bytes (KTag header) are read-only
- **Hex editing**: Tap any byte to edit its value
- **Field highlighting**: Color-coded fields based on packet type
- **Presets**: Quick-load common packet types:
  - Instigate Game (0x01)
  - Event (0x02)
  - Tag (0x03)
  - Console (0x04)
  - Status (0x05)
  - Parameters (0x06)
  - Hello (0x07)

### Scanner

- **KTag filtering**: Only shows devices with valid KTag packets
- **Real-time updates**: Live packet decoding as devices broadcast
- **Full packet parsing**: Decodes all 7 packet types with field details
- **Device tracking**: Groups packets by device address

## Packet Types

| Type | Name | Key Fields |
|------|------|------------|
| 0x01 | Instigate Game | Game length, Countdown time |
| 0x02 | Event | Target address, Event ID/Data |
| 0x03 | Tag | Team, Player, Damage, Color, Target |
| 0x04 | Console | ASCII message string |
| 0x05 | Status | Team, Health, Colors, State |
| 0x06 | Parameters | Target, Key/Value pairs |
| 0x07 | Hello | Version, Device type, Name |

## KTag Packet Structure

All KTag packets follow this structure:

```
Byte 0-3:  "KTag" magic bytes (0x4B 0x54 0x61 0x67)
Byte 4:    Packet type (0x01-0x07)
Byte 5:    Event number (incrementing)
Byte 6-26: Type-specific payload
```

## Key Components

### BleAdvertiserScreen

Interactive packet editor with:

- `LazyVerticalGrid` of `ByteCell` components
- `ExposedDropdownMenu` for preset selection
- `ByteEditor` for hex value input
- Start/Stop broadcast button

### ScannerScreen

Device scanner with:

- `LazyColumn` of `PacketCard` components
- Sealed class hierarchy for packet types
- `parseKTagPacket()` for decoding raw bytes

## Dependencies

- Jetpack Compose (Material3)
- BLE (BluetoothLeScanner, BluetoothLeAdvertiser)
- Material Icons