企业官网建设流程全解析

简介：面向Android蓝牙4.0开发者的官方BLE示例工程，以安卓开发者官网的Bluetooth LE指南为蓝本整理，完整演示设备扫描（scan）、连接与断开（connection/disconnect）、服务发现（discover service）以及UUID读写操作等关键流程，适用于刚接触蓝牙低功耗通信的移动开发者，也可作为已有项目快速集成BLE功能的参考模板。压缩包共70个文件，包含26个class、15个xml、7个java，并附jar库、APK成品、项目配置与缓存文件，整体仅1.34MB；从目录结构可区分src源码、res资源、gen生成文件与bin输出，方便直接导入开发环境对照学习。已有523人学习下载。通过这个demo可直观理解BLE的回调机制和GATT服务交互逻辑，降低环境搭建与API调用的门槛，帮助读者绕过常见坑点，快速跑通扫描、连接与数据交互流程，是一份轻量而完整的入门实战资料。

1. 项目概述

1.1 核心需求解析

做Android蓝牙开发，几乎所有人都会先接触到官方提供的BLE demo。这套demo托管在Android官方示例代码仓库中，项目名叫BluetoothLeGatt，涵盖了BLE开发中最核心的完整链路：设备扫描、设备连接、发现服务、读写特征值、接收通知。我当年刚接触BLE时就是靠啃这套demo入门的，前前后后把它翻来覆去改过好几遍，对它的评价是：基础功能都有，但直接搬到生产环境是不够用的。这篇文章把整套demo从环境准备到位运行到关键代码拆解，讲一遍我的实操经验，包括那些官方注释里没写清楚、你得踩几次坑才能总结出来的东西。

这个demo适合谁看？刚接触BLE开发、想搞清楚Android手机和外设之间是怎么通信的，或者已经在看demo但有些地方没看明白的同学。如果你需要BLE设备做OTA升级、大数据传输这类场景，这篇也会涉及相关的MTU和分包策略，但核心还是从demo出发把基础链路走通。

1.2 demo能做到什么

先给一个直观认识。BluetoothLeGatt实现了这些功能：

• 扫描周围的BLE外设，展示设备名、MAC地址、信号强度
• 连接指定设备，并自动发现GATT服务
• 列出设备支持的所有Service、Characteristic、Descriptor
• 读取Characteristic的值，支持十六进制和ASCII格式显示
• 写入数据到Characteristic，支持带响应和不带响应两种方式
• 接收设备主动发送的Notification通知

基本上，BLE开发里你能碰到的常规操作它都覆盖了。搞明白这套代码的来龙去脉，你再去写实际项目，不管是智能家居控制还是健康设备数据采集，思路都会清晰很多。

2. 准备工作与关键技术背景

2.1 搞清楚BLE和经典蓝牙的区别

先说点基础背景，很多新手在这个地方容易犯迷糊。BLE全称Bluetooth Low Energy，低功耗蓝牙，Android从API 18（Android 4.3）开始支持。它和经典蓝牙（BR/EDR）最大的区别在于：BLE不是简单地把数据传得更省电，而是整个协议栈都重新设计了。经典蓝牙支持持续的流式传输，比如蓝牙音箱播放音乐；BLE则在大部分时间处于睡眠状态，只在需要的时候快速唤醒、发几个字节、再睡过去，因此非常适合电池供电的传感器设备。

两者的另一个关键区别在于通信模型。经典蓝牙建立的是RFCOMM通道，你可以在上面跑socket，像用TCP一样；BLE则是基于GATT（Generic Attribute Profile）的，数据以Attribute为单位组织，一个Attribute包含UUID、属性、值。设备间通信就是你读写这些Attribute，设备主动推送数据则是通过Notification或Indication机制。这也是为什么看BLE的demo代码，你会发现它跟传统的蓝牙socket编程完全不是一个套路。

2.2 硬件与软件环境准备

