接口總結(jié)

正常使用：

1. 初始化（開啟）藍(lán)牙模塊wx.openBluetoothAdapter

2. 搜索藍(lán)牙設(shè)備（消耗大量資源，要及時結(jié)束）wx.startBluetoothDevicesDiscovery

3. 結(jié)束搜索wx.stopBluetoothDevicesDiscovery

4. 與藍(lán)牙設(shè)備建立連接wx.createBLEConnection

5. 獲取藍(lán)牙設(shè)備的服務(wù)列表wx.getBLEDeviceServices

6. 獲取藍(lán)牙設(shè)備的某個服務(wù)的特征值列表wx.getBLEDeviceCharacteristics

7. 與特征值通信

   • 啟用/關(guān)閉某個特征值的 notify wx.notifyBLECharacteristicValueChange

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

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

8. 斷開與藍(lán)牙設(shè)備的連接wx.closeBLEConnection

9. 停用（關(guān)閉）藍(lán)牙模塊wx.closeBluetoothAdapter

事件監(jiān)聽：

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

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

3. 藍(lán)牙設(shè)備連接狀態(tài)變化wx.onBLEConnectionStateChange

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

其他：

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

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

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

踩坑總結(jié)

1. 全局

   • 初始化藍(lán)牙模塊后才能調(diào)用相關(guān)API

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

   • 初始化后，如果errCode=10001，那么其實此時小程序藍(lán)牙模塊已經(jīng)初始化完成，可以調(diào)用API，也會有事件回調(diào)。

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

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

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

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

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

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

2. 設(shè)備連接

   • 必須成對地調(diào)用createBLEConnection和closeBLEConnection接口

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

   • 如果未能及時關(guān)閉連接釋放資源，容易導(dǎo)致state 133 GATT ERROR的異常

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

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

3. 設(shè)備搜索

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

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

   • 設(shè)備搜索占用大量資源，要及時關(guān)閉

   • wx.getBluetoothDevices獲取到的設(shè)備列表為藍(lán)牙模塊生效期間所有搜索到的藍(lán)牙設(shè)備

   • 若在藍(lán)牙模塊使用流程結(jié)束后未及時調(diào)用wx.closeBluetoothAdapter釋放資源，那么：

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

     • 調(diào)用wx.getBluetoothDevices時，仍會返回之前的藍(lán)牙使用流程中搜索到的藍(lán)牙設(shè)備，即使設(shè)備已經(jīng)不在用戶身邊，無法連接

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

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

   • 并行調(diào)用多次可能會導(dǎo)致寫入失敗

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

   • 特征值必須支持 write

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

   • 并行調(diào)用多次可能會導(dǎo)致讀取失敗

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

   • 特征值必須支持 read

6. 啟用/關(guān)閉notify

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

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

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

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