Android BLE调试助手从零开发实战：GATT解析与MTU协商

简介一款面向蓝牙开发者的BLE调试助手Android源码基于蓝牙4.0技术可完成设备扫描、连接、服务与特性值查看、读写操作等全流程调试。源码包含完整的Android工程共52个文件以java源码、class编译文件、xml配置与布局、png图标资源为主另有可安装的apk与调试所需的dex、properties等文件整体仅172KB结构紧凑适合初学者直接导入工程分析或二次开发。该工程目录层级规范源码注释清晰便于按模块研读。已有3959人学习下载。通过阅读源码可深入理解BLE协议栈调用、GATT服务发现、特征值读写与蓝牙事件处理等核心逻辑也可参考其界面布局与扫描连接流程快速搭建自己的蓝牙调试工具或物联网传感采集应用。这份资源用实际代码演示了蓝牙低功耗通信的关键环节对学习Android蓝牙开发与低功耗嵌入式联调都有直接帮助。 做蓝牙开发这几年最烦的事情就是在真机上调试BLE设备时永远少一个趁手的工具。现成的调试助手要么全是广告要么功能被砍得七零八落要么不支持自定义过滤规则遇到特殊协议只能干瞪眼。后来我干脆花了一个多月业余时间从零写了一个“蓝牙BLE调试助手”软件源码把项目开源到仓库里。今天就跟大家聊聊这个项目是怎么做出来的核心模块怎么组织以及我在开发过程中踩过的一堆坑。这篇文章适合三类人正在学习BLE开发的嵌入式工程师、想给自己做工具箱的Android开发以及日常要和蓝牙外设打交道的硬件测试同学。1. 项目定位与核心需求拆解1.1 为什么非要自己造轮子市面上不缺BLE调试工具Google Play和国内应用市场一搜一大把但实际用下来总有各种别扭。有的工具只支持经典蓝牙扫描对BLE 4.0/5.0的广播包解析不完整有的把GATT服务列表展示得很好却没法手动写特征值还有的工具连日志导出功能都没有出了问题只能截屏靠肉眼比对。更关键的是很多工具是闭源的我没办法按自己的测试流程去改。于是“自己写一个”这个念头越来越强烈索性动手。自己的调试助手至少要做到三点第一能完整看到扫描结果包括设备名称、MAC地址、RSSI和广播包数据第二能连接设备并完整枚举出所有主服务、从服务和特征值属性第三能方便地读写特征值、订阅通知并且全程记录日志。再加一些扩展功能比如保存设备列表、自定义UUID、数据导出基本上就是一个能用的调试平台了。这个定位也决定了后续代码架构的方向尽量简单、模块清晰、方便二次开发。1.2 功能清单与优先级排序我一开始就把功能拆成必做、选做和扩展三类避免在开发里跑偏。优先级功能模块说明P0BLE扫描支持多设备结果展示、RSSI刷新、名称/MAC过滤P0GATT连接/断开管理连接状态处理断线重连P0服务与特征枚举递归展示Service、Characteristic、DescriptorP0特征值读写支持单字节、Hex、ASCII、UTF-8输入P0通知/指示订阅一键订阅实时接收设备上行数据P1MTU协商显示当前MTU并主动请求更新P1日志记录与导出时间戳、收发方向、数据内容可导出CSVP2经典蓝牙扫描扩展支持BR/EDR设备发现方便调试双模设备P2自动化脚本记录并回放一组交互操作用于产测开发时我严格按P0先做把核心链路跑通后再补P1和P2。事实证明这个顺序帮我省了不少重构时间尤其是日志模块虽然排在后半段但在调试其他功能时给了很多关键线索。2. 技术选型与整体架构设计2.1 为什么选Android Kotlin而不是Flutter/React Native项目一开始我也纠结过跨平台方案毕竟很多同事用iPhone看起来Flutter一劳永逸。但深入了解后我放弃了。Flutter生态里的BLE插件确实不少比如flutter_blue_plus、flutter_reactive_ble但它们的封装层很厚一旦遇到国产ROM的系统BLE行为差异你根本不知道是插件问题还是系统问题排障成本极高。Android原生方案用官方android.bluetooth.le包代码虽然啰嗦一些但每一层调用都自己控制出问题时能直接看到系统日志这对调试工具来说太重要了。Kotlin的好处不用多说协程处理异步回调、数据类和密封类表达状态非常舒服。我的目标是做一个源码开放、学习门槛低的项目所以尽量减少了第三方依赖UI层也没引入重型框架直接用Jetpack Compose编写。这样大家clone下来就能跑不需要额外配置一堆复杂环境。2.2 源码目录结构和模块边界一个开源调试工具最怕代码全堆在Activity里后面根本没法看。我用分层思想把目录分成三块data负责所有蓝牙硬件操作ui负责界面和交互util放Hex转换、日志格式化等工具类。app/src/main/java/com/example/bthelper/ ├── data/ │ ├── BleScanner.kt // 封装扫描 │ ├── BleGattClient.kt // 封装连接、服务发现、读写 │ ├── BleDeviceInfo.kt // 设备信息数据类 │ └── GattParseUtil.kt // GATT解析工具 ├── ui/ │ ├── scan/ │ │ ├── ScanScreen.kt │ │ └── ScanViewModel.kt │ ├── device/ │ │ ├── DeviceScreen.kt │ │ ├── CharacteristicSheet.kt │ │ └── DeviceViewModel.kt │ └── log/ │ └── LogScreen.kt └── util/ ├── HexUtils.kt └── TimeUtils.kt这样的分层让每个类干一件事调试时我可以单独替换扫描实现或GATT实现。比如早期我写了一个基于BluetoothAdapter.startLeScan的老版本后来切换到BluetoothLeScanner只改了BleScanner.kt这个文件UI完全不用动。这就是模块化带来的好处。2.3 必须吃透的BLE协议层概念写调试助手之前我建议先把几个核心协议概念弄明白不然很容易写出“能用但很难用”的工具。GATT是BLE应用层的通信框架设备被抽象成服务Service、特征Characteristic、描述符Descriptor三层。特征值就是实际读写的数据点描述符通常是配置通知开关的CCCClient Characteristic Configuration Descriptor0x2902。调试工具的核心工作就是把这些层级完整展示出来并允许用户操作。MTU是另一个关键参数。默认MTU是23字节扣掉3字节的LL层头实际一次最多传20字节用户数据。很多传感器往手机上报大数据时如果MTU不协商到247字节会导致数据被截断。代码里需要主动调用requestMtu然后在回调里记录协商后的真实值。调试助手如果不提供这个能力排查“数据不完整”问题时会非常痛苦。3. 源码实现中的核心细节3.1 扫描模块与权限处理扫描是BLE调试的第一步权限没处理好的话一上来就崩。Android 12API 31以后蓝牙权限分得更细BLUETOOTH_SCAN管扫描BLUETOOTH_CONNECT管连接另外在部分手机上还需要ACCESS_FINE_LOCATION才能拿到扫描结果。我在ScanScreen里同时判断这几个权限并用rememberLauncherForActivityResult请求。扫描的核心代码我用BluetoothLeScanner实现关键点是设置ScanSettings时的回调模式。默认CALLBACK_TYPE_FIRST_MATCH只会回调一次做调试工具应该用CALLBACK_TYPE_ALL_MATCHES来持续刷新RSSI才能让用户看到设备信号强度的变化趋势。同时扫描间隔SCAN_MODE_LOW_LATENCY虽然费电但调试场景下实时性优先。val settings ScanSettings.Builder() .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY) .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES) .build() scanner.startScan(filters, settings, scanCallback)3.2 GATT连接与重连策略连接部分最容易踩坑的是BluetoothGatt实例被系统回收。很多人直接在onScanResult里写gatt device.connectGatt(context, false, callback)看起来没问题但如果在回调还没触发时用户退出了页面gatt局部变量被回收系统会认为连接不再需要直接断开。我踩过几次之后统一用ApplicationContext和成员变量保存gatt并且在连接前取消之前未释放的旧连接。另外autoConnect参数在调试工具里我习惯设为false这样发起连接时会更快尤其是在距离较近时重连操作再改用true走系统后台广播唤醒配合指数退避策略不会频繁唤醒蓝牙栈。连接状态的管理用sealed class来描述比如Idle、Scanning、Connecting、Connected、Disconnected和Error。这样界面层只需要观察状态变化避免在Activity里写一堆if/else判断。3.3 服务发现与特征值解析连接成功后GATT回调里会触发onServicesDiscovered。我在这里把所有服务和特征值解析成树状列表供DeviceScreen展示。关于UUID我用一个HashMap映射常见服务比如0x180F代表电池服务、0x180A代表设备信息服务这样界面里可以显示“Battery”、“Device Info”等友好名称而不是一长串UUID。对于未知服务就显示原始UUID。特征值属性决定哪些操作可用。读取是PROPERTY_READ写入分为PROPERTY_WRITE和PROPERTY_WRITE_NO_RESPONSE两种通知是PROPERTY_NOTIFY。我在每个特征行里动态生成按钮有读权限的显示“读取”有写权限的显示“写入”有通知权限的显示“通知”。这个细节能极大提升使用体验避免用户对着只读特征瞎点。3.4 特征值读写与通知订阅写入数据时用户可以在输入框里选择Hex还是字符串。十六进制输入要自己做非法校验不然一个“GG”可能被解析成GG然后崩溃。我的HexUtils里做了严格过滤只有0-9A-Fa-f且长度为偶数时才允许转换。写特征值有一个容易忽略的地方BluetoothGattCharacteristic.setValue()要求先设置好writeType再调用writeCharacteristic。如果你把长数据一次性塞给默认的writeType系统可能按单包发送导致设备端只收到前20字节。调试工具里我应该把“writeType”也暴露出来让用户自己选择“带回执写入”还是“无回执写入”这样测试不同从机行为时更灵活。订阅通知的流程是调用setCharacteristicNotification(characteristic, true)开启本地通知找到对应的CCC描述符0x2902写入\x01\x00表示开启通知写入\x02\x00表示开启指示在onCharacteristicChanged回调里接收数据。很多新手第二点容易漏掉结果通知永远收不到。我在源码里做了自动补全——只要用户点击“订阅通知”就自动检查CCC描述符并写入正确的值。3.5 日志记录与导出日志模块看似简单却是整个工具里最重要的部分之一。我把日志分为三类系统事件连接、断连、MTU变更、错误、发送数据、接收数据。每条日志都带毫秒级时间戳、设备地址、方向、数据类型和内容。导出功能用CSV文件这样可以用Excel直接打开分析。实际测试中发现连续收大量数据时如果在主线程刷新UI列表会卡顿甚至ANR所以我把日志存储放在Room数据库里界面通过Paging分页加载。这样一来即使设备每秒上报100条数据App也能保持流畅。4. 实战踩坑与排查技巧4.1 国产ROM的扫描兼容性问题我最开始用小米手机测试扫描结果非常不稳定经常需要点好几遍“开始扫描”才能出设备。后来发现是定位权限没给配合定位服务也没开。小米、华为、OPPO等系统在蓝牙扫描时强依赖定位服务不是Android原生要求但这些定制ROM就是这么做。解决方法是在App启动时引导用户开启定位服务并且请求ACCESS_FINE_LOCATION不然后果不是崩溃而是“扫不出设备”排查起来更隐蔽。另外扫描回调里不要做耗时操作比如更新UI列表里的所有Item。扫描到几十个设备时每台都会回调一次若在主线程里跑重量级操作很快会掉帧。我在ScanViewModel里用Debounce合并更新或者只更新新增/移除的设备性能提升非常明显。4.2 连接后立即断开的排查步骤这个问题的出现频率在我做测试的几个月里排名第一。常见的两个原因第一BluetoothGatt对象被GC回收。Kotlin里如果在回调内使用局部变量函数结束后对象失去引用系统底层可能断开。解决办法是全局持有gatt对象并且用applicationContext来获取BluetoothManager。第二连接参数不匹配。有些老设备的从机连接间隔设置过短Android在onConnectionStateChange里收到133错误GATT_ERROR。我遇到这个问题时会先用官方调试工具排查是否是设备问题再用自己的工具尝试连接。如果确定是连接参数问题就需要调整设备端的连接间隔而不是在App端硬扛。4.3 MTU协商不起作用的情况requestMtu(247)并不保证一定成功。有的低功耗蓝牙从机芯片不支持大MTU协商失败后会停留在23字节。我发现某些Android手机即使协商到247后续写数据如果不做分包仍然会失败。所以在调试工具里发送长数据时我会做一个分包传输的选项按当前MTU-3字节自动拆分并在每包之间加10~20ms延时避免缓冲区溢出。这个功能对固件开发和产测非常有帮助。另外iOS对MTU的协商策略与Android不同如果你在Android调试时习惯一次写200字节换到iOS上可能会发现数据丢失。iOS通常会把最大写入长度限制得比较保守建议统一在工具里写一个“当前MTU自适应”的逻辑。4.4 iOS连接参数规范与Android的差异这项虽然我的项目是Android应用但测试时常需要和iOS端的同事一起联调。BLE设备的连接参数是核心问题。iOS对从机的连接参数要求更严格常见规范是连接间隔在30ms到50ms之间从机延迟尽量为0超时时间要大于6倍连接间隔。如果设备固件设置的连接间隔过小iOS可能直接拒绝连接或者是连接后立刻断开。调试助手如果能显示当前连接参数就能快速判断是设备参数问题还是手机兼容性问题。我的工具里在连接成功后会主动读取当前的连接参数并尝试用requestConnectionPriority来调整。类似这样的小细节很多现成的调试工具都不具备。4.5 善用RSSI与广播包日志调试BLE很多问题不需要连上设备就能判断。比如设备不在广播、广播间隔太长、信号太弱。我在扫描界面不仅显示RSSI还把广播包原始Hex数据展示出来。这样设备广播里的名称、UUID、厂商自定义数据都能一目了然。某次排查“手机搜索不到设备”的问题时我发现设备广播名是乱码导致系统的名称过滤失效其实设备一直在广播。如果没有广播包日志这个问题很难定位。5. 可扩展场景与源码复用5.1 对接ESP32等嵌入式设备这套调试助手源码可以直接用来测试ESP32的BLE服务。我在源码里留了“自定义UUID”功能你可以把ESP32代码里的UUID直接填进去工具会自动解析服务名称和特征列表。对于跑ESP-IDF或Arduino开发环境的同学这套工具基本是零成本上手。ESP32设备开发时会遇到一个典型问题广播包里的设备名称过长导致扫描不到。此时我的工具里可以切换成显示所有设备忽略名称过滤通过MAC地址或广播UUID来识别目标。这种灵活度是商业工具很少提供的。5.2 从BLE扩展到经典蓝牙很多物联网设备是双模蓝牙比如同时支持BLE与经典蓝牙的音频模块。我的调试工具目前以BLE为主但架构上预留了经典蓝牙扫描接口。实测下来Android对经典蓝牙的扫描权限与BLE是独立的要额外请求BLUETOOTH_ADMIN并处理BondStateChanged。另外Android 14以后对BLE和经典蓝牙的Profile访问限制越来越严格比如部分Profile如OPP被禁用如果做经典蓝牙工具需要关注系统版本兼容。源码里我把这一层设计成独立模块等有时间再把A2DP、HFP的调试功能补充进去。5.3 脚本自动化与产测联动我后续计划做的一个方向是“脚本录制回放”。在调试模式下用户操作的所有读写和订阅动作都会被记录下来可以导出成JSON脚本再通过App一键回放。这样产线测试人员不需要懂协议只需要拿着手机点开始就能自动完成一系列功能检查。这个功能我在自己的工具里已经写了最小原型源码里的LogRepository设计成了可插拔的数据源正是为后续脚本引擎准备的。如果你也有硬件测试需求可以在这个源码基础上继续扩展不一定非要自己从零开始。我个人在实际使用中最大的体会是调试工具不是做得越复杂越好而是要能快速定位问题。有时候看半天代码不如看一页日志日志格式清晰、模块边界明确比颜色鲜艳的UI更有用。现在这个源码已经陪我度过了好几个项目的联调阶段每次遇到奇怪的蓝牙问题我第一个打开的不是厂商工具而是自己写的这个调试助手。最后再分享一个小技巧如果你也准备开发类似工具一定要把日志和MTU协商这两个功能放在优先级最前面它们会在后面所有调试中反复救你。本文还有配套的精品资源点击获取