跑这个demo之前，你得有一个支持BLE的Android手机，Android 5.0以上的系统都行。不需要额外买硬件外设，用手机模拟BLE外设也行，但最方便的还是搞一个真实的BLE设备。我常用的是一个Nordic开发板，或者也可以直接用另一台手机配合nRF Connect这个App模拟外设，不过实际调试下来你会发现，真机外设能暴露更多网络时序相关的问题。

环境方面，需要准备：

• Android Studio，推荐用较新的稳定版
• SDK版本，官方demo最新的代码要求API 30以上，但实际编译时把targetSdk和compileSdk调成当前SDK版本即可，minSdk保持API 18就能兼容老设备
• 一台有蓝牙模块的开发手机

2.3 Gradle配置常见坑

从GitHub拉下BluetoothLeGatt工程后，第一步是Gradle同步。这里大概率会遇到依赖下载慢、SDK版本不匹配的问题。GitHub官方仓库使用的是Android Gradle Plugin较新的版本，如果你本地的Gradle版本对不上，会直接报错。

我的建议是把build.gradle里这几个版本号统一改成自己本地环境可用的。拿我的配置举例：

android { compileSdk 34 defaultConfig { applicationId "com.example.bluetoothlegatt" minSdk 21 targetSdk 34 versionCode 1 versionName "1.0" } }

注意Android 12（API 31）之后有个比较大的变化：如果你把targetSdk升到31以上，应用中需要显式声明BLUETOOTH_SCAN、BLUETOOTH_CONNECT这两个运行时权限，否则在真机上会直接崩溃或者扫描不到设备。原生demo里给出的权限声明只覆盖了API 30以下的老权限方式，这部分需要自己改。

3. 核心代码逐段拆解

3.1 权限声明：不只是加两行配置

先来看最容易被忽略的权限部分。官方demo在AndroidManifest.xml里声明了这些权限：

<uses-permission android:name="android.permission.BLUETOOTH" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

如果你的app运行在Android 12以上，还需要增加：

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

补充一点，如果你只是扫描广播包而不主动连接设备，可以用neverForLocation标记来避免请求定位权限，但要特别注意设备是否在广播包里携带了可解析的私有地址或者厂商自定义数据，这些在Google的政策里被认定为可能推断位置信息，所以Play商店审核时对这个标记的审查比较严格。

实际开发中的权限处理是这样的：定位权限（ACCESS_FINE_LOCATION）是运行时权限，必须在代码里动态申请，用户拒绝之后扫描功能就无法正常工作。BLUETOOTH_SCAN和BLUETOOTH_CONNECT同样需要在代码里通过requestPermissions动态申请，并且要注意Android 12以上一个很烦人的点是：用户在系统设置里关掉“附近设备”权限后，你的app不会收到crash提示，而是静默地拿不到扫描结果。这时候可以通过ActivityResultContracts.RequestMultiplePermissions一次性把几个权限都申请掉。

以下是我常用的权限检查写法：

private fun checkPermissions(): Boolean { val requiredPermissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { arrayOf( Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT, Manifest.permission.ACCESS_FINE_LOCATION ) } else { arrayOf( Manifest.permission.ACCESS_FINE_LOCATION ) } val notGranted = requiredPermissions.filter { ContextCompat.checkSelfPermission(this, it) != PackageManager.PERMISSION_GRANTED } if (notGranted.isNotEmpty()) { ActivityCompat.requestPermissions(this, notGranted.toTypedArray(), REQUEST_PERMISSION_CODE) return false } return true }

3.2 扫描机制：从LeScanCallback到ScanCallback

demo里最核心的扫描代码用的是BluetoothLeScanner配合ScanCallback。这里要说明一下，官方demo的代码有多处update，早期版本用的是已废弃的startLeScan方法，现在正确姿势如下：

