簡介這是一份面向Android開發(fā)者的藍(lán)牙開發(fā)源碼工程包涵蓋藍(lán)牙適配器初始化、BLE設(shè)備掃描、Gatt連接及數(shù)據(jù)讀寫等核心流程適用于初學(xué)藍(lán)牙通信或需快速搭建設(shè)備互聯(lián)功能的開發(fā)者。壓縮包共23個(gè)文件包含Java源碼、AndroidManifest.xml、資源文件以及編譯生成的apk、dex、class等既可直接閱讀源碼也可運(yùn)行包內(nèi)APK驗(yàn)證效果整體僅91KB輕量便于下載。已有209人學(xué)習(xí)瀏覽這份工程包具有一定參考價(jià)值。通過分析源碼可掌握BluetoothManager與BluetoothAdapter的獲取方式、ScanCallback掃描回調(diào)處理、BluetoothGatt與BluetoothGattCallback的用法還能理解Android不同版本對(duì)掃描權(quán)限、掃描模式的要求從而減少實(shí)際開發(fā)中的兼容性問題。1. Android 藍(lán)牙開發(fā)源碼從能掃到設(shè)備到能順利交付的完整路徑搜“android 藍(lán)牙開發(fā)源碼”結(jié)果基本分兩種要么是幾年前的 Demo 工程要么是封裝得看不出調(diào)用邏輯的框架代碼。實(shí)際上 Android 藍(lán)牙開發(fā)屬于“看起來不難、跑起來全是細(xì)節(jié)”的模塊——權(quán)限、掃描、配對(duì)、連接、服務(wù)發(fā)現(xiàn)、數(shù)據(jù)收發(fā)每一環(huán)都可能因?yàn)樵O(shè)備兼容性翻車而且一旦翻車報(bào)錯(cuò)信息常常讓你摸不著頭腦。這篇文章不打算給你一份虛構(gòu)的全家桶源碼包而是把一條可復(fù)現(xiàn)的開發(fā)路徑拆開講透先搞懂選型再跑通最小工程接著調(diào)關(guān)鍵參數(shù)最后落在一份能用的避坑清單上。不管你是新接手藍(lán)牙功能還是已經(jīng)寫了兩天還卡在連接階段按這個(gè)順序走一遍對(duì)自己手上的源碼該看哪里、改哪里、為什么這么改會(huì)有清晰的方向感。2. 先選型再讀碼經(jīng)典藍(lán)牙與 BLE 的源碼結(jié)構(gòu)差異2.1 經(jīng)典藍(lán)牙與 BLE協(xié)議棧差異決定了代碼走向Android 的藍(lán)牙技術(shù)棧從 API 層面分兩條路線。經(jīng)典藍(lán)牙走 BluetoothSocket適合音頻、文件傳輸這類持續(xù)大流量場景低功耗藍(lán)牙BLE走 BluetoothGatt適合傳感器數(shù)據(jù)、遙控器、智能硬件這類小包低頻場景。兩者的源碼結(jié)構(gòu)差異很大經(jīng)典藍(lán)牙的核心是BluetoothDevice.createRfcommSocketToServiceRecord()BLE 的核心是BluetoothGattCallback里那一堆異步回調(diào)。選型選錯(cuò)了后面的代碼幾乎等于白寫。實(shí)際項(xiàng)目里“android 藍(lán)牙開發(fā)源碼”的需求大部分落在 BLE 上。原因無非三點(diǎn)功耗低、協(xié)議靈活、手機(jī)兼容性好。但如果你要接的是車載藍(lán)牙、藍(lán)牙音箱、老式藍(lán)牙串口模塊那就繞不開經(jīng)典藍(lán)牙的 Socket 路線。我的習(xí)慣是先問自己三個(gè)問題數(shù)據(jù)量多大傳輸頻率多高對(duì)端設(shè)備是什么數(shù)據(jù)量超過每秒幾十 KB、且要求穩(wěn)定流式傳輸就選經(jīng)典藍(lán)牙否則優(yōu)先 BLE。這個(gè)決定直接決定了你手上那份源碼的代碼組織方式。兩條路線在連接流程上的差異也要清楚這會(huì)影響你排查問題的方向。經(jīng)典藍(lán)牙需要先配對(duì)再創(chuàng)建 Socket連接后走輸入輸出流BLE 不需要配對(duì)直接連接 GATT 服務(wù)然后通過特征值Characteristic讀寫。配對(duì)失敗的報(bào)錯(cuò)在經(jīng)典藍(lán)牙里非常常見而 BLE 里根本沒有“配對(duì)”這個(gè)概念取而代之的是連接參數(shù)協(xié)商和 MTU 協(xié)商。如果你拿到的源碼是 BLE 的卻在翻“配對(duì)回調(diào)”說明你還沒把協(xié)議模型轉(zhuǎn)換過來。2.2 一份可用的藍(lán)牙源碼工程里該有哪些模塊拿到一套藍(lán)牙源碼不用急著逐行讀。先看它有沒有把功能拆成模塊。一個(gè)可維護(hù)的藍(lán)牙工程至少應(yīng)該包含初始化、掃描、連接、數(shù)據(jù)收發(fā)、服務(wù)解析、狀態(tài)回調(diào)這六個(gè)部分。我習(xí)慣把它們列成一張對(duì)照表來快速對(duì)號(hào)入座模塊職責(zé)關(guān)鍵類初始化檢查硬件、權(quán)限、藍(lán)牙開關(guān)狀態(tài)BluetoothAdapter, BluetoothManager掃描發(fā)現(xiàn)周邊設(shè)備區(qū)分經(jīng)典藍(lán)牙與 BLEBluetoothAdapter.startDiscovery / BluetoothLeScanner連接管理建立并維護(hù)連接持有連接狀態(tài)BluetoothSocket / BluetoothGatt數(shù)據(jù)收發(fā)收發(fā)數(shù)據(jù)處理粘包與分包InputStream / OutputStream / GattCallback服務(wù)解析解析 BLE 服務(wù)與特征值BluetoothGattService / BluetoothGattCharacteristic狀態(tài)回調(diào)向 UI 層通知連接狀態(tài)變化Handler / LiveData / 接口回調(diào)如果一份源碼里找不到獨(dú)立的掃描模塊多半是把掃描邏輯直接塞進(jìn)了 Activity這種結(jié)構(gòu)改起來成本很高設(shè)備一多就亂成一鍋粥。我更在意的其實(shí)不是它的包名是否華麗而是掃描、連接、收發(fā)這三件事有沒有解耦。三者獨(dú)立之后后面你想從經(jīng)典藍(lán)牙切到 BLE或者換一個(gè)對(duì)端設(shè)備型號(hào)改動(dòng)范圍能被限制在一個(gè)模塊內(nèi)。模塊劃分還有一個(gè)現(xiàn)實(shí)價(jià)值藍(lán)牙連接經(jīng)常是異步的回調(diào)滿天飛。如果所有邏輯都堆在 Activity 里配置變更旋轉(zhuǎn)屏幕時(shí)回調(diào)就會(huì)崩或泄漏。把連接和掃描放到 ViewModel 或獨(dú)立的單例管理器里持有 ApplicationContext是規(guī)避這類問題的常見且有效做法。2.3 拿到一份源碼后先看哪幾個(gè)文件按下面這個(gè)順序讀半小時(shí)內(nèi)基本能判斷一套源碼靠不靠譜。首先打開 AndroidManifest.xml看藍(lán)牙相關(guān)權(quán)限是否齊全是否適配了 Android 12API 31之后的運(yùn)行時(shí)權(quán)限拆分。很多老源碼在高版本設(shè)備上直接崩就是因?yàn)闆]適配 BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 的動(dòng)態(tài)申請。接著看藍(lán)牙適配器的初始化位置。最規(guī)范的寫法是通過 BluetoothManager 拿 BluetoothAdapter這樣能準(zhǔn)確拿到系統(tǒng)藍(lán)牙服務(wù)的狀態(tài)。如果源碼里直接用BluetoothAdapter.getDefaultAdapter()也不是不行但你在新設(shè)備上要留意這個(gè)接口是否被系統(tǒng)標(biāo)記為過時(shí)或受限。再看設(shè)備掃描的回調(diào)實(shí)現(xiàn)。經(jīng)典藍(lán)牙用的是 BroadcastReceiver 接收 ACTION_FOUNDBLE 用的是 ScanCallback。重點(diǎn)看回調(diào)里是按設(shè)備名做字符串匹配還是結(jié)合信號(hào)強(qiáng)度做過濾。直接拿設(shè)備名做模糊匹配的源碼在設(shè)備密集的環(huán)境里基本不能用。最后看連接的建立與斷開邏輯。經(jīng)典藍(lán)牙看 Socket 是否在子線程創(chuàng)建、是否有超時(shí)控制BLE 看 onConnectionStateChange 里的斷線處理是否完整。很多源碼只寫了連接成功和失敗沒有重連邏輯這種工程連上線都會(huì)斷交付時(shí)必被挑戰(zhàn)。3. 把藍(lán)牙源碼跑通最小工程與調(diào)用鏈拆解3.1 權(quán)限聲明與藍(lán)牙適配器初始化權(quán)限是第一道門檻也是翻車率最高的地方。Android 12API 31之后藍(lán)牙權(quán)限被拆成 BLUETOOTH_SCAN、BLUETOOTH_CONNECT、BLUETOOTH_ADVERTISE 三個(gè)運(yùn)行時(shí)權(quán)限而 Android 11 及以下用的是 BLUETOOTH 和 BLUETOOTH_ADMIN另外定位權(quán)限對(duì) BLE 掃描結(jié)果有直接影響。下面這段 Manifest 聲明是我在新項(xiàng)目里一直沿用的兼容寫法!-- Android 12 -- uses-permission android:nameandroid.permission.BLUETOOTH_SCAN android:usesPermissionFlagsneverForLocation / uses-permission android:nameandroid.permission.BLUETOOTH_CONNECT / uses-permission android:nameandroid.permission.BLUETOOTH_ADVERTISE / !-- Android 11 及以下 -- uses-permission android:nameandroid.permission.BLUETOOTH android:maxSdkVersion30 / uses-permission android:nameandroid.permission.BLUETOOTH_ADMIN android:maxSdkVersion30 / uses-permission android:nameandroid.permission.ACCESS_FINE_LOCATION android:maxSdkVersion30 /usesPermissionFlagsneverForLocation表示不會(huì)用藍(lán)牙掃描結(jié)果做定位這在應(yīng)用市場審核時(shí)能降低權(quán)限敏感度。但如果你的應(yīng)用確實(shí)需要根據(jù)藍(lán)牙信號(hào)推算位置這句就不要加否則功能會(huì)受限。maxSdkVersion30的作用是讓舊權(quán)限只在 Android 11 及以下生效避免高版本系統(tǒng)重復(fù)請求舊權(quán)限。適配器初始化我推薦用 BluetoothManager 的方式代碼更穩(wěn)// BluetoothManager 方式獲取適配器兼容性更好 BluetoothManager manager (BluetoothManager) getSystemService(Context.BLUETOOTH_SERVICE); BluetoothAdapter adapter manager.getAdapter(); if (adapter null) { // 設(shè)備不支持藍(lán)牙直接停止后續(xù)流程 return; } if (!adapter.isEnabled()) { // 先發(fā)系統(tǒng) Intent 請求用戶打開藍(lán)牙而不是強(qiáng)制 enable Intent enableBtIntent new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE); startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT); }manager.getAdapter()在系統(tǒng)藍(lán)牙服務(wù)異常重啟后能重新拿到有效實(shí)例而getDefaultAdapter()在某些定制 ROM 上會(huì)返回一個(gè)不可用的空殼對(duì)象。這里沒有直接用adapter.enable()是因?yàn)槟鞘欠瓷湎到y(tǒng)接口部分廠商 ROM 會(huì)攔截而且系統(tǒng)會(huì)彈權(quán)限確認(rèn)框不做用戶確認(rèn)直接開藍(lán)牙不符合交互規(guī)范。運(yùn)行時(shí)權(quán)限請求建議把三個(gè)藍(lán)牙權(quán)限和定位權(quán)限放在一次請求里完成用戶只需要做一次授權(quán)操作體驗(yàn)會(huì)好很多。注意Android 13 及以上即使動(dòng)態(tài)權(quán)限都給了系統(tǒng)設(shè)置里“附近設(shè)備”權(quán)限開關(guān)如果被用戶手動(dòng)關(guān)閉BLE 掃描仍然會(huì)靜默失敗。這個(gè)開關(guān)藏得很深遇到掃描不到設(shè)備時(shí)要去檢查。3.2 設(shè)備掃描回調(diào)、過濾與掃描周期BLE 掃描的推薦做法是用 BluetoothLeScanner掃描回調(diào)的觸發(fā)頻率可以很高必須做過濾和去重。下面是一個(gè)帶信號(hào)強(qiáng)度過濾的掃描實(shí)現(xiàn)能有效避免掃描列表被遠(yuǎn)處設(shè)備刷屏private MapString, BluetoothDevice deviceMap new HashMap(); private ListBluetoothDevice deviceList new ArrayList(); private ScanCallback scanCallback new ScanCallback() { Override public void onScanResult(int callbackType, ScanResult result) { BluetoothDevice device result.getDevice(); String name device.getName(); int rssi result.getRssi(); // 信號(hào)強(qiáng)度低于 -85dBm 的設(shè)備直接忽略減少列表干擾 if (rssi -85) { return; } // 按設(shè)備地址去重避免同一設(shè)備在回調(diào)中反復(fù)出現(xiàn) if (!deviceMap.containsKey(device.getAddress())) { deviceMap.put(device.getAddress(), device); deviceList.add(device); // 回到主線程更新 UI 列表 runOnUiThread(() - adapter.notifyItemInserted(deviceList.size() - 1)); } } }; private void startBleScan() { BluetoothLeScanner scanner BluetoothAdapter.getDefaultAdapter().getBluetoothLeScanner(); if (scanner null) { // 當(dāng)前設(shè)備不支持 BLE 掃描提示用戶換設(shè)備 return; } ScanFilter filter new ScanFilter.Builder() .setDeviceName(MyDevice) // 按廣播名精確過濾 .build(); ScanSettings settings new ScanSettings.Builder() .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY) // 高頻率掃描 .setReportDelay(0) // 實(shí)時(shí)上報(bào)不做批量延遲 .build(); scanner.startScan(filter, settings, scanCallback); }ScanFilter能按設(shè)備名或服務(wù) UUID 過濾能顯著減少回調(diào)次數(shù)。但按設(shè)備名過濾的前提是廣播名穩(wěn)定有些設(shè)備會(huì)在名稱后面加隨機(jī)后綴用setDeviceName就會(huì)漏掉。遇到這種對(duì)端我建議要么去掉過濾器要么按服務(wù) UUID 過濾。setScanMode有兩檔最常用LOW_LATENCY 延遲最低但耗電高適合用戶停留在掃描頁的場景LOW_POWER 適合后臺(tái)掃描但發(fā)現(xiàn)速度慢很多。setReportDelay(0)表示實(shí)時(shí)回調(diào)如果設(shè)成大于 0 的值系統(tǒng)會(huì)積攢一批結(jié)果一起返回這個(gè)對(duì) UI 列表刷新并不友好。經(jīng)典藍(lán)牙掃描走的是startDiscovery加廣播接收器。需要注意的是startDiscovery是全局掃描會(huì)掃描所有經(jīng)典藍(lán)牙設(shè)備而且掃描期間會(huì)干擾已經(jīng)建立的藍(lán)牙連接在低端設(shè)備上尤其明顯。我的習(xí)慣是只在用戶主動(dòng)點(diǎn)擊“搜索”時(shí)啟動(dòng)掃描到目標(biāo)設(shè)備立刻cancelDiscovery()不要讓掃描在后臺(tái)持續(xù)運(yùn)行。3.3 建立連接與數(shù)據(jù)收發(fā)Socket 與 GATT 兩條路線經(jīng)典藍(lán)牙的連接必須在子線程里做connect()是阻塞調(diào)用而且沒有內(nèi)置超時(shí)。部分設(shè)備響應(yīng)慢連接可能拖十幾秒。下面這段代碼把連接放到單線程池并依賴外層做超時(shí)控制private void connectClassic(BluetoothDevice device) { ExecutorService executor Executors.newSingleThreadExecutor(); executor.execute(() - { try { // 創(chuàng)建 Socket使用 SPP 服務(wù) UUID經(jīng)典藍(lán)牙串口通用值 BluetoothSocket socket device.createRfcommSocketToServiceRecord( UUID.fromString(00001101-0000-1000-8000-00805F9B34FB)); // 連接前主動(dòng)取消掃描避免掃描干擾連接建立 bluetoothAdapter.cancelDiscovery(); // 阻塞調(diào)用建議用 Future.get(timeout) 包裝做超時(shí) socket.connect(); InputStream in socket.getInputStream(); OutputStream out socket.getOutputStream(); // 啟動(dòng)獨(dú)立讀線程持續(xù)讀取對(duì)端數(shù)據(jù) readLoop(in); } catch (IOException e) { // 連接失敗記錄日志并觸發(fā)重試或提示用戶 e.printStackTrace(); } }); }createRfcommSocketToServiceRecord的第一個(gè)參數(shù)是服務(wù) UUID。SPP 的通用 UUID 是00001101-0000-1000-8000-00805F9B34FB絕大多數(shù)藍(lán)牙串口設(shè)備都認(rèn)這個(gè)值。但如果你的對(duì)端是定制硬件就需要查閱設(shè)備文檔確認(rèn) UUID 是否不同。connect()成功后讀寫操作都在各自的線程里完成不能把讀線程和 UI 線程混在一起。BLE 的代碼風(fēng)格完全相反。Gatt 是異步的連接結(jié)果、服務(wù)發(fā)現(xiàn)結(jié)果、數(shù)據(jù)通知全部通過BluetoothGattCallback回調(diào)返回。下面是連接加訂閱通知的完整流程private BluetoothGatt gatt; private final BluetoothGattCallback gattCallback new BluetoothGattCallback() { Override public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) { if (newState BluetoothProfile.STATE_CONNECTED) { // 連接成功開始發(fā)現(xiàn)服務(wù) gatt.discoverServices(); } else if (newState BluetoothProfile.STATE_DISCONNECTED) { // 連接斷開在這里做重連或通知上層 } } Override public void onServicesDiscovered(BluetoothGatt gatt, int status) { if (status ! BluetoothGatt.GATT_SUCCESS) { // 服務(wù)發(fā)現(xiàn)失敗關(guān)閉連接并重試 gatt.disconnect(); gatt.close(); return; } // 按協(xié)議文檔里的 UUID 查找服務(wù)和特征值 BluetoothGattService service gatt.getService(serviceUuid); if (service null) { return; } BluetoothGattCharacteristic characteristic service.getCharacteristic(charUuid); // 啟用通知讓設(shè)備可以主動(dòng)推送數(shù)據(jù) gatt.setCharacteristicNotification(characteristic, true); // 有些設(shè)備還必須寫描述符 CCCD 才能收到通知 BluetoothGattDescriptor descriptor characteristic.getDescriptor( UUID.fromString(00002902-0000-1000-8000-00805F9B34FB)); if (descriptor ! null) { descriptor.setValue(BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE); gatt.writeDescriptor(descriptor); } } Override public void onCharacteristicChanged(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic) { byte[] data characteristic.getValue(); // 對(duì)端設(shè)備推送的數(shù)據(jù)在這里處理不能做耗時(shí)操作 } }; private void connectBle(BluetoothDevice device) { // autoConnect 用 false主動(dòng)連接速度更快 gatt device.connectGatt(context, false, gattCallback); }connectGatt的autoConnect參數(shù)值得單獨(dú)說。false是主動(dòng)連接速度快適合用戶點(diǎn)擊連接按鈕的場景true是讓系統(tǒng)在后臺(tái)監(jiān)測到設(shè)備可用時(shí)自動(dòng)連接適合“靠近就自動(dòng)連”的場景但首次連接很慢部分設(shè)備固件還不支持。我?guī)缀跞胒alse然后自己做重連策略這樣時(shí)序是可控的。setCharacteristicNotification之后很多設(shè)備還必須寫描述符 0x2902CCCD否則數(shù)據(jù)不會(huì)推送上來。這是 BLE 開發(fā)里最容易漏掉的一步漏掉的表現(xiàn)就是連接正常、服務(wù)發(fā)現(xiàn)正常但onCharacteristicChanged永遠(yuǎn)不觸發(fā)。3.4 數(shù)據(jù)收發(fā)緩沖與線程模型藍(lán)牙數(shù)據(jù)沒有理想的包邊界。經(jīng)典藍(lán)牙的 InputStream 是字節(jié)流你不知道一幀數(shù)據(jù)在哪里結(jié)束BLE 的onCharacteristicChanged每次回調(diào)是一個(gè)特征值的數(shù)據(jù)包但如果特征值超過 MTU對(duì)端會(huì)把它拆成多個(gè)包依次推送。應(yīng)用層必須自己維護(hù)一個(gè)累積緩沖來做粘包和分包處理。常用的做法是維護(hù)一個(gè) ByteArrayOutputStream把每個(gè) chunk 寫入再按自定義的幀協(xié)議去判斷哪些是完整的包、哪些還差數(shù)據(jù)。幀協(xié)議一般就是包頭、長度、負(fù)載、校驗(yàn)這個(gè)套路。比如你規(guī)定幀以 0xAA 0x55 開頭以 0x0D 0x0A 結(jié)尾那應(yīng)用層的處理邏輯就是先把數(shù)據(jù)塞進(jìn) buffer然后循環(huán)檢查 buffer 里是否有完整的幀有就提取出來處理剩下的殘留在 buffer 里等下一個(gè) chunk 湊齊。沒有協(xié)議文檔的話可以抓一段對(duì)端的日志統(tǒng)計(jì)一組完整數(shù)據(jù)的長度和起止標(biāo)志用啟發(fā)式方式找邊界。這個(gè)過程是藍(lán)牙開發(fā)里最耗時(shí)、也最容易讓開發(fā)者產(chǎn)生“數(shù)據(jù)對(duì)不對(duì)得上”困惑的地方值得多投入時(shí)間驗(yàn)證。線程模型方面原則只有一條藍(lán)牙回調(diào)線程不碰 UI。經(jīng)典藍(lán)牙的讀線程在子線程BLE 的回調(diào)運(yùn)行在系統(tǒng) Binder 線程都不能直接更新界面。用 Handler 或 LiveData 把數(shù)據(jù)切到主線程。另外onCharacteristicChanged回調(diào)頻率可能很高如果在這里做耗時(shí)的業(yè)務(wù)處理會(huì)拖慢整個(gè)藍(lán)牙消息隊(duì)列導(dǎo)致后續(xù)數(shù)據(jù)包丟失這點(diǎn)在高頻推送場景下尤其要留心。4. 源碼改造時(shí)最容易翻車的配置項(xiàng)UUID、掃描周期與重連策略4.1 UUID 不一致連接失敗的第一大原因UUID 是藍(lán)牙開發(fā)里出問題最多的配置項(xiàng)。經(jīng)典藍(lán)牙里創(chuàng)建 Socket 用的 UUID 必須與對(duì)端設(shè)備監(jiān)聽的服務(wù) UUID 一致BLE 里GATT 服務(wù) UUID、特征值 UUID 必須與設(shè)備廣播的完全一致。UUID 是 128 位的十六進(jìn)制字符串形如00001101-0000-1000-8000-00805F9B34FB但不同設(shè)備文檔的寫法差別很大有的省略前導(dǎo)零有的把廠商自定義段放在中間一不留神就配錯(cuò)。我的經(jīng)驗(yàn)是拿到設(shè)備文檔后先把所有 UUID 整理到一個(gè)常量類里逐個(gè)對(duì)照格式補(bǔ)全成完整的 128 位字符串。BIG 需要注意的是大小寫不敏感但連字符位置必須正確有些框架層會(huì)做格式化但你自己手寫的字符串不一致就會(huì)失敗。另外一個(gè)常用手段是先用成熟的 BLE 調(diào)試工具連接設(shè)備查看它實(shí)際廣播的服務(wù)和特征值列表再和源碼里的常量逐個(gè)比對(duì)能快速定位寫錯(cuò)的位置。注意調(diào)試工具連過的設(shè)備會(huì)在系統(tǒng)層留下緩存同一臺(tái)設(shè)備在應(yīng)用里連接時(shí)可能被系統(tǒng)返回舊緩存遇到這種情況要把設(shè)備從系統(tǒng)藍(lán)牙設(shè)置里移除再測試。4.2 掃描周期與服務(wù)發(fā)現(xiàn)時(shí)序回調(diào)沒觸發(fā)時(shí)先看時(shí)序掃描周期的設(shè)置直接影響兩個(gè)體驗(yàn)設(shè)備出現(xiàn)速度和耗電。持續(xù)以 LOW_LATENCY 模式掃描手機(jī)發(fā)熱和耗電都會(huì)明顯上升尤其在掃描列表頁面長時(shí)間停留的場景。我一般把掃描拆成“掃描 6 秒、停 3 秒”的循環(huán)來平衡功耗和發(fā)現(xiàn)速度。注意停掃描時(shí)要傳入同一個(gè)scanCallback實(shí)例不要傳 null傳 null 是全局停止會(huì)把其他模塊發(fā)起的掃描也停掉。服務(wù)發(fā)現(xiàn)時(shí)序的問題也很典型。很多源碼在onConnectionStateChange里調(diào)用discoverServices()之后就立刻去getService()但onServicesDiscovered可能幾百毫秒后才回調(diào)。這時(shí)拿到的 service 是 null代碼就崩了或者靜默失敗。正確做法是在onServicesDiscovered回調(diào)里去獲取服務(wù)和特征值而不是在連接成功的回調(diào)里急著取。還有一類廠商設(shè)備的行為比較特殊連接成功后不會(huì)立刻響應(yīng)服務(wù)發(fā)現(xiàn)需要先往某個(gè)特征值寫一個(gè)喚醒命令然后等 200 毫秒左右再調(diào)discoverServices()才會(huì)正常完成服務(wù)枚舉。如果你發(fā)現(xiàn)設(shè)備用通用工具一切正常、自己的代碼卻卡在服務(wù)發(fā)現(xiàn)階段可以先試試延遲觸發(fā)discoverServices()這個(gè)經(jīng)驗(yàn)我在實(shí)際項(xiàng)目里驗(yàn)證過多次。4.3 重連策略與系統(tǒng)藍(lán)牙緩存斷線重連不是簡單重調(diào) connect很多人在連接斷開后直接調(diào)用之前的connectGatt或socket.connect()結(jié)果要么連不上要么連上后行為異常。這個(gè)問題多半落在系統(tǒng)藍(lán)牙緩存和資源未清理上。BLE 斷線重連的正確姿勢是private void reconnectBle(BluetoothDevice device) { if (gatt ! null) { // 先斷開再關(guān)閉釋放底層資源 gatt.disconnect(); gatt.close(); gatt null; } // 必須用新的 connectGatt 重新建立連接 gatt device.connectGatt(context, false, gattCallback); }gatt.disconnect()和gatt.close()的順序不能反。先斷開連接再釋放資源。如果跳過close()系統(tǒng)底層會(huì)保留一個(gè) GATT 客戶端實(shí)例下一次connectGatt很容易失敗或串線。這是 BLE 資源管理里最重要的一步。經(jīng)典藍(lán)牙的 Socket 也一樣一個(gè)BluetoothSocket對(duì)象成功connect()一次之后再斷開不能復(fù)用第二次。重連時(shí)必須重新createRfcommSocketToServiceRecord()創(chuàng)建新 Socket舊對(duì)象直接close()。如果代碼里復(fù)用了同一個(gè) Socket 對(duì)象第二次連接大概率拋異?；蚩ㄋ馈＝?jīng)典藍(lán)牙的重連流程必須是“新建 Socket → 連接 → 使用 → 關(guān)閉 → 新建”沒有捷徑。系統(tǒng)藍(lán)牙緩存的另外一個(gè)表現(xiàn)是設(shè)備改了廣播名或服務(wù) UUID但手機(jī)掃到的還是舊的。這是系統(tǒng)級(jí)緩存應(yīng)用層控制不了只能引導(dǎo)用戶在系統(tǒng)藍(lán)牙設(shè)置里取消配對(duì)后重新掃描。你的代碼里能做的就是盡量保持設(shè)備端廣播的 UUID 和名稱穩(wěn)定從源頭減少緩存導(dǎo)致的幽靈數(shù)據(jù)問題。5. Android 藍(lán)牙開發(fā)避坑指南五條高頻踩坑記錄5.1 坑一權(quán)限聲明了但一啟動(dòng)就崩潰現(xiàn)象AndroidManifest.xml 里權(quán)限一個(gè)不少運(yùn)行在 Android 12 以上設(shè)備仍然崩潰日志報(bào) SecurityException 或 MissingPermission。原因targetSdkVersion 在 31 以上時(shí)BLUETOOTH_SCAN 和 BLUETOOTH_CONNECT 屬于運(yùn)行時(shí)權(quán)限必須在代碼里動(dòng)態(tài)申請。只寫在 Manifest 里等于沒寫。另一個(gè)隱蔽點(diǎn)部分廠商 ROM 在 targetSdkVersion 30 及以下也會(huì)強(qiáng)制要求動(dòng)態(tài)申請否則直接不給權(quán)限。解決在啟動(dòng)流程中先判斷 SDK 版本31 及以上請求三個(gè)藍(lán)牙權(quán)限30 及以下請求定位權(quán)限。用ActivityResultContracts.RequestMultiplePermissions統(tǒng)一管理授權(quán)結(jié)果。同時(shí)檢查系統(tǒng)設(shè)置里“附近設(shè)備”權(quán)限開關(guān)是否開啟這個(gè)開關(guān)與運(yùn)行時(shí)權(quán)限是獨(dú)立的用戶關(guān)掉后任何掃描和連接 API 都會(huì)靜默失敗。5.2 坑二掃描回調(diào)一直不觸發(fā)掃描列表永遠(yuǎn)為空現(xiàn)象代碼完全照著官方文檔寫但onScanResult一次都沒被調(diào)用?；蛘邟呙璧搅嗽O(shè)備但列表里只出現(xiàn)一兩個(gè)離得近的設(shè)備反而不出現(xiàn)。原因最常見的是系統(tǒng)“附近設(shè)備”權(quán)限被關(guān)閉掃描 API 被靜默攔截不報(bào)任何錯(cuò)誤。其次是 ScanFilter 配置過嚴(yán)比如setDeviceName拼錯(cuò)、服務(wù) UUID 和設(shè)備廣播不一致過濾后把目標(biāo)設(shè)備也濾掉了。還有一種情況是上一次stopScan沒正常執(zhí)行新的startScan不會(huì)有回調(diào)。解決先用最寬松的方式測試不傳任何 Filter直接scanner.startScan(callback)。回調(diào)能觸發(fā)就說明過濾條件有問題逐個(gè)把條件加回去排查?；卣{(diào)仍不觸發(fā)就去檢查系統(tǒng)權(quán)限和位置服務(wù)開關(guān)。另外 Android 13 以上定位服務(wù)開關(guān)關(guān)閉也會(huì)導(dǎo)致 BLE 掃描不到設(shè)備這個(gè)要準(zhǔn)備在文檔里寫清楚否則用戶會(huì)認(rèn)為軟件有問題。5.3 坑三BLE 連接成功后立刻斷連狀態(tài)碼是 133現(xiàn)象onConnectionStateChange先收到 STATE_CONNECTED不到一秒又收到 STATE_DISCONNECTEDstatus 值是 133GATT_ERROR。原因133 表示底層 GATT 連接出錯(cuò)。常見原因有上一次連接沒有close()舊實(shí)例還占著資源兩個(gè)應(yīng)用同時(shí)連接同一臺(tái) BLE 設(shè)備設(shè)備端主動(dòng)斷開。還有一個(gè)容易被低估的原因是 MTU 協(xié)商不成功部分老固件不支持高 MTU超出范圍會(huì)直接斷開連接。解決先檢查代碼里是否在每次連接前都調(diào)用了close()處理舊連接。然后排除多應(yīng)用干擾把系統(tǒng)藍(lán)牙設(shè)置里所有配對(duì)設(shè)備取消關(guān)掉其他使用藍(lán)牙的應(yīng)用再測試。MTU 問題用gatt.requestMtu(247)時(shí)注意捕獲結(jié)果回調(diào)不要假設(shè)一定成功。如果設(shè)備固件不支持高 MTU應(yīng)用層仍要按 20 字節(jié)分包處理數(shù)據(jù)。5.4 坑四多設(shè)備并發(fā)連接時(shí)數(shù)據(jù)竄了現(xiàn)象同時(shí)連接多臺(tái)設(shè)備A 設(shè)備的數(shù)據(jù)跑到了 B 設(shè)備的回調(diào)里斷開 A 設(shè)備后 B 設(shè)備也跟著斷了。原因如果多個(gè)連接共用一個(gè)BluetoothGattCallback所有設(shè)備的回調(diào)都會(huì)進(jìn)同一個(gè)實(shí)例?；卣{(diào)方法里的gatt參數(shù)能區(qū)分設(shè)備但很多源碼直接忽略這個(gè)參數(shù)數(shù)據(jù)自然就竄了。還有更糟的情況多個(gè)連接共用一個(gè)BluetoothGatt實(shí)例系統(tǒng)會(huì)返回同一個(gè)已存在的對(duì)象設(shè)備之間互相干擾。解決每個(gè)設(shè)備使用獨(dú)立的BluetoothGatt實(shí)例回調(diào)里用gatt.getDevice().getAddress()區(qū)分設(shè)備維護(hù)一個(gè)MapdeviceAddress, BluetoothGatt。處理數(shù)據(jù)時(shí)始終攜帶設(shè)備地址上下文不要只把 byte[] 傳給上層。并發(fā)連接數(shù)也有限制手機(jī)硬件雖然支持多個(gè) BLE 連接但實(shí)際項(xiàng)目中連接超過三個(gè)就會(huì)出現(xiàn)不穩(wěn)定不要設(shè)計(jì)成大規(guī)模一對(duì)多并發(fā)。5.5 坑五設(shè)備端固件不支持 MTU 協(xié)商數(shù)據(jù)包被靜默吞掉現(xiàn)象連接一切正常服務(wù)發(fā)現(xiàn)也成功應(yīng)用寫入大塊數(shù)據(jù)也不報(bào)錯(cuò)但對(duì)端就是沒有響應(yīng)。日志里看不到任何異常似乎數(shù)據(jù)發(fā)出去就消失了。原因應(yīng)用主動(dòng)requestMtu(247)但設(shè)備固件協(xié)商失敗后靜默退回默認(rèn) MTU一般是 23 字節(jié)。應(yīng)用層還按照擴(kuò)展 MTU 一次性寫入了超過 20 字節(jié)的數(shù)據(jù)包底層把超長部分丟掉造成數(shù)據(jù)靜默丟失。解決在onMtuChanged回調(diào)里確認(rèn)協(xié)商結(jié)果拿到實(shí)際 MTU 值再根據(jù)實(shí)際值調(diào)整每次寫入的字節(jié)數(shù)。不需要強(qiáng)行追求大包應(yīng)用層可以按 20 字節(jié)分包寫入或者等 MTU 協(xié)商成功后再切大包模式。這個(gè)排查動(dòng)作我很早就應(yīng)該做結(jié)果在一個(gè)項(xiàng)目里耗了快一周最后靠協(xié)議日志才發(fā)現(xiàn)設(shè)備端拒絕了 MTU 協(xié)商。6. 強(qiáng)化你的調(diào)試習(xí)慣先抓藍(lán)牙協(xié)議日志再動(dòng)代碼調(diào)試藍(lán)牙源碼光靠 Logcat 里的應(yīng)用日志遠(yuǎn)遠(yuǎn)不夠。很多連接層的異常發(fā)生在系統(tǒng)協(xié)議棧內(nèi)部應(yīng)用層只能看到狀態(tài)的跳變看不到原因。這時(shí)候必須抓系統(tǒng)藍(lán)牙 HCI 日志。開啟方法是在開發(fā)者選項(xiàng)里打開“藍(lán)牙 HCI 信息收集日志”Bluetooth HCI snoop log復(fù)現(xiàn)問題后日志文件會(huì)記錄系統(tǒng)藍(lán)牙協(xié)議棧收發(fā)的所有 HCI 數(shù)據(jù)包。文件通常保存在/data/misc/bluetooth/logs/可以用 adb 導(dǎo)出然后用 Wireshark 的解析工具查看。日志里能看到完整的 ATT/GATT 數(shù)據(jù)包來回記錄比如某個(gè)特征值寫入是否被設(shè)備拒收、連接斷開前底層發(fā)生了什么事件。我的排查習(xí)慣是先看應(yīng)用日志確認(rèn)在哪個(gè)回調(diào)卡住再?zèng)Q定要不要抓 HCI 日志。比如連接斷開在 state133HCI 日志會(huì)顯示底層是否有 Link Loss 事件onCharacteristicChanged收不到數(shù)據(jù)HCI 日志能看出設(shè)備到底有沒有主動(dòng)發(fā) Notification——如果日志里根本沒有設(shè)備發(fā)來的包那問題在對(duì)端如果有包但應(yīng)用沒收到那問題在訂閱 Descriptor 或者 MTU 協(xié)商上。這種定位方式能避免“盲目改代碼然后反復(fù)試”的死循環(huán)。還有一個(gè)更省錢的前置手段在 Logcat 里過濾系統(tǒng)藍(lán)牙日志關(guān)鍵字包括 BluetoothGatt、bt_btif、bt_gatt。系統(tǒng)層很多關(guān)鍵狀態(tài)變化會(huì)打點(diǎn)在這里。配合 Debug.startMethodTracing可以查看藍(lán)牙回調(diào)線程上的耗時(shí)操作。把回調(diào)里的耗時(shí)控制在一毫秒以內(nèi)是避免背靠背數(shù)據(jù)包丟失的前提這在大量數(shù)據(jù)連續(xù)推送時(shí)尤其重要?；仡^再看我調(diào)試過的藍(lán)牙項(xiàng)目花時(shí)間最多的往往不是寫代碼而是定位“誰沒按協(xié)議走”。一開始遇到連接異常就悶頭改業(yè)務(wù)代碼改了兩天發(fā)現(xiàn)根本沒用后來養(yǎng)成先看協(xié)議日志、再動(dòng)代碼的習(xí)慣很多問題一眼就能看到癥結(jié)。如果這篇文章能讓你少走這個(gè)彎路那投入的方向就是對(duì)的。希望你也能養(yǎng)成這個(gè)習(xí)慣——遇到藍(lán)牙異常先抓日志再下結(jié)論。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取