接口總結

正常使用：

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

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

3. 結束搜索wx.stopBluetoothDevicesDiscovery

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

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

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

7. 與特征值通信

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

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

   • 向特征值寫入數(shù)據(jù)wx.writeBLECharacteristicValue

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

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

事件監(jiān)聽：

1. 搜索過程中發(fā)現(xiàn)新的藍牙設備wx.onBluetoothDeviceFound

2. 藍牙適配器狀態(tài)變化wx.onBluetoothAdapterStateChange

3. 藍牙設備連接狀態(tài)變化wx.onBLEConnectionStateChange

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

其他：

1. 根據(jù)uuid獲取已連接的設備wx.getConnectedBluetoothDevices

2. 獲取當前藍牙模塊周期已發(fā)現(xiàn)的設備wx.getBluetoothDevices

3. 獲取本機藍牙適配器的狀態(tài)wx.getBluetoothAdapterState

踩坑總結

1. 全局

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

   • 初始化之前可執(zhí)行事件監(jiān)聽，但不會觸發(fā)事件回調

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

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

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

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

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

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

   • 特征值的讀寫是二進制數(shù)據(jù)，ArrayBuffer類型

2. 設備連接

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

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

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

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

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

3. 設備搜索

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

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

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

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

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

     • 可能不會發(fā)現(xiàn)新的設備，因為之前已搜索過

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

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

4. 向特征值寫入數(shù)據(jù)

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

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

   • 特征值必須支持 write

5. 讀取特征值數(shù)據(jù)

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

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

   • 特征值必須支持 read

6. 啟用/關閉notify

   • 啟用后才會觸發(fā)特征值變化

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

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

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