private val scanCallback = object : ScanCallback() { override fun onScanResult(callbackType: Int, result: ScanResult) { super.onScanResult(callbackType, result) val device = result.device val rssi = result.rssi val name = device.name ?: "未知设备" // 这里用runOnUiThread把结果更新到列表 runOnUiThread { leDeviceListAdapter.addDevice(device) leDeviceListAdapter.notifyDataSetChanged() } } override fun onScanFailed(errorCode: Int) { super.onScanFailed(errorCode) // errorCode为SCAN_FAILED_ALREADY_STARTED表示重复启动扫描 } } private fun startScan() { val filters: List<ScanFilter>? = null val settings = ScanSettings.Builder() .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY) .build() bluetoothLeScanner?.startScan(filters, settings, scanCallback) }

关键点在于ScanSettings的setScanMode参数。demo里用的是SCAN_MODE_LOW_LATENCY，扫描间隔短、结果出来快，但功耗高，适合主动扫描场景。如果你的app在后台持续扫描，建议用SCAN_MODE_LOW_POWER，否则会被系统判定为耗电异常。Android 8.0之后，后台应用扫描BLE有严格的限制：后台扫描时每30分钟只能有4次不超过30秒的扫描机会，这是系统的硬性限制。

扫描结果里的rssi是个很有用的字段，代表信号强度，实测中距离1米大概-40dBm，10米大概-70dBm，这可以作为粗略的距离判断依据，但千万别拿来精确测距，BLE信号受环境反射影响很大，同一位置角度转个90度，RSSI能差10dB以上。

我在用demo扫描的时候发现一个问题：列表经常会出现好几个同名的设备，这是因为设备在广播时每次的MAC地址可能不一样（隐私地址轮换），过滤方式是通过result.device.address去重，但实际场景中更好的做法是通过广播包里的Service UUID来过滤。后面我会讲到。

3.3 连接与GATT回调：这里最容易出问题

点击扫描列表里的设备后，进入设备控制界面，代码在DeviceControlActivity中。核心方法如下：

private fun connectToDevice(address: String): Boolean { if (bluetoothAdapter == null || address.isEmpty()) return false // 正式连接前要先取消之前未完成的连接 if (mBluetoothGatt != null) { mBluetoothGatt!!.close() mBluetoothGatt = null } val device = bluetoothAdapter!!.getRemoteDevice(address) mBluetoothGatt = device.connectGatt(this, false, mGattCallback) return true }

第二个参数autoConnect，demo里传的是false。这个参数选择在实际开发里很有讲究：autoConnect=false是主动发起连接，如果设备不在广播状态，连接会马上失败回调onConnectionStateChange且status为133；autoConnect=true则是在设备不在线时不停监听广播，等设备出现时自动建立连接。但后者连接速度慢，系统底层有较长的backoff周期，不适合需要快速连上的交互场景。我的建议是用户主动点击连接时用false，需要自动重连时用true。

GATT回调是整个demo中最核心也最容易出问题的地方：

private val mGattCallback = object : BluetoothGattCallback() { override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) { if (newState == BluetoothProfile.STATE_CONNECTED) { // 连接成功后立即发现服务 gatt.discoverServices() } else if (newState == BluetoothProfile.STATE_DISCONNECTED) { // 处理断开逻辑 } } override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) { if (status == BluetoothGatt.GATT_SUCCESS) { // 遍历服务，找到目标Service和Characteristic val services = gatt.services for (service in services) { // 根据Service UUID判断是否是你要的服务 } } } }

这个方法名discoverServices特别容易让人误会，以为它是从设备上拉取一个服务列表的数据操作。实际上它做的只是向设备发送一个发现服务的请求，设备返回的服务列表会缓存在GATT对象内部，你调用gatt.services拿到的就是这个缓存。有个巨坑：如果你disconnect之后没有调用close，系统会保留服务缓存；下次连接同一个设备时，服务列表可能还是旧的。如果你的设备固件升级后改了Service UUID，你就会奇怪为什么新服务没出现。解决方法是每次退出连接时调用gatt.close()，或者连上后主动调用refreshDeviceCache()（这个方法属于隐藏API，需要通过反射调用）。

还有一个高频问题：onConnectionStateChange的status参数不等于0时，表示连接失败，常见错误码是133（不是错误，是设备暂时不可达）和257（连接参数不满足要求）。很多初学者只判断newState == STATE_CONNECTED，不判断status，导致连接失败时UI表现很怪，一会儿显示已连接一会儿显示断开。正确做法是修改为：

override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) { when (newState) { BluetoothProfile.STATE_CONNECTED -> { if (status == BluetoothGatt.GATT_SUCCESS) { gatt.discoverServices() } else { // 失败时要主动关掉，否则底层连接一直占着 gatt.close() runOnUiThread { showMessage("连接失败，错误码: $status") } } } BluetoothProfile.STATE_DISCONNECTED -> { gatt.close() runOnUiThread { showMessage("连接断开") } } } }

3.4 读写与通知：MTU是绕不开的话题

发明特征的读写操作，demo在DeviceControlActivity中提供了readCharacteristic、writeCharacteristic等方法。这里我只挑重点说。

读取特征值：

private fun readCharacteristic(characteristic: BluetoothGattCharacteristic) { if (bluetoothGatt == null) return val success = bluetoothGatt!!.readCharacteristic(characteristic) if (!success) { showMessage("读取失败") } }

读取结果在onCharacteristicRead回调中获取：

override fun onCharacteristicRead( gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray, status: Int ) { if (status == BluetoothGatt.GATT_SUCCESS) { // value就是读取到的数据 } }

注意API 33以上，onCharacteristicRead的参数从byte[]类型变成了ByteArray,API 33以下还有另一个重载版本onCharacteristicRead(gatt, characteristic, status)，返回值是从characteristic.value取的。如果你只重写了新版本，在老设备上会静默地不触发回调，藏得相当深。

写入特征值分带响应和不带响应两种：

private fun writeCharacteristic(characteristic: BluetoothGattCharacteristic, value: ByteArray) { // API 33以上推荐写法 val writeType = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { characteristic.writeType } else { characteristic.writeType } characteristic.value = value val success = bluetoothGatt!!.writeCharacteristic(characteristic) }

重点来了：MTU（Maximum Transmission Unit）。BLE 4.x默认MTU是23字节，其中3字节被协议头占用，实际用户数据只有20字节。意味着你单次只能发20字节的数据，超过20字节要么协商更大的MTU，要么自己分包。

协商更大MTU使用requestMtu方法：

val success = bluetoothGatt?.requestMtu(247)

但这里有个前置条件：手机和从机都必须支持。Android端通常支持512字节，但你的BLE外设如果固件里没配置相应的MTU大小，协商就会失败。协商结果的回调在onMtuChanged里获取。实践中的经验是MTU设为185比较稳妥（185-3=182字节可用），这是一个在兼容性和传输效率上比较平衡的值。

当你需要传一张图片或一段几百字节的数据时，正确做法是：

• 先查MTU，确定单包能传多少字节
• 计算总包数，按顺序发送
• 每发送一包后，等待对端返回确认包，再发下一包

我见过很多新手把数据split成每20字节一个包然后一股脑全发出去，结果对端收到的是乱序的或者直接丢包。原因在于BLE底层的流控，如果你在收到对端应答之前发了太多包，对端会直接丢弃后续的。所以我在demo基础上增加了简单的ACK确认机制，感觉是用的最顺手的方案。

接收通知则需要先开启Notification，这一步对初学者来说有些玄学，很容易踩坑。开启Notif的流程是：

private fun enableNotification(characteristic: BluetoothGattCharacteristic, enabled: Boolean) { val descriptor = characteristic.getDescriptor(UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")) if (descriptor != null) { descriptor.value = if (enabled) { BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE } else { BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE } bluetoothGatt?.writeDescriptor(descriptor) } // 这里还需要指定接收通知的特征 bluetoothGatt?.setCharacteristicNotification(characteristic, enabled) }

顺序很重要：先setCharacteristicNotification把特征注册到回调里，再去写CCCD（Client Characteristic Configuration Descriptor）。如果顺序反了，会收不到通知。写的这个Descriptor的UUID是固定的00002902-0000-1000-8000-00805f9b34fb，这是BLE协议规定的CCCD，所有有Notification属性的特征都得配置它。

还有个比较容易混淆的点：setCharacteristicNotification的返回值没法代表通知是否真正开启，真正的成功回调是onDescriptorWrite。如果CCCD写入失败，最常见原因是设备端这个特征的Property不包含Notify或Indicate。

3.5 连接管理：不要只是disconnect，要close

demo里退出页面时会执行：

override fun onDestroy() { super.onDestroy() if (mBluetoothGatt != null) { mBluetoothGatt!!.close() mBluetoothGatt = null } }

这个close()很多人都漏了，但它是必须的。disconnect()只断开当前连接，但GATT对象仍然保存着连接尝试的状态，如果不close，后续重连会出现各种诡异问题，最常见的表现是：连接成功后discoverServices一直不回调，或者回调的status是133。原因是系统底层同一时刻只允许一个GATT连接实例在跑，你不close掉旧的，新连接就被占着资源起不来。

我还遇到过一种情况：设备断开后，没有调用close就立刻重新连接同一个设备，结果连接一直失败。日志里也没有明确的报错，就是连不上，隔一会儿又莫名其妙地好了。后来才意识到这是系统蓝牙协议栈的处理逻辑，蓝牙连接断开后底层需要一段时间做资源回收，你的代码如果在这个窗口期里重连，就可能失败。解决方案是断开后延迟几百毫秒到1秒再发起重连。

4. 实际开发中的常见问题与处理方案

4.1 扫描不到设备

这是最高频的问题，通常有以下几个原因：

我遇到过特别折腾的一次：在Android 12手机上扫描没问题，Android 8手机上却扫不到任何设备。后来发现是targetSdk升到31之后，在Android 8设备上运行时因为系统没有强制权限模型，BLUETOOTH_SCAN权限被忽略了，但定位权限又没有申请成功，导致扫描直接返回空。解决办法很简单，在检查权限时同时检查targetSdk，对老设备特殊处理，保证定位权限必须拿到。

4.2 连接之后老是掉线

掉线问题一般出在连接参数上。BLE设备在建立连接后，Android系统会基于设备的建议更新连接间隔。如果你连接的是一个没有优化过连接参数的低成本外设，或者外设的建议连接参数太激进，Android系统会在某个时刻判定连接质量差，强制断开。

这个问题用demo原版代码几乎没法解决，因为你没法直接控制Android底层的连接参数。你能做的是：

• 检查外设固件里建议的连接间隔，间隔太短（比如7.5ms）容易导致掉线
• 连接成功后，主动通过GATT服务里的Connection Parameters服务（如果设备支持）修改参数
• 保持app在前台运行，不要切到后台，因为Android后台对BLE连接的资源管理更严格

在真机实测中，Nordic的SDK设置默认连接间隔为30ms~50ms，连接稳定性就很好；某些便宜的模块把连接间隔设到10ms以下，手机连接后运行几分钟就会断。

4.3 数据收发不完整

如果你发现收到的数据比设备发出来的少，或者写入大片数据后设备只收到了前面的字节，大概率是MTU没协商好，或者分包策略有问题。

我总结的经验是：先协商MTU再审数据。协商成功后的onMtuChanged回调里拿到的mtu值，会告诉你单包数据的最大可用大小。假设协商结果是mtu=247，那么单包实际可用数据是244字节（247-3）。你的代码里应该有这样一个工具方法：

fun splitPackets(data: ByteArray, mtuSize: Int): List<ByteArray> { val maxPayload = mtuSize - 3 val packets = mutableListOf<ByteArray>() var offset = 0 while (offset < data.size) { val length = minOf(maxPayload, data.size - offset) packets.add(data.copyOfRange(offset, offset + length)) offset += length } return packets }

发送时加一个简单的超时重传机制。网上有人这么做：发完一包后启动2秒超时定时器，收到对端ACK就取消定时器发下一包，超时则重发。这种做法在数据量不大时完全够用。

4.4 动态广播过滤：避免收到一堆无关设备

原版demo把周围所有正在广播的设备都列出来了，在一个办公楼里扫码能刷出一大屏。实际项目里，你只会关心自己公司那款设备。常规做法是启动扫描时传入ScanFilter：

val scanFilter = ScanFilter.Builder() .setServiceUuid(ParcelUuid.fromString("0000ffe0-0000-1000-8000-00805f9b34fb")) .build() val filters = listOf(scanFilter) bluetoothLeScanner?.startScan(filters, settings, scanCallback)

setServiceUuid会匹配广播包里的Service UUID，这个UUID是设备厂商定义的，你得从设备文档里找到。如果设备在广播包里没有广播Service UUID，还可以用setDeviceAddress指定MAC地址过滤，但这种方式限制太死，不够灵活。

有一种更高级的过滤方式：解析广播包raw data里的Manufacturer Specific Data。很多设备会把设备类型、是否连接中、电量这类信息放在厂商自定义数据里。你可以在ScanResult.scanRecord?.bytes里手动解析这一段数据，实现比较智能的判断逻辑。

4.5 Android 12及以上版本适配

Android 12是BLE开发的分水岭，权限模型变化影响面非常大。老代码如果不适配，直接面临两个问题：

• 使用startLeScan或BluetoothAdapter.startDiscovery扫描时直接抛SecurityException
• 连接设备时因为没动态申请BLUETOOTH_CONNECT，在connectGatt就会崩

正确的适配思路是：

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // 使用新的权限模型 requestPermissions(arrayOf( Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT ), REQUEST_BLE_PERMISSION) }

此外，Android 12的权限弹窗有两个：一个扫描权限，一个连接权限，它们可以分开授权。如果用户只授权了扫描没授权连接，你能扫描到设备但连不上；反过来你能主动连设备但扫描不到新设备。这种割裂状态对体验影响很大，建议在UI层做好引导，如果发现某个权限缺失，弹出明确的说明而不是让用户盲猜。

5. 实操总结：从demo到可用项目的改造建议

官方demo跑通之后，你可以直接在这个基础上做几个升级，让它更接近真实项目。

第一个建议是增加重连机制。demo里连接断了就断了，产品上这肯定不行。我会在断开后记录设备地址，弹出重连提示，或者直接定时重试，重试次数限制在3-5次之间，每次间隔1-2秒。

第二个建议是抽离BLE管理类。原版demo把GATT回调、扫描、连接都写在Activity里，业务一复杂就变成母类大妈，几百行代码揉在一起。我一般会抽一个BleManager单例，封装扫描、连接、断开、读写、通知等所有操作，通过回调接口把结果抛给UI层。

第三个建议是处理设备连接的超时机制。原版demo里，点击设备后如果一直连不上，UI就一直卡在连接中。我会加一个8秒超时，超时后自动调disconnect并提示用户重试。这个8秒不是随便定的，是根据实际测试，绝大多数正常设备的连接握手在8秒内能完成，超过8秒基本是设备离线或者信号差。

第四个建议是增加日志记录。把关键的状态变化、错误码、每次收发的数据都记录到文件中。BLE这种无线通信的问题极其依赖现场日志排查，很多问题只有设备端能看到，两端日志一对比，问题立刻就能定位。

最后再分享一个我自己的体会：官方demo就像一把钥匙，帮你打开BLE世界的大门，但它展示的是最基础的用法，真正落地到产品里，有太多脏活累活在等着你。上面提到的权限处理、MTU协商、分包策略、连接管理这些问题，如果等踩坑后再查，浪费的时间可不少。把demo吃透，在上面把这些坑提前填掉，后面开发其他蓝牙项目就会轻松很多。

本文还有配套的精品资源，点击获取