Android-KTag-Apps/subapp-bletool

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