BLE低功耗蓝牙模块

📋 模块概述

BLE(Bluetooth Low Energy)低功耗蓝牙模块提供BLE设备的连接、GATT服务访问、特征值读写、通知订阅等功能。

核心类: android.znhaas.bluetooth.BluetoothBleManager

扫描管理: android.znhaas.bluetooth.BluetoothBleScanner

连接管理: android.znhaas.bluetooth.BluetoothBleConnection

协议处理: android.znhaas.bluetooth.BluetoothBleHandler

🎯 主要功能

• ✅ BLE设备扫描
• ✅ GATT连接管理
• ✅ 服务发现
• ✅ 特征值读取/写入
• ✅ 通知/指示订阅
• ✅ Handler线程安全处理

📚 核心API

1. 初始化

val bleManager = BluetoothBleManager(context)
bleManager.initialize()

2. 扫描BLE设备

// 开始扫描
bleManager.bleScanner.startScan()

// 设置扫描结果监听
bleManager.bleScanner.setScanResultListener { device ->
    Log.d(TAG, "发现BLE设备: ${device.name} - ${device.address}")
    handleDeviceFound(device)
}

// 停止扫描
bleManager.bleScanner.stopScan()

3. 连接BLE设备

val device = BluetoothDeviceInfo(
    address = "AA:BB:CC:DD:EE:FF",
    name = "BLE Sensor",
    deviceType = DeviceType.BLE_DEVICE
)

bleManager.connectBleDevice(device)

4. GATT操作

读取特征值

bleManager.readCharacteristic(
    deviceAddress = "AA:BB:CC:DD:EE:FF",
    serviceUuid = "0000180d-0000-1000-8000-00805f9b34fb",
    characteristicUuid = "00002a37-0000-1000-8000-00805f9b34fb"
)

写入特征值

val data = byteArrayOf(0x01, 0x02, 0x03)
bleManager.writeCharacteristic(
    deviceAddress = "AA:BB:CC:DD:EE:FF",
    serviceUuid = "0000180d-0000-1000-8000-00805f9b34fb",
    characteristicUuid = "00002a39-0000-1000-8000-00805f9b34fb",
    data = data
)

订阅通知

bleManager.enableNotification(
    deviceAddress = "AA:BB:CC:DD:EE:FF",
    serviceUuid = "0000180d-0000-1000-8000-00805f9b34fb",
    characteristicUuid = "00002a37-0000-1000-8000-00805f9b34fb"
)

5. 数据接收监听

bleManager.setDataListener { address, serviceUuid, characteristicUuid, data ->
    Log.d(TAG, "收到BLE数据: ${data.toHexString()}")
    handleBleData(data)
}

6. 连接状态监听

bleManager.setConnectionListener { address, isConnected ->
    if (isConnected) {
        Log.d(TAG, "BLE设备已连接: $address")
        // 连接后自动发现服务
        bleManager.discoverServices(address)
    } else {
        Log.d(TAG, "BLE设备已断开: $address")
    }
}

7. 断开连接

bleManager.disconnectBleDevice("AA:BB:CC:DD:EE:FF")

🔧 完整使用示例

class BleActivity : AppCompatActivity() {
    
    private lateinit var bleManager: BluetoothBleManager
    private var targetDevice: BluetoothDeviceInfo? = null
    
    // 心率服务UUID
    private val HEART_RATE_SERVICE_UUID = "0000180d-0000-1000-8000-00805f9b34fb"
    private val HEART_RATE_MEASUREMENT_UUID = "00002a37-0000-1000-8000-00805f9b34fb"
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_ble)
        
        // 初始化
        bleManager = BluetoothBleManager(this)
        bleManager.initialize()
        
        setupListeners()
        
        // 扫描按钮
        scanButton.setOnClickListener {
            startScan()
        }
        
        // 连接按钮
        connectButton.setOnClickListener {
            targetDevice?.let { device ->
                bleManager.connectBleDevice(device)
            }
        }
    }
    
    private fun setupListeners() {
        // 扫描结果监听
        bleManager.bleScanner.setScanResultListener { device ->
            runOnUiThread {
                // 过滤心率设备
                if (device.name?.contains("Heart", ignoreCase = true) == true) {
                    targetDevice = device
                    deviceNameText.text = device.name
                    deviceAddressText.text = device.address
                    connectButton.isEnabled = true
                }
            }
        }
        
        // 连接状态监听
        bleManager.setConnectionListener { address, isConnected ->
            runOnUiThread {
                if (isConnected) {
                    statusText.text = "已连接"
                    // 发现服务
                    bleManager.discoverServices(address)
                } else {
                    statusText.text = "未连接"
                }
            }
        }
        
        // 服务发现监听
        bleManager.setServicesDiscoveredListener { address, services ->
            runOnUiThread {
                Log.d(TAG, "发现${services.size}个服务")
                // 订阅心率通知
                bleManager.enableNotification(
                    deviceAddress = address,
                    serviceUuid = HEART_RATE_SERVICE_UUID,
                    characteristicUuid = HEART_RATE_MEASUREMENT_UUID
                )
            }
        }
        
        // 数据接收监听
        bleManager.setDataListener { address, serviceUuid, characteristicUuid, data ->
            runOnUiThread {
                // 解析心率数据
                if (characteristicUuid == HEART_RATE_MEASUREMENT_UUID && data.isNotEmpty()) {
                    val heartRate = data[1].toInt() and 0xFF
                    heartRateText.text = "$heartRate BPM"
                }
            }
        }
    }
    
    private fun startScan() {
        bleManager.bleScanner.startScan()
        scanButton.isEnabled = false
        
        // 10秒后自动停止扫描
        Handler(Looper.getMainLooper()).postDelayed({
            bleManager.bleScanner.stopScan()
            scanButton.isEnabled = true
        }, 10000)
    }
    
    override fun onDestroy() {
        super.onDestroy()
        bleManager.cleanup()
    }
}

⚠️ 注意事项

1. 权限要求

<!-- 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" />

2. UUID格式

BLE使用128位UUID,标准服务UUID格式:

0000xxxx-0000-1000-8000-00805f9b34fb

3. MTU大小

默认MTU为23字节(有效数据20字节),可以请求更大的MTU:

bleManager.requestMtu(deviceAddress, 512)

4. 扫描超时

建议设置扫描超时,避免持续扫描耗电:

bleScanner.startScan()
Handler().postDelayed({ bleScanner.stopScan() }, 10000) // 10秒超时

5. 线程安全

GATT回调在Handler线程处理,UI更新需切换到主线程:

bleManager.setDataListener { address, serviceUuid, characteristicUuid, data ->
    runOnUiThread {
        // 更新UI
        textView.text = data.toHexString()
    }
}

🔗 相关资源

• 源码:
  • app/src/main/java/android/znhaas/bluetooth/BluetoothBleManager.kt
  • app/src/main/java/android/znhaas/bluetooth/BluetoothBleScanner.kt
  • app/src/main/java/android/znhaas/bluetooth/BluetoothBleConnection.kt

📚 扩展阅读

• BLE协议标准
• Android BLE开发指南
• GATT服务规范