藍牙-低功耗中心設備

writeBLECharacteristicValue

TIP

該API使用方法為： wx.writeBLECharacteristicValue(Object object)

TIP

• 並行調用多次會存在寫失敗的可能性。
• 小程序不會對寫入數据包大小做限制，但系統與藍牙設備會限制藍牙4.0單次傳輸的數據大小，超過最大位元組數後會發生寫入錯誤，建議每次寫入不超過20位元組。
• 若單次寫入數據過長，iOS上存在系統不會有任何回檔的情况（包括錯誤回檔）。
• Android平臺上，在調用 wx.notifyBLECharacteristicValueChange 成功後立即調用本接口，在部分機型上會發生10008系統錯誤

• 功能說明： 向藍牙低功耗設備特徵值中寫入二進位數據 ，必須設備的特徵支持write才可以成功調用

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  serviceId	number	-	是	藍牙特徵對應服務的UUID
  characteristicId	boolean	-	是	藍牙特徵的UUID
  value	string	-	是	藍牙設備特徵對應的二進位值
  writeType	string	-	否	藍牙特徵值的寫模式設定，有兩種模式，iOS優先write，Android優先writeNoResponse。 合法值為： 1.write: 強制回復寫，不支持時報錯 2.writeNoResponse: 強制無回復寫，不支持時報錯
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

// Transmit a hexadecimal data of 0x00 to the Bluetooth device.
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)

