Initial public release.

subapp-bletool/README.md

@@ -0,0 +1,120 @@
+# 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