简介这是一份面向Android开发者与Kotlin初学者的蓝牙通信实战源码包聚焦短距离无线通信在移动设备中的典型应用如设备发现、配对、数据传输等核心场景有效解决蓝牙API集成复杂、权限适配繁琐、多语言协同开发等实际问题。资源共326个文件压缩包大小24.36MB涵盖62个Kotlin源文件含协程与扩展函数实践、34个Java文件保障Java/Kotlin混合项目兼容、133个XML布局与配置文件定义UI与Manifest、17个AAR库含多个版本ppblutoothkit蓝牙SDK、14个SO本地库支撑底层蓝牙协议栈调用以及Gradle构建脚本、Markdown说明文档和PNG资源图等。已有423人学习下载适合希望掌握Kotlin现代化语法落地蓝牙开发、理解AAR/SO依赖集成机制、并快速复用模块化蓝牙能力的中初级开发者。1. 项目概述与核心价值最近在整理过往项目时翻出了一个基于Kotlin语言实现的Android蓝牙库示例程序。这个项目虽然不大但麻雀虽小五脏俱全它完整地封装了Android蓝牙特别是低功耗蓝牙BLE的核心操作流程并提供了一个清晰、可直接运行的Demo。对于正在学习Android蓝牙开发尤其是想用Kotlin和现代架构来构建稳定蓝牙功能的开发者来说这个源码或许能提供一个不错的起点。很多朋友在初次接触Android蓝牙API时都会被其繁琐的回调、状态管理和线程问题搞得头大这个示例程序正是试图解决这些痛点将混乱的API调用梳理成一条清晰的生命周期管线。这个设计源码的核心价值在于“示例”与“库”的结合。它不仅仅是一个演示某个单一功能比如扫描或连接的代码片段而是一个具备一定工程结构、考虑了实际开发中常见问题的微型框架。你可以直接将其中的蓝牙管理模块也就是“库”的部分抽取出来集成到你自己的App中快速获得蓝牙通信能力。同时配套的示例程序则像一份活的说明书展示了如何正确地使用这个库如何处理连接断开、数据读写、通知监听等完整场景。无论你是想学习Kotlin协程在异步IO操作中的最佳实践还是想了解如何用ViewModel和LiveData来优雅地管理蓝牙状态与UI的联动这个项目都能给你直观的答案。2. 整体架构设计与技术选型考量2.1 为何选择Kotlin与Clean Architecture思想这个项目坚定地使用Kotlin作为开发语言这不仅仅是追赶潮流。Kotlin的空安全特性、扩展函数以及协程对于蓝牙这种充斥着异步回调、可能随时为空的对象如BluetoothDevice的开发场景带来了革命性的简化。例如用协程的flow来处理蓝牙设备扫描结果流比传统的Handler或RxJava更直观也更符合“响应式”的数据驱动理念。在架构上项目没有采用庞杂的MVVM或MVI全家桶而是汲取了Clean Architecture的核心思想进行了适度的简化形成了“数据层-领域层-表现层”的三层结构。数据层负责与Android原生的BluetoothAdapter、BluetoothGatt等API直接对话处理最底层的操作和回调。领域层则包含了核心的业务逻辑实体和用例例如“连接设备”、“发送数据”等这里会封装具体的协程挂起函数将底层回调转化为更易于理解的同步或异步流操作。表现层则是Android的Activity/Fragment和ViewModel它们通过调用领域层的用例来驱动UI更新。注意这里没有盲目引入Repository模式因为对于蓝牙操作数据源相对单一就是系统蓝牙服务过度抽象反而增加复杂度。我们的原则是架构服务于清晰度而非教条。2.2 核心模块分解与职责界定整个项目源码可以清晰地划分为以下几个模块每个模块职责单一通过接口进行通信蓝牙管理器 (BluetoothManager)这是整个库的心脏。它是一个单例或通过依赖注入管理的对象负责蓝牙适配器的生命周期、全局的扫描控制、已连接设备的集中管理。它对外提供诸如startScan、stopScan、connectToDevice等高级API并内部处理Android系统蓝牙权限的申请和检查。设备连接与会话 (DeviceConnection)每个连接的蓝牙设备特别是BLE设备都会对应一个DeviceConnection对象。这个对象封装了BluetoothGatt连接管理着GATT服务的发现、特征值的读写、通知的启用与监听等。它将BluetoothGattCallback中繁杂的回调方法封装成更易用的StateFlow或Channel让上层可以轻松监听连接状态、服务发现结果和数据到达事件。数据协议解析器 (DataParser)蓝牙通信的核心是二进制数据ByteArray的交换。这个模块提供了一系列扩展函数和类用于处理常见的协议操作例如将Int、String转换为字节数组或从接收到的字节数组中解析出温度、电量等具体数值。这部分通常需要根据你实际连接的设备协议进行定制示例中给出了通用的框架和几个常用范例。UI示例模块 (Demo App)这是一个完整的Android应用模块包含扫描设备列表、设备详情、数据通信控制等界面。它严格遵循表现层模式ViewModel持有BluetoothManager的引用UI通过观察ViewModel暴露的LiveData或StateFlow来更新界面。这个模块最重要的价值是展示了如何将蓝牙的异步事件安全地绑定到UI线程。3. 核心实现细节与避坑指南3.1 蓝牙权限的现代化处理与动态申请从Android 6.0到Android 12蓝牙权限策略发生了多次重大变化。示例程序必须妥善处理这些兼容性问题。我们的策略是采用条件判断进行渐进式申请。// 在BluetoothManager初始化或扫描前检查 fun checkAndRequestPermissions(activity: Activity): Boolean { val permissionsNeeded mutableListOfString() // 基础蓝牙权限Android 12 需要区分 if (Build.VERSION.SDK_INT Build.VERSION_CODES.S) { if (ContextCompat.checkSelfPermission(activity, Manifest.permission.BLUETOOTH_SCAN) ! PackageManager.PERMISSION_GRANTED) { permissionsNeeded.add(Manifest.permission.BLUETOOTH_SCAN) } if (ContextCompat.checkSelfPermission(activity, Manifest.permission.BLUETOOTH_CONNECT) ! PackageManager.PERMISSION_GRANTED) { permissionsNeeded.add(Manifest.permission.BLUETOOTH_CONNECT) } } else { // 旧版本使用ACCESS_FINE_LOCATION进行设备发现 if (ContextCompat.checkSelfPermission(activity, Manifest.permission.ACCESS_FINE_LOCATION) ! PackageManager.PERMISSION_GRANTED) { permissionsNeeded.add(Manifest.permission.ACCESS_FINE_LOCATION) } } if (permissionsNeeded.isNotEmpty()) { // 触发动态申请流程建议在ViewModel或Fragment中处理回调 activity.requestPermissions(permissionsNeeded.toTypedArray(), REQUEST_CODE_BLUETOOTH_PERM) return false } return true }实操心得千万不要在Application或BluetoothManager构造函数中申请权限。权限申请必须在一个Activity或Fragment的上下文中触发并且结果回调需要在onRequestPermissionsResult中处理再通知回你的蓝牙管理模块。建议将权限状态也封装成一个Flow让UI组件可以响应其变化。3.2 使用协程与Flow优雅处理异步回调Android原生蓝牙API是典型的基于监听器的回调模型容易导致“回调地狱”。Kotlin协程的suspendCancellableCoroutine和callbackFlow是解决这个问题的利器。以扫描设备为例传统方式需要注册一个BroadcastReceiver或实现ScanCallback在回调中手动更新列表。我们用callbackFlow将其转化为一个Flowfun scanDevices(): FlowScanResult callbackFlow { val scanCallback object : ScanCallback() { override fun onScanResult(callbackType: Int, result: ScanResult) { trySend(result) // 将结果发送到flow } override fun onScanFailed(errorCode: Int) { close(ScanFailedException(errorCode)) // 发生错误时关闭flow } } val scanner bluetoothAdapter.bluetoothLeScanner val settings ScanSettings.Builder().setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY).build() scanner.startScan(null, settings, scanCallback) // 当flow收集被取消时如用户停止扫描执行清理 awaitClose { scanner.stopScan(scanCallback) } }在ViewModel中可以这样安全地收集扫描结果viewModelScope.launch { bluetoothManager.scanDevices() .catch { e - _scanError.value e.message } // 集中处理错误 .collect { scanResult - // 更新设备列表LiveData _deviceList.value currentList scanResult.device.toDeviceItem() } }注意事项callbackFlow内部必须调用awaitClose来注册清理逻辑这是保证资源如扫描在界面销毁或不再需要时能被正确释放的关键。否则会导致蓝牙扫描一直在后台运行严重消耗电量。3.3 设备连接与GATT操作的生命周期管理管理BluetoothGatt连接是BLE开发中最复杂的一环。一个核心原则是连接对象必须与UI或后台服务的生命周期绑定。示例程序中DeviceConnection类通常会被ViewModel持有并在ViewModel的onCleared()方法中主动断开连接和关闭Gatt客户端。连接过程同样被封装为挂起函数suspend fun connect(deviceAddress: String): ConnectionResult suspendCancellableCoroutine { cont - val device bluetoothAdapter.getRemoteDevice(deviceAddress) val gatt device.connectGatt(context, false, gattCallback) this.bluetoothGatt gatt // 在gattCallback的onConnectionStateChange中解析结果 connectionContinuation cont // 临时保存continuation // 设置超时防止设备无响应导致协程永远挂起 cont.invokeOnCancellation { gatt.close() } }在BluetoothGattCallback中override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) { val continuation connectionContinuation connectionContinuation null when (newState) { BluetoothProfile.STATE_CONNECTED - { continuation?.resume(ConnectionResult.Success) gatt.discoverServices() // 开始发现服务 } BluetoothProfile.STATE_DISCONNECTED - { continuation?.resume(ConnectionResult.Failure(Disconnected)) close() // 清理资源 } } }踩坑记录BluetoothGatt的很多操作如readCharacteristic,writeCharacteristic都是异步的并且结果在onCharacteristicRead/Write回调中返回。必须为每一次读写操作建立请求-响应的配对机制可以使用一个并发的Channel来传递结果避免在回调中直接更新UI或处理业务逻辑从而引发线程安全问题或状态混乱。4. 示例程序UI层与状态管理实战4.1 使用ViewModel与StateFlow驱动UI在示例程序的UI层我们严格遵循“单向数据流”的思想。BluetoothViewModel会暴露多个StateFlow来代表UI状态。class BluetoothViewModel(private val bluetoothManager: BluetoothManager) : ViewModel() { // UI状态 private val _scanState MutableStateFlowScanState(ScanState.Idle) val scanState: StateFlowScanState _scanState.asStateFlow() private val _connectedDevice MutableStateFlowDeviceConnection?(null) val connectedDevice: StateFlowDeviceConnection? _connectedDevice.asStateFlow() private val _messageLog MutableStateFlowListString(emptyList()) val messageLog: StateFlowListString _messageLog.asStateFlow() fun startScan() { viewModelScope.launch { _scanState.value ScanState.Scanning bluetoothManager.scanDevices() .onEach { scanResult - // 更新设备列表这里简化处理 } .catch { e - _scanState.value ScanState.Error(e.message ?: Unknown error) } .collect() // 扫描10秒后自动停止 delay(10000L) stopScan() } } fun stopScan() { bluetoothManager.stopScan() _scanState.value ScanState.Idle } }在Fragment或Compose函数中只需收集这些StateFlow// Compose 示例 Composable fun DeviceScanScreen(viewModel: BluetoothViewModel) { val scanState by viewModel.scanState.collectAsStateWithLifecycle() when (scanState) { is ScanState.Scanning - { /* 显示扫描中UI */ } is ScanState.Idle - { /* 显示空闲状态展示扫描按钮 */ } is ScanState.Error - { /* 显示错误提示 */ } } }技巧分享使用collectAsStateWithLifecycle()需要androidx.lifecycle:lifecycle-runtime-compose库来收集Flow可以确保UI只在活跃的生命周期内接收更新避免后台不必要的计算和可能的内存泄漏。这是开发Android应用的最佳实践。4.2 处理屏幕旋转与配置变更蓝牙连接是耗时操作且BluetoothGatt对象与系统资源紧密绑定。在屏幕旋转时默认情况下Activity/Fragment会重建如果处理不当会导致旧的连接未关闭新的连接又试图建立造成资源泄露和连接失败。我们的解决方案是ViewModel存活ViewModel在配置变更时不会销毁因此将BluetoothManager和DeviceConnection的核心持有放在ViewModel中。使用SavedStateHandle对于需要在进程死亡后恢复的数据如已连接设备的MAC地址将其保存在ViewModel的SavedStateHandle中。UI重建时重绑Fragment重建后通过观察ViewModel中的StateFlow重新将UI组件如按钮、显示列表绑定到现有的连接状态上而不是发起新的连接。class BluetoothViewModel( private val savedStateHandle: SavedStateHandle, private val bluetoothManager: BluetoothManager ) : ViewModel() { private val _connectedDeviceAddress savedStateHandle.getStateFlow(connected_addr, ) val connectedDeviceAddress: StateFlowString _connectedDeviceAddress fun restoreConnection() { viewModelScope.launch { val addr connectedDeviceAddress.value if (addr.isNotEmpty()) { // 尝试重新连接到保存地址的设备 connectToDevice(addr) } } } }5. 蓝牙通信中的数据协议处理与调试技巧5.1 通用数据编解码器实现蓝牙设备间传输的是原始的字节数组。示例程序中包含一个DataEncoder和DataDecoder工具类用于处理常见数据类型的转换。object BluetoothDataProcessor { // 将Short以小端字节序写入ByteArray fun writeShortToBytes(value: Short, byteArray: ByteArray, offset: Int 0) { byteArray[offset] (value.toInt() and 0xFF).toByte() byteArray[offset 1] ((value.toInt() shr 8) and 0xFF).toByte() } // 从小端字节序的ByteArray中读取Short fun readShortFromBytes(byteArray: ByteArray, offset: Int 0): Short { return ((byteArray[offset].toInt() and 0xFF) or ((byteArray[offset 1].toInt() and 0xFF) shl 8)).toShort() } // 解析常见的BLE标准服务数据如电池电量 fun parseBatteryLevel(data: ByteArray): Int { if (data.isEmpty()) return -1 return data[0].toInt() and 0xFF // 电量通常是0-100的单个字节 } }在实际项目中你需要根据设备厂商提供的《蓝牙通信协议文档》来实现特定的解析器。一个良好的实践是为每种设备或服务定义一个独立的Parser类。5.2 调试与日志记录策略蓝牙调试非常依赖日志。我们不应该依赖Log.d简单输出而是构建一个集中式的日志系统将蓝牙操作的所有关键节点扫描开始/停止、连接状态变化、服务发现、数据收发记录下来并能在UI上实时查看。class BluetoothLogger { private val _logEntries MutableSharedFlowLogEntry(replay 100) // 保留最近100条 val logEntries: SharedFlowLogEntry _logEntries.asSharedFlow() fun log(level: LogLevel, tag: String, message: String) { val entry LogEntry(System.currentTimeMillis(), level, tag, message) viewModelScope.launch { // 假设在ViewModel中 _logEntries.emit(entry) } // 同时打印到控制台 when (level) { LogLevel.ERROR - Log.e(tag, message) LogLevel.WARN - Log.w(tag, message) else - Log.d(tag, message) } } } // 在BluetoothManager各处关键点调用 bluetoothLogger.log(LogLevel.INFO, Connection, Attempting to connect to $deviceAddress)在示例程序的调试界面可以添加一个可展开的日志面板实时显示logEntries。当设备通信出现异常时这个面板是排查问题的第一手资料。排查技巧如果遇到设备连接后立刻断开首先检查日志中GATT的状态码onConnectionStateChange中的status参数。status 133是常见错误通常意味着设备端忙或连接参数问题可以尝试增加连接延迟或重试逻辑。另外确保在onServicesDiscovered回调成功之后再进行特征值的读写操作。6. 常见问题排查与性能优化实录6.1 连接不稳定与自动断开问题这是BLE开发中最常见的问题。除了前面提到的status 133还有以下原因和解决方案问题现象可能原因排查步骤与解决方案连接成功几秒后无故断开1. Android系统省电策略2. 未及时进行有效通信1. 在onCreate中获取PowerManager的WakeLock部分场景。2. 连接成功后尽快执行一次服务发现或读写操作让系统认为此连接是活跃的。3. 考虑使用BluetoothGatt.requestConnectionPriority(BluetoothGatt.CONNECTION_PRIORITY_HIGH)请求高连接间隔。连接非常缓慢或经常超时1. 环境干扰2. 设备端广播或连接参数不佳1. 换一个环境测试排除Wi-Fi、微波炉等2.4GHz干扰源。2. 扫描时使用ScanSettings.SCAN_MODE_LOW_LATENCY。3. 连接时可以尝试在connectGatt方法中设置autoConnect参数为true采用后台异步连接方式但这种方式连接事件回调时机不精确。只有特定品牌/型号手机有问题手机厂商蓝牙栈的兼容性问题这是硬伤通常需要收集日志与设备厂商共同排查。可以尝试在代码中为特定手机型号添加workaround比如调整重试次数、延长超时时间。6.2 数据传输速率慢与吞吐量优化BLE本身不是为高速传输设计的但通过一些优化可以提升效率使用“写操作无响应”模式对于不需要确认的数据如连续发送的传感器数据在writeCharacteristic时将writeType设置为BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE。这允许手机在不等设备端确认的情况下发送下一包数据大幅提升吞吐量。characteristic.writeType BluetoothGattCharacteristic.WRITE_TYPE_NO_RESPONSE bluetoothGatt?.writeCharacteristic(characteristic)但需注意设备端必须支持此模式且数据有丢失风险需要应用层协议保证可靠性。调整连接参数通过BluetoothGatt.requestConnectionPriority()可以请求更快的连接间隔。CONNECTION_PRIORITY_HIGH对应最小的连接间隔如7.5ms-15ms但这会显著增加功耗需权衡使用。数据分包与粘包处理BLE单包数据长度有限通常是20字节。发送长数据时需要在应用层实现分包。接收时设备端可能快速发送多个包需要在onCharacteristicChanged回调中处理好数据包的拼接粘包问题。示例程序中应提供一个简单的帧头长度数据校验的封装示例。6.3 后台运行与功耗控制如果App需要在后台维持蓝牙连接如智能手环数据同步会面临严格的系统限制。使用前台服务在AndroidManifest.xml中声明BLUETOOTH_CONNECT和BLUETOOTH_SCAN权限并启动一个带有FOREGROUND_SERVICE_TYPE_CONNECTED_DEVICE类型的前台服务。这是Android 12后台维持连接的必要条件。优化扫描策略后台扫描必须使用ScanSettings.SCAN_MODE_LOW_POWER模式并设置合理的扫描间隔和窗口例如每30秒扫描5秒。使用WorkManager进行定时任务对于非实时性的数据同步如每天同步一次健康数据使用WorkManager安排定时任务在任务执行期间建立连接、同步数据、然后立即断开而不是维持长连接这是最省电的方式。终极建议在正式发布前务必使用Android Studio的Profiler工具监控App的功耗Energy Profiler。观察蓝牙模块活动时CPU和无线射频Radio的耗电曲线。一个设计良好的蓝牙应用在空闲时应几乎不产生额外功耗。本文还有配套的精品资源点击获取
