Android | Kotlin实现Ble低功耗蓝牙设备连接

一、引言

本文记录在之前进行的仪表类多ble设备采集项目开发中，使用到的低功耗蓝牙连接技术的总结。
二、概念

(一) 低功耗蓝牙介绍

低功耗蓝牙是4.0版本起支持的蓝牙协议，主要特点是低功耗，传输速度快，传输数据量小的特点。
工作在2.4GHz 频段，使用调频扩频实现抗干扰。
支持广播+点对点快速连接。
(二) GATT （Generic Attribute Profile通用属性配置文件）

Gatt是立在 ATT（Attribute Protocol，属性协议） 之上的用于结构化数据交换的标准方式。
Gatt架构中，有明确的角色划分，分别是服务端和客户端。
Gatt Server（服务器）数据的提供者，提供服务和特征值。
Gatt Client（客户端） 访问服务器数据的设备，发起请求
1. GATT 层次结构：层级模型

GATT 使用一种树状结构来组织数据，从大到小依次为：

1. Device（设备）
2. └─── Service（服务）
3.      └─── Characteristic（特征值）
4.           ├── Value（值）
5.           └─── Descriptor（描述符，可选）

复制代码

1.1 Service（服务）

• 表示一类功能或数据集合。
  
• 每个 Service 包含一个或多个 Characteristic。
  

Service 的组成：

• UUID（Universally Unique Identifier）：唯一标识符，用来区分不同服务。
  
• 标准服务使用 16位 UUID（由 Bluetooth SIG 定义）
  
• 自定义服务使用 128位 UUID，避免冲突。
  
• Handle（句柄）：内部索引号，用于快速定位。
  
• 包含关系：一个服务可以“包含”另一个服务（较少见）。
  

1.2 Characteristic（特征值）

这是 GATT 中最核心的数据单元。

• 特征值代表一个具体的数据项，比如“当前心率”、“开关状态”、“温度值”。
  
• 每个特征值属于某个服务。
  
• 包括三部分：
  

• Value（值）：实际的数据内容（如 byte 数组）。
  
• Properties（属性）：说明该特征值支持哪些操作。
  
• Descriptors（描述符，可选）：对值的补充说明（如单位、用户描述）。
  

特征值的 Properties
这些属性决定了客户端能对该特征值做什么操作：
属性功能对应操作Read可读Client 可读取其值Write可写Client 可写入新值Notify通知Server 主动向 Client 发送更新（无需回复）Indicate指示类似 Notify，但要求 Client 回 ACK（确认收到）Broadcast广播向所有监听设备发送（不常用）Write Without Response无响应写入快速写入，不等待确认（适合高频数据）1.3 Descriptor（描述符）

是对特征值的元数据说明，是可选组件。
三、权限适配

在进行ble设备操作前，必须进行权限的相关配置。
1. Android 6.0 ~ 11（API 23–30）

• 必须获取 ACCESS_FINE_LOCATION
  
• 用户可在设置中关闭
  
• 即使 App 不需要定位，也必须申请位置权限
  

2.  Android 12+（API ≥ 31）

• 不再需要位置权限
  
• 使用两个新权限：
  
• BLUETOOTH_SCAN：用于扫描
  
• BLUETOOTH_CONNECT：用于连接已有设备
  

3. 权限声明清单