wx.writeBLECharacteristicValue({
  // The deviceId here must be obtained through the getBluetoothDevices or onBluetoothDeviceFound interfaces.
  deviceId,
  // The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
  serviceId,
  // The CharacteristicId Here must be obtained from the getBLEDeviceCharacteristics interface.
  characteristicId,
  // The value here is of ArrayBuffer type.
  value: buffer,
  success (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

readBLECharacteristicValue

TIP

該API使用方法為： wx.readBLECharacteristicValue(Object object)

TIP

• 並行調用多次會存在讀失敗的可能性
• 接口讀取到的資訊需要在 wx.onBLECharacteristicValueChange 方法注册的回檔中獲取

• 功能說明： 讀取藍牙低功耗設備特徵值的二進位數據 ，必須設備的特徵支持read才可以成功調用

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  serviceId	string	-	是	藍牙特徵對應服務的UUID
  characteristicId	string	-	是	藍牙特徵的UUID
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

// Retrieval is only possible in this callback.
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value comed:', characteristic)
})

wx.readBLECharacteristicValue({
  // The deviceId here must have already established a link with the corresponding device through createBLEConnection.
  deviceId,
  // The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
  serviceId,
  // The CharacteristicId Here Must be Retrieved from the getBLEDeviceCharacteristics Interface
  characteristicId,
  success (res) {
    console.log('readBLECharacteristicValue:', res.errCode)
  }
})

setBLEMTU

TIP

該API使用方法為： wx.setBLEMTU(Object object)

• 功能說明： 協商設定藍牙低功耗的最大傳輸單元（Maximum Transmission Unit，MTU）。 需在 wx.createBLEConnection 調用成功後調用。 僅Android系統5.1以上版本有效，iOS因系統限制不支持

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  mtu	number	-	是	最大傳輸單元。 設定範圍為（22512）區間內，單位bytes
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• object.success回呼函數參數： Object res。

  内容	類型	說明
  mtu	number	最終協商的MTU值，與傳入參數一致。 Android用戶端8.0.9開始支持

getBLEMTU

TIP

該API使用方法為： wx.getBLEMTU(Object object)

TIP

• 小程序中MTU為ATT_MTU，包含Op-Code和Attribute Handle的長度，實際可以傳輸的數據長度為ATT_MTU - 3。
• iOS系統中MTU為固定值； Android系統中，MTU會在系統協商成功之後發生改變，建議使用 wx.onBLEMTUChange 監聽。

• 功能說明： 獲取藍牙低功耗的最大傳輸單元，需在 wx.createBLEConnection 調用成功後調用。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  writeType	string	write	是	寫模式（iOS特有參數），合法值為： 1.write: 有回復寫 1.writeNoResponse: 無回複寫
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• object.success回呼函數參數： Object res。

  内容	類型	說明
  mtu	number	最大傳輸單元

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

wx.getBLEMTU({
  deviceId: '',
  writeType: 'write',
  success (res) {
    console.log(res)
  }
})

onBLEMTUChange

TIP

該API使用方法為： wx.onBLEMTUChange(function listener)

• 功能說明： 監聽藍牙低功耗的最大傳輸單元變化事件（僅Android觸發）

• 參數及說明： function listener，藍牙低功耗的最大傳輸單元變化事件的監聽函數，參數Object res如下：

  内容	類型	說明
  deviceId	string	最大傳輸單元
  mtu	number	最大傳輸單元

• 示例代碼：

wx.onBLEMTUChange(function (res) {
  console.log('bluetooth mtu is', res.mtu)
})

offBLEMTUChange

TIP

該API使用方法為： wx.offBLEMTUChange(function listener)

• 功能說明： 移除藍牙低功耗的最大傳輸單元變化事件的監聽函數

• 參數及說明： function listener，onBLEMTUChange傳入的監聽函數。 不傳此參數則移除所有監聽函數

• 示例代碼：

const listener = function (res) { console.log(res) }

wx.onBLEMTUChange(listener)
wx.offBLEMTUChange(listener) // Pass the same function object used for listening.

onBLEConnectionStateChange

TIP

該API使用方法為： wx.onBLEConnectionStateChange(function listener)

• 功能說明： 監聽藍牙低功耗連接狀態改變事件。 包括開發者主動連接或斷開連接，設備遺失，連接异常斷開等

• 參數及說明： function listener，藍牙低功耗連接狀態改變事件的監聽函數，參數Object res如下：

  内容	類型	說明
  deviceId	string	藍牙設備id
  connected	boolean	是否處於已連接狀態

• 示例代碼：

wx.onBLEConnectionStateChange(function(res) {
  // This method callback can be used to handle exceptional situations such as unexpected disconnections.
  console.log(device ${res.deviceId} state has changed, connected: ${res.connected})
})

offBLEConnectionStateChange

TIP

該API使用方法為： wx.offBLEConnectionStateChange(function listener)

• 功能說明： 移除藍牙低功耗連接狀態改變事件的監聽函數

• 參數及說明： function listener，onBLEConnectionStateChange傳入的監聽函數。 不傳此參數則移除所有監聽函數

• 示例代碼：

const listener = function (res) { console.log(res) }

wx.onBLEConnectionStateChange(listener)
wx.offBLEConnectionStateChange(listener) // pass the same listener function to unregister the listener

onBLECharacteristicValueChange

TIP

該API使用方法為： wx.onBLECharacteristicValueChange(function listener)

• 功能說明： 監聽藍牙低功耗設備的特徵值變化事件。 必須先調用 wx.notifyBLECharacteristicValueChange 接口才能接收到設備推送的notification

• 參數及說明： function listener，藍牙低功耗設備的特徵值變化事件的監聽函數，參數Object res如下：

  内容	類型	說明
  deviceId	string	藍牙設備id
  serviceId	string	藍牙特徵對應服務的UUID
  characteristicId	string	藍牙特徵的UUID
  value	ArrayBuffer	特徵最新的值

• 示例代碼：

// ArrayBuffer to 16
function ab2hex(buffer) {
  let hexArr = Array.prototype.map.call(
    new Uint8Array(buffer),
    function(bit) {
      return ('00' + bit.toString(16)).slice(-2)
    }
  )
  return hexArr.join('');
}
wx.onBLECharacteristicValueChange(function(res) {
  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
  console.log(ab2hex(res.value))
})

offBLECharacteristicValueChange

TIP

該API使用方法為： wx.offBLECharacteristicValueChange()

• 功能說明： 移除藍牙低功耗設備的特徵值變化事件的全部監聽函數

• 示例代碼：

wx.offBLECharacteristicValueChange()

notifyBLECharacteristicValueChange

TIP

該API使用方法為： wx.notifyBLECharacteristicValueChange(Object object)

TIP

• 訂閱操作成功後需要設備主動更新特徵的value，才會觸發 wx.onBLECharacteristicValueChange 完成App上的其他事件可以使用
• Android平臺上，在本接口調用成功後立即調用 wx.writeBLECharacteristicValue 接口，在部分機型上會發生10008系統錯誤。
• 必須設備的特徵支持notify或者indicate才可以成功調用。 另外，必須先啟用wx.notifyBLECharacteristicValueChange才能監聽到設備characteristicValueChange事件。

• 功能說明： 啟用藍牙低功耗設備特徵值變化時的notify功能，訂閱特徵。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  serviceId	string	-	是	藍牙特徵對應服務的UUID
  characteristicId	string	-	是	藍牙特徵的UUID
  state	boolean	-	是	是否啟用notify
  type	string	indication	否	設定特徵訂閱類型，有效值有notification和indication
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

// Transmit a hexadecimal data of 0x00 to the Bluetooth device.
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)


