接口總結

正常使用：

1. 初始化（開啟）藍牙模塊wx.openBluetoothAdapter

2. 搜索藍牙設備（消耗大量資源，要及時結束）wx.startBluetoothDevicesDiscovery

3. 結束搜索wx.stopBluetoothDevicesDiscovery

4. 與藍牙設備建立連接wx.createBLEConnection

5. 獲取藍牙設備的服務列表wx.getBLEDeviceServices

6. 獲取藍牙設備的某個服務的特征值列表wx.getBLEDeviceCharacteristics

7. 與特征值通信

   • 啟用/關閉某個特征值的 notify wx.notifyBLECharacteristicValueChange

   • 讀取特征值數據（讀取到的數據通過特征值變化事件返回） wx.readBLECharacteristicValue

   • 向特征值寫入數據wx.writeBLECharacteristicValue

8. 斷開與藍牙設備的連接wx.closeBLEConnection

9. 停用（關閉）藍牙模塊wx.closeBluetoothAdapter

事件監聽：

1. 搜索過程中發現新的藍牙設備wx.onBluetoothDeviceFound

2. 藍牙適配器狀態變化wx.onBluetoothAdapterStateChange

3. 藍牙設備連接狀態變化wx.onBLEConnectionStateChange

4. 特征值變化（需開啟notify）wx.onBLECharacteristicValueChange

其他：

1. 根據uuid獲取已連接的設備wx.getConnectedBluetoothDevices

2. 獲取當前藍牙模塊周期已發現的設備wx.getBluetoothDevices

3. 獲取本機藍牙適配器的狀態wx.getBluetoothAdapterState

踩坑總結

1. 全局

   • 初始化藍牙模塊后才能調用相關API

   • 初始化之前可執行事件監聽，但不會觸發事件回調

   • 初始化后，如果errCode=10001，那么其實此時小程序藍牙模塊已經初始化完成，可以調用API，也會有事件回調。

   • iOS 上由于系統需要獲取特征值實例，必須要調用獲取設備服務和特征值的接口，使用獲取到的serviceId和characteristicId，才能對特征值進行read、write、notify操作

   • Android 上，部分機型獲取設備服務時會多出00001800和00001801UUID的服務，這是系統行為，注意不要使用這兩個服務

   • Android 上獲取到的deviceId為設備 MAC 地址，iOS 上則為設備 UUID

   • iOS 上不同手機搜索到的deviceId是不同的

   • 與藍牙設備通信的 MTU（最大傳輸單元）系統限定為20字節，如果超過則會出錯，這里應該根據藍牙設備協議進行分片傳輸。

   • 特征值的讀寫是二進制數據，ArrayBuffer類型

2. 設備連接

   • 必須成對地調用createBLEConnection和closeBLEConnection接口

   • Android 上，如果連續多次調用createBLEConnection，可能會導致系統持有同一設備多個連接的實例，導致調用 closeBLEConnection 的時候并不能真正地斷開與設備的連接

   • 如果未能及時關閉連接釋放資源，容易導致state 133 GATT ERROR的異常

   • 若小程序在之前已有搜索過某個藍牙設備，并成功建立連接，可直接傳入之前搜索獲取的deviceId直接嘗試連接該設備，無需進行搜索操作

   • 藍牙連接隨時可能斷開，建議監聽wx.onBLEConnectionStateChange回調事件，當藍牙設備斷開時按需執行重連操作

3. 設備搜索

   • iOS里面藍牙狀態變化以后不能馬上開始搜索，否則會搜索不到設備，必須要等待2秒以上

   • Android 上，部分機型無定位權限或者是定位開關未打開時會搜不到設備。原因是藍牙功能是可以獲取到定位的，系統基于安全考量，使用藍牙接口時必須要有定位權限

   • 設備搜索占用大量資源，要及時關閉

   • wx.getBluetoothDevices獲取到的設備列表為藍牙模塊生效期間所有搜索到的藍牙設備

   • 若在藍牙模塊使用流程結束后未及時調用wx.closeBluetoothAdapter釋放資源，那么：

     • 可能不會發現新的設備，因為之前已搜索過

     • 調用wx.getBluetoothDevices時，仍會返回之前的藍牙使用流程中搜索到的藍牙設備，即使設備已經不在用戶身邊，無法連接

   • 藍牙設備在被搜索到時，系統返回的name字段一般為廣播包中的localName字段中的設備名稱，而如果與藍牙設備建立連接，系統返回的name字段會改為從藍牙設備上獲取到的GattName。若需要動態改變設備名稱并展示，建議使用localName字段

4. 向特征值寫入數據

   • 并行調用多次可能會導致寫入失敗

   • 若單次寫入數據過長，iOS 上存在系統不會有任何回調的情況（包括錯誤回調）

   • 特征值必須支持 write

5. 讀取特征值數據

   • 并行調用多次可能會導致讀取失敗

   • 接口讀取到的信息需要在 onBLECharacteristicValueChange 方法注冊的回調中獲取

   • 特征值必須支持 read

6. 啟用/關閉notify

   • 啟用后才會觸發特征值變化

   • 監聽到的消息要進行過濾處理，有些設備會抽風一樣的發送同樣的消息，需要在處理邏輯里面去重

   • 開啟notify以后并不能馬上發送消息，藍牙設備有個準備的過程，需要延遲1秒以上才能發送，否則會發送失敗

   • 特征值必須支持notify或者indicate