BleKotlin

Android BLE (Bluetooth Low Energy) 工具库，基于 Kotlin + Jetpack Compose 封装，提供开箱即用的蓝牙扫描、连接、服务发现、特性读写与通知订阅功能。

功能特性

• ✅ 环境检查 — 权限、蓝牙开关、定位服务一键检测
• 🔍 BLE 扫描 — 支持自定义扫描时长，自动超时停止
• 🔗 GATT 连接 — 支持主动连接与已连接设备自动附着
• 📡 特性操作 — 支持 Read / Write / WriteNoResp / Notify / Indicate
• 🎨 Compose UI — 基于 Material Design 3，自适应明暗模式
• 📱 Demo App — 完整示例，可直接运行体验

环境要求

项目	要求
minSdk	24 (Android 7.0)
compileSdk	36
Kotlin	2.0+
Jetpack Compose	BOM 2025.06.00

集成方式

1. 添加 JitPack 仓库

在 settings.gradle.kts 中添加：

dependencyResolutionManagement { 
  repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }}

2. 添加依赖

dependencies { implementation("com.github.guaju:BleKotlin:v1.0.0") }

快速开始

环境检查

val check = rememberBleCheck(
      onAllReady = { /* 所有条件满足，开始扫描 / },
      onPermissionDenied = { / 权限被拒绝 / },
      onBluetoothDisabled = { / 蓝牙未开启 / },
      onLocationDisabled = { / 定位未开启 */ } )
Button(onClick = { check() }) {
     Text("开始扫描") }

扫描设备

val devices = remember { mutableStateListOf<BleDevice>() }
BleScannerHelper.startScan(
      context = context,
      onDeviceFound = { device -> if (devices.none { it.address == device.address }) { devices.add(device) } },
      scanDurationMs = 10_000L,
      onFinished = { /* 扫描结束 */ }
)
// 手动停止扫描
BleScannerHelper.stopScan()

连接设备

// 方式一：主动连接
BleConnectionHelper.connect(
      context = context,
      device = bluetoothDevice,
      onConnected = { /* 连接成功，服务已发现 / },
      onDisconnected = { / 连接断开 / },
      onConnectionFailed = { / 连接失败 */ } )
// 方式二：附着到已连接设备
val device = BleConnectionHelper.getConnectedBleDevice(context)
if (device != null) {
      BleConnectionHelper.attachToDevice(
        context = context,
        onServicesReady = { /* 服务发现完成 / },
        onDisconnected = { / 断开 */ } )
}

读取特性

val success = BleConnectionHelper.readCharacteristic(serviceUuid, characteristicUuid)
// 监听读取结果 
val value = BleConnectionHelper.characteristicValue // ByteArray? 
val count = BleConnectionHelper.readCount // 读取次数，可作为 LaunchedEffect 的 key

写入特性

val data = byteArrayOf(0x01, 0x02, 0x03)
val success = BleConnectionHelper.writeCharacteristic(serviceUuid, characteristicUuid, data)

订阅通知 (Notify / Indicate)

// 订阅
BleConnectionHelper.enableNotify(serviceUuid, characteristicUuid)
// 监听推送数据
val notifyList = BleConnectionHelper.notifyDataList // List<Pair<String, ByteArray>>
// 取消订阅
BleConnectionHelper.disableNotify(serviceUuid, characteristicUuid)

断开连接

BleConnectionHelper.disconnect()

核心类说明

类名	说明
BleCheckHelper	环境检查：权限、蓝牙、定位
BleScannerHelper	BLE 扫描，支持超时自动停止
BleConnectionHelper	GATT 连接管理、特性读写、通知订阅
rememberBleCheck	Compose 环境检查辅助函数
BleDevice	设备数据类 (name, address, rssi)
ServiceInfo	服务信息 (uuid, isPrimary, characteristics)
CharacteristicInfo	特性信息 (uuid, properties, value)
OperationRecord	操作记录 (timestamp, operation, dataHex, success)

权限声明

在 AndroidManifest.xml 中添加：

<!-- Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- Android 11 及以下 -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Demo App

项目包含一个完整的 Demo 应用（app 模块），演示了：

• 蓝牙扫描与设备列表
• 设备连接与断开
• 服务/特性浏览
• Read / Write / Notify 操作
• HEX 数据格式化输入
• 操作记录展示

克隆项目后可直接运行体验。

License

Copyright 2026 guaju Licensed under the Apache License, Version 2.0 (the "License");