wx.writeBLECharacteristicValue({
  // The deviceId here must be obtained through the getBluetoothDevices or onBluetoothDeviceFound interfaces.
  deviceId,
  // The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
  serviceId,
  // The CharacteristicId Here Must be Retrieved from the getBLEDeviceCharacteristics Interface
  characteristicId,
  // The Value Here is of ArrayBuffer Type
  value: buffer,
  success (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

getBLEDeviceServices

TIP

該API使用方法為： wx.getBLEDeviceServices(Object object)

• 功能說明： 獲取藍牙低功耗設備所有服務（service）。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id。 需要已經通過wx.createBLEConnection 建立連接
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• object.success回呼函數參數： Object res。

  内容	類型	說明
  services	Array.<Object>	設備服務清單

• service結構内容

  内容	類型	說明
  uuid	string	藍牙設備服務的UUID
  isPrimary	boolean	該服務是否為主服務

• 示例代碼：

wx.getBLEDeviceServices({
  //  deviceId  wx.createBLEConnection 
  deviceId,
  success (res) {
    console.log('device services:', res.services)
  }
})

getBLEDeviceRSSI

TIP

該API使用方法為： wx.getBLEDeviceRSSI(Object object)

• 功能說明： 獲取藍牙低功耗設備的信號強度（Received Signal Strength Indication，RSSI）。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• object.success回呼函數參數： Object res。

  内容	類型	說明
  RSSI	Number	信號強度，單位： dBm

getBLEDeviceCharacteristics

TIP

該API使用方法為： wx.getBLEDeviceCharacteristics(Object object)

• 功能說明： 獲取藍牙低功耗設備某個服務中所有特徵（characteristic）。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id。 需要已經通過wx.createBLEConnection 建立連接
  serviceId	string	-	是	藍牙服務UUID。 需要先調用wx.createBLEConnection
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• object.success回呼函數參數： Object res。

  内容	類型	說明
  characteristics	Array.<Object>	設備特徵清單

  • characteristics結構内容

    結構内容	類型	說明
    uuid	string	藍牙設備特徵的UUID
    properties	Object	該特徵支持的操作類型

    • properties結構内容

      内容	類型	說明
      read	boolean	該特徵是否支持read操作
      write	boolean	該特徵是否支持write操作
      notify	boolean	該特徵是否支持notify操作
      indicate	boolean	該特徵是否支持indicate操作
      writeNoResponse	boolean	該特徵是否支持writeNoResponse操作
      writeDefault	boolean	該特徵是否支持writeDefault操作

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

wx.getBLEDeviceCharacteristics({
  // The deviceId here needs to have already established a link with the corresponding device through wx.createBLEConnection
  deviceId,
  // The ServiceId here must be obtained from the wx.getBLEDeviceServices interface.
  serviceId,
  success (res) {
    console.log('device getBLEDeviceCharacteristics:', res.characteristics)
  }
})

createBLEConnection

TIP

該API使用方法為： wx.createBLEConnection(Object object)

TIP

• 請保證儘量成對的調用wx.createBLEConnection和 wx.closeBLEConnection 接口。 Android如果重複調用wx.createBLEConnection創建連接，有可能導致系統持有同一設備多個連接的實例，導致調用closeBLEConnection的時候並不能真正的斷開與設備的連接。
• 藍牙連接隨時可能斷開，建議監聽 wx.onBLEConnectionStateChange 回檔事件，當藍牙設備斷開時按需執行重連操作
• 若對未連接的設備或已斷開連接的設備調用數據讀寫操作的接口，會返回10006錯誤，建議進行重連操作。

• 功能說明： 連接藍牙低功耗設備。 若小程序在之前已有蒐索過某個藍牙設備，並成功建立連接，可直接傳入之前蒐索獲取的deviceId直接嘗試連接該設備，無需再次進行蒐索操作。

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  timeout	number	-	否	超時時間，單位ms，不填表示不會超時
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

wx.createBLEConnection({
  deviceId,
  success (res) {
    console.log(res)
  }
})

closeBLEConnection

TIP

該API使用方法為： wx.closeBLEConnection(Object object)

• 功能說明： 斷開與藍牙低功耗設備的連接

• 參數及說明： Object object。

  内容	類型	預設值	必填	說明
  deviceId	string	-	是	藍牙設備id
  success	Function	-	否	接口調用成功的回呼函數
  fail	Function	-	否	接口調用失敗的回呼函數
  complete	Function	-	否	接口調用結束的回呼函數（無論成功與否都執行）

• 錯誤碼

  錯誤碼	錯誤資訊	說明
  0	ok	正常
  -1	already connect	已連接
  10000	not init	未初始化藍牙適配器
  10001	not available	當前藍牙適配器不可用
  10002	no device	沒有找到指定設備
  10003	connection fail	連接失敗
  10004	no service	沒有找到指定服務
  10005	no characteristic	沒有找到指定特徵
  10006	no connection	當前連接已斷開
  10007	property not support	當前特徵不支持此操作
  10008	system error	其餘所有系統上報的异常
  10009	system not support	Android系統特有，系統版本低於4.3不支持BLE
  10012	operate time out	連接超時
  10013	invalid_data	連接deviceId為空或者是格式不正確

• 示例代碼：

wx.closeBLEConnection({
  deviceId,
  success (res) {
    console.log(res)
  }
})