BleDebugger

简体中文

BleDebugger is a modern Android BLE debugging tool built with Kotlin, Jetpack Compose, Hilt, and Kable. It helps developers scan nearby Bluetooth Low Energy devices, connect to peripherals, inspect GATT services, read and subscribe to characteristics, send packets in multiple payload formats, and review RX/TX logs from a focused mobile interface.

Scan	GATT	Log	Send	More

• BLE device scanning with name/MAC search, RSSI sorting, connectable-device filtering, unnamed-device filtering, and manufacturer hints.
• Guided connection flow with connection-state feedback and discovered GATT service loading.
• GATT tree browser for services and characteristics, including common SIG service and characteristic names.
• Characteristic actions for read, write, notify, and stop notification when supported by the characteristic properties.
• Packet composer with HEX, UTF-8, DEC, and Base64 payload formats.
• Quick-send snippets and repeat sending for common debugging workflows.
• RX/TX data log with pause, resume, clear, and configurable terminal/chat styles.
• App preferences for theme, accent color, density, signal display mode, log limits, and language.
• English and Simplified Chinese localization.

• Kotlin
• Jetpack Compose and Material 3
• AndroidX Navigation Compose
• Hilt dependency injection with KSP
• Kable BLE library
• Kotlin Coroutines and Flow
• DataStore Preferences
• JUnit and AndroidX test dependencies

• Android Studio with support for the configured Android Gradle Plugin.
• JDK compatible with the Android Gradle Plugin used by this project.
• Android SDK 36 for compilation.
• Android 7.0 or later device with Bluetooth Low Energy support.

Clone the repository:

git clone https://github.com/<owner>/BleDebugger.git
cd BleDebugger

Build the debug APK:

./gradlew assembleDebug

Run unit tests:

./gradlew test

Install the debug build on a connected Android device:

./gradlew installDebug

On Windows PowerShell, use .\gradlew.bat instead of ./gradlew.

BleDebugger requires Bluetooth permissions to scan and connect to BLE peripherals:

• Android 12 and later: BLUETOOTH_SCAN and BLUETOOTH_CONNECT.
• Android 11 and earlier: Bluetooth permissions plus location permissions required by the platform BLE scanning API.

The app declares BLE hardware support through android.hardware.bluetooth_le.

app/src/main/java/club/knifelf/ble/debugger
+-- data        # BLE, settings, locale, and log data implementations
+-- di          # Hilt modules
+-- domain      # Models and repository contracts
+-- ui          # Compose screens, navigation, components, and theme

The app follows a single-activity Compose architecture. UI screens are organized by feature, ViewModels expose immutable UI state, and the BLE implementation maps Kable APIs into domain-level models.

Contributions are welcome. For a clean review process:

1. Fork the repository and create a feature branch.
2. Keep changes focused and consistent with the existing Kotlin and Compose style.
3. Add or update tests for behavior changes when practical.
4. Run ./gradlew test before opening a pull request.
5. Open a pull request with a clear description, screenshots for UI changes, and any known limitations.

This project is released under the MIT License.

Before publishing, add a LICENSE file if you want GitHub to detect and display the license automatically.