1. [/code][size=6]四、具体实现[/size]
3. [size=5](一) GATT 工作流程[/size]
5. [size=4]1. [b]CCCD[/b][/size]
7. [b]CCCD[/b]（[b]C[/b]lient [b]C[/b]haracteristic [b]C[/b]onfiguration [b]D[/b]escriptor）：
8. 特殊的描述符，控制某个特征值是否通知Notify，即通知开关。
9. [table][tr][b]写入值（16位）[/b][b]含义[/b][b]用途[/b][/tr][tr][td]0x0000[/td][td]禁用通知和指示（默认值）[/td][td]初始状态，不接收推送[/td][/tr][tr][td]0x0001[/td][td]启用 [b]Notification（通知）[/b][/td][td]服务器可主动发送数据，无需确认[/td][/tr][tr][td]0x0002[/td][td]启用 [b]Indication（指示）[/b][/td][td]服务器发送数据后，必须等待客户端回复 ACK[/td][/tr][/table]如果没有配置[b]CCCD[/b]，即便低功耗蓝牙设备具备通知功能，也无法进行通知。因此在需要开启消息自动通知时，需要配置CCCD。
10. [size=4]2. [b]BluetoothAdapter[/b][/size]
12. 注：从Android 4.3(API18）开始，使用BluetoothManager来获取adapter。
13. 核心功能：
14. [list]
15. [*]控制蓝牙开关(Android 12后需要手动确认)
16. [*]设备扫描（经典蓝牙和ble的api不同,ble需要通过其子对象 BluetoothLeScanner扫描）
17. [*]获取蓝牙信息（name,mac）
18. [*]通过地址获取设备引用（getRemoteDevice(address)）
19. [*]通过广播监听状态变化
20. [/list][size=4]3. [b]BluetoothGatt[/b][/size]
22. BluetoothGatt 是Android与ble外设通信的桥梁和控制中心，是ble客户端的抽象，并不是设备本身，而是与设备建立连接后获取的一个通信句柄。
23. 核心功能：
24. [list]
25. [*]创建连接（connectGatt，会返回BluetoothGatt实例）
26. [*]发现服务（discoverServices，发起服务发现流程）
27. [*]读写特征值（readCharacteristic/writeCharacteristic）
28. [*]开启本地通知监听（setCharacteristicNotification）
29. [*]写描述符（如CCCD)
30. [*]请求MTU扩展
31. [*]设置连接优先级
32. [*]断开连接（disconnect）
33. [*]释放资源（close）
34. [/list][size=4]4. [b]BluetoothGattCallback[/b][/size]
36. 调用BluetoothGatt connectGatt(android.content.Context context, boolean autoConnect, android.bluetooth.BluetoothGattCallback callback, int transport)
37. 需要传入一个关键参数，BluetoothGattCallback是一个抽象类，在进行具体实现时，需要继承这个抽象类实现所有的抽象回调方法，如果把BluetoothGatt比作电话，BluetoothGattCallback更像是一个听筒。
38. 注意，每个设备和Gatt只能持有自己的gattCallBack
39. BluetoothGattCallback包含如下重要的回调方法：
40. [list]
41. [*]onConnectionStateChange        连接状态回调
42. [*]onServicesDiscovered                服务发现回调
43. [*]onCharacteristicRead                特征值读回调
44. [*]onCharacteristicWrite                特征值写入回调
45. [*]onCharacteristicChanged        特征值变化通知回调（对应设置了CCCD的通知）
46. [*]onDescriptorWrite                        特征值描述写入回调
47. [*]onMtuChanged                        Mtu变化回调
48. [/list][size=4]5. [b]工作流程：[/b][/size]
50. App 启动 BLE 扫描 → 发现目标设备 → 自动连接 → 建立通信通道 → 准备好读写操作。
51. 这里注意是采用特征值通知的方式读取数据，还有一种方式是上位机直接进行特征值读取。
52. [align=center][img]https://cdn.nlark.com/yuque/__mermaid_v3/431f390567d85cd0bd3f71acfd618948.svg[/img][/align]
53. [size=4]6. [b]注意点：[/b][/size]
55. [list=1]
56. [*]链路连接成功是onConnectionStateChange回调触发，但并不能直接进行通讯，真正的[b]连接成功[/b]定义在onServicesDiscovered成功之后；
57. [/list]
58. [list]
59. [*]必须在onConnectionStateChange之中手动调用discoverServices
60. [*]app主动获取低功耗蓝牙模块制定特征值的数据需要记录对应模块的READ UUID，通过调用readCharacteristic来进行对应特征值的读取，适用于app端主动获取数据的场景。
61. [/list][size=5](二) 代码实现[/size]
63. [code]/**
64. * BLE 设备封装类 —— 实现连接、通信与事件分发
65. */
66. class BleDevice(
67.     private val deviceName: String,
68.     private val deviceAddress: String,
69.     private var nativeDevice: BluetoothDevice? = null
70. ) {
72.     companion object {
73.         private const val TAG = "BleDevice"
75.         // 服务与特征值 UUID（请根据实际设备修改）
76.         private val SERVICE_UUID = UUID.fromString("0000fff0-0000-1000-8000-00805f9b34fb")
77.         private val NOTIFY_CHARACTERISTIC_UUID = UUID.fromString("0000fff1-0000-1000-8000-00805f9b34fb")
78.         private val WRITE_CHARACTERISTIC_UUID = UUID.fromString("0000fff2-0000-1000-8000-00805f9b34fb")
80.         // CCCD UUID（标准定义）
81.         private val CLIENT_CHARACTERISTIC_CONFIG = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")
82.     }
84.     // 当前连接状态
85.     @Volatile
86.     var isConnected: Boolean = false
87.         private set
89.     // 回调接口
90.     var stateListener: ((device: BleDevice, state: ConnectionState) -> Unit)? = null
91.     var dataListener: ((device: BleDevice, data: ByteArray) -> Unit)? = null
93.     private var bluetoothGatt: BluetoothGatt? = null
94.     private var writeCharacteristic: BluetoothGattCharacteristic? = null
95.     private var notifyCharacteristicUuid: UUID? = null
97.     // 主线程 Handler，用于回调 UI
98.     private val mainHandler = Handler(Looper.getMainLooper())
100.     /**
101.      * 连接设备
102.      */
103.     fun connect(context: Context) {
104.         if (isConnected) {
105.             Log.w(TAG, "Already connected to $deviceName")
106.             return
107.         }
109.         // 清理旧连接
110.         closeOldConnection()
112.         realConnect(context.applicationContext)
113.     }
115.     private fun closeOldConnection() {
116.         if (bluetoothGatt != null) {
117.             Log.d(TAG, "Closing previous GATT instance to avoid errors...")
118.             try {
119.                 bluetoothGatt?.close()
120.             } catch (e: Exception) {
121.                 Log.e(TAG, "Error closing old GATT", e)
122.             }
123.             bluetoothGatt = null
125.             // 延迟重连，避免频繁操作导致 Status 133
126.             mainHandler.postDelayed(this::realConnectWithAppContext, 200)
127.         }
128.     }
130.     private val realConnectWithAppContext: () -> Unit = {
131.         // 在延时任务中重新获取 context（需外部传入）
132.     }
134.     private fun realConnect(context: Context) {
135.         val adapter = (context.getSystemService(Context.BLUETOOTH_SERVICE) as? BluetoothManager)?.adapter
136.             ?: run {
137.                 stateListener?.invoke(this, ConnectionState.Error("Bluetooth not available"))
138.                 return
139.             }
141.         if (!adapter.isEnabled) {
142.             stateListener?.invoke(this, ConnectionState.Error("Bluetooth is disabled"))
143.             return
144.         }
146.         val device = nativeDevice ?: run {
147.             val d = adapter.getRemoteDevice(deviceAddress)
148.             nativeDevice = d
149.             d
150.         }
152.         try {
153.             bluetoothGatt = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
154.                 device.connectGatt(context, false, gattCallback, BluetoothDevice.TRANSPORT_LE)
155.             } else {
156.                 device.connectGatt(context, false, gattCallback)
157.             }
158.         } catch (e: IllegalArgumentException) {
159.             Log.e(TAG, "Invalid device address: $deviceAddress", e)
160.             stateListener?.invoke(this, ConnectionState.Error("Invalid address"))
161.         }
162.     }
164.     /**
165.      * 断开连接
166.      */
167.     fun disconnect() {
168.         bluetoothGatt?.disconnect()
169.     }
171.     /**
172.      * 发送数据
173.      */
174.     fun sendData(data: ByteArray): Boolean {
175.         val char = writeCharacteristic ?: return false
177.         return try {
178.             char.value = data
179.             char.writeType = BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
180.             bluetoothGatt?.writeCharacteristic(char) == true
181.         } catch (e: Exception) {
182.             Log.e(TAG, "Failed to write characteristic", e)
183.             false
184.         }
185.     }
187.     /**
188.      * 主动读取特征值（可选）
189.      */
190.     fun readData() {
191.         val char = bluetoothGatt?.getService(SERVICE_UUID)
192.             ?.getCharacteristic(NOTIFY_CHARACTERISTIC_UUID)
193.             ?: return
195.         bluetoothGatt?.readCharacteristic(char)
196.     }
198.     // MARK: - GATT Callback
200.     private val gattCallback = object : BluetoothGattCallback() {
202.         override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
203.             when (newState) {
204.                 BluetoothProfile.STATE_CONNECTED -> {
205.                     Log.i(TAG, "Connected to $deviceName")
206.                     isConnected = true
207.                     mainHandler.post { stateListener?.invoke(this@BleDevice, ConnectionState.Connected) }
209.                     // 请求高优先级连接参数
210.                     gatt.requestConnectionPriority(BluetoothGatt.CONNECTION_PRIORITY_HIGH)
211.                     // 开始服务发现
212.                     gatt.discoverServices()
213.                 }
214.                 BluetoothProfile.STATE_DISCONNECTED -> {
215.                     Log.i(TAG, "Disconnected from $deviceName")
216.                     isConnected = false
217.                     writeCharacteristic = null
218.                     notifyCharacteristicUuid = null
220.                     gatt.close()
221.                     bluetoothGatt = null
223.                     mainHandler.post { stateListener?.invoke(this@BleDevice, ConnectionState.Disconnected) }
224.                 }
225.             }
226.         }
228.         override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
229.             if (status != BluetoothGatt.GATT_SUCCESS) {
230.                 Log.e(TAG, "Service discovery failed: $status")
231.                 mainHandler.post {
232.                     stateListener?.invoke(this@BleDevice, ConnectionState.Error("Service discovery failed"))
233.                 }
234.                 return
235.             }
237.             val targetService = gatt.getService(SERVICE_UUID)
238.             if (targetService == null) {
239.                 Log.e(TAG, "Target service not found")
240.                 printAllServices(gatt.services)
241.                 return
242.             }
244.             for (char in targetService.characteristics) {
245.                 when (char.uuid) {
246.                     WRITE_CHARACTERISTIC_UUID -> {
247.                         writeCharacteristic = char.apply {
248.                             writeType = BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
249.                         }
250.                         Log.d(TAG, "Write characteristic found: ${char.uuid}")
251.                     }
252.                     NOTIFY_CHARACTERISTIC_UUID -> {
253.                         Log.d(TAG, "Notify characteristic found: ${char.uuid}")
254.                         notifyCharacteristicUuid = char.uuid
255.                         enableNotification(gatt, char)
256.                     }
257.                 }
258.             }
259.         }
261.         // 接收被动通知的数据（服务器主动推送）
262.         override fun onCharacteristicChanged(
263.             gatt: BluetoothGatt,
264.             characteristic: BluetoothGattCharacteristic
265.         ) {
266.             handleReceivedData(characteristic.value ?: byteArrayOf())
267.         }
269.         // 主动读取返回的数据
270.         override fun onCharacteristicRead(
271.             gatt: BluetoothGatt,
272.             characteristic: BluetoothGattCharacteristic,
273.             status: Int
274.         ) {
275.             if (status == BluetoothGatt.GATT_SUCCESS) {
276.                 Log.d(TAG, "Read success: ${characteristic.uuid}")
277.                 handleReceivedData(characteristic.value ?: byteArrayOf())
278.             }
279.         }
281.         override fun onDescriptorWrite(
282.             gatt: BluetoothGatt,
283.             descriptor: BluetoothGattDescriptor,
284.             status: Int
285.         ) {
286.             if (status == BluetoothGatt.GATT_SUCCESS) {
287.                 Log.d(TAG, "CCCD enabled: ${descriptor.characteristic.uuid}")
288.             } else {
289.                 Log.e(TAG, "Failed to write descriptor: $status")
290.             }
291.         }
292.     }
294.     private fun enableNotification(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic) {
295.         if (!gatt.setCharacteristicNotification(characteristic, true)) {
296.             Log.e(TAG, "Failed to set characteristic notification")
297.             return
298.         }
300.         val cccd = characteristic.getDescriptor(CLIENT_CHARACTERISTIC_CONFIG)
301.         if (cccd != null) {
302.             cccd.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
303.             gatt.writeDescriptor(cccd)
304.         } else {
305.             Log.w(TAG, "CCCD not found for characteristic ${characteristic.uuid}. Trying fallback...")
306.             // 尝试写入第一个可用描述符（部分设备非标准实现）
307.             characteristic.descriptors.firstOrNull()?.let { desc ->
308.                 desc.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
309.                 gatt.writeDescriptor(desc)
310.             }
311.         }
312.     }
314.     private fun handleReceivedData(value: ByteArray) {
315.         Log.d(TAG, "Received data: ${value.toHexString()}")
316.         mainHandler.post { dataListener?.invoke(this, value) }
317.     }
319.     private fun printAllServices(services: List<BluetoothGattService>) {
320.         Log.d(TAG, "Discovered services:")
321.         services.forEach { service ->
322.             Log.d(TAG, "  Service: ${service.uuid}")
323.             service.characteristics.forEach { char ->
324.                 Log.d(TAG, "    Char: ${char.uuid} | Props: ${char.properties}")
325.             }
326.         }
327.     }
328. }
330. // MARK: - 状态枚举
331. sealed class ConnectionState {
332.     object Connected : ConnectionState()
333.     object Disconnected : ConnectionState()
334.     data class Error(val message: String) : ConnectionState()
335. }
337. // MARK: - 工具扩展
338. private fun ByteArray.toHexString(): String =
339.     this.joinToString(separator = " ") { "%02X".format(it) }

复制代码

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

用心讨论，共获提升！

新版吗？好像是停更了吧。