微信小程序API藍牙適配器接口,openBluetoothAdapter初始化藍牙適配器

2017-12-22

導讀：藍牙適配器接口基礎(chǔ)庫版本 1.1.0 開始支持，低版本需做兼容處理 iOS 微信客戶端 6.5.6 版本開始支持，Android 客戶端暫不支持 wx.openBluetoothAdapter(OBJECT) 基礎(chǔ)庫版本 1.1.0 開始支持，低版本...

藍牙適配器接口

wx.openBluetoothAdapter(OBJECT)

初始化藍牙適配器

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
success	Function	是	成功則返回成功初始化信息
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

示例代碼：

wx.openBluetoothAdapter({
  success: function (res) {
    console.log(res)
  }
})

Bug & Tip

tip: 由于系統(tǒng)的問題，目前僅在 mac 版的開發(fā)工具上支持藍牙調(diào)試
tip: 基礎(chǔ)庫版本 1.1.0 開始支持，低版本需做兼容處理

wx.closeBluetoothAdapter(OBJECT)

關(guān)閉藍牙模塊。調(diào)用該方法將斷開所有已建立的鏈接并釋放系統(tǒng)資源

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
success	Function	是	成功則返回成功關(guān)閉模塊信息
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

示例代碼：

wx.closeBluetoothAdapter({
  success: function (res) {
    console.log(res)
  }
})

wx.getBluetoothAdapterState(OBJECT)

獲取本機藍牙適配器狀態(tài)

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
discovering	Boolean	是否正在搜索設(shè)備
available	Boolean	藍牙適配器是否可用
errMsg	String	成功：ok，錯誤：詳細信息

示例代碼：

wx.getBluetoothAdapterState({
  success: function (res) {
    console.log(res)
  }
})

wx.onBluetoothAdapterStateChange(CALLBACK)

監(jiān)聽藍牙適配器狀態(tài)變化事件

CALLBACK參數(shù)說明：

參數(shù)	類型	說明
available	boolean	藍牙適配器是否可用
discovering	boolean	藍牙適配器是否處于搜索狀態(tài)

示例代碼：

wx.onBluetoothAdapterStateChange(function(res) {
  console.log(`adapterState changed, now is`, res)
})

wx.startBluetoothDevicesDiscovery(OBJECT)

開始搜尋附近的藍牙外圍設(shè)備。注意，該操作比較耗費系統(tǒng)資源，請在搜索并連接到設(shè)備后調(diào)用 stop 方法停止搜索。

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
services	Array	否	藍牙設(shè)備主 service 的 uuid 列表
allowDuplicatesKey	boolean	否	是否允許重復上報同一設(shè)備，如果允許重復上報，則onDeviceFound 方法會多次上報同一設(shè)備，但是 RSSI 值會有不同
interval	integer	否	上報設(shè)備的間隔，默認為0，意思是找到新設(shè)備立即上報，否則根據(jù)傳入的間隔上報
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

services參數(shù)說明：某些藍牙設(shè)備會廣播自己的主 service 的 uuid。如果這里傳入該數(shù)組，那么根據(jù)該 uuid 列表，只搜索有這個主服務(wù)的設(shè)備。

success返回參數(shù)：

參數(shù)	類型	說明
errMsg	string	成功：ok，錯誤：詳細信息
isDiscovering	boolean	當前藍牙適配器是否處于搜索狀態(tài)

示例代碼：

// 以微信硬件平臺的藍牙智能燈為例，主服務(wù)的 UUID 是 FEE7。傳入這個參數(shù)，只搜索主服務(wù) UUID 為 FEE7 的設(shè)備
wx.startBluetoothDevicesDiscovery({
  services: ['FEE7'],
  success: function (res) {
    console.log(res)
  }
})

wx.stopBluetoothDevicesDiscovery(OBJECT)

停止搜尋附近的藍牙外圍設(shè)備。請在確保找到需要連接的設(shè)備后調(diào)用該方法停止搜索。

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
errMsg	string	成功：ok，錯誤：詳細信息

adapterState

藍牙適配器狀態(tài)信息

參數(shù)	類型	說明
discovering	boolean	是否正在搜索設(shè)備
available	boolean	藍牙適配器是否可用

示例代碼：

wx.stopBluetoothDevicesDiscovery({
  success: function (res) {
    console.log(res)
  }
})

wx.getBluetoothDevices(OBJECT)

獲取所有已發(fā)現(xiàn)的藍牙設(shè)備，包括已經(jīng)和本機處于連接狀態(tài)的設(shè)備

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
devices	Array	uuid 對應(yīng)的的已連接設(shè)備列表
errMsg	string	成功：ok，錯誤：詳細信息

device 對象

藍牙設(shè)備信息

參數(shù)	類型	說明
name	string	藍牙設(shè)備名稱，某些設(shè)備可能沒有
deviceId	string	用于區(qū)分設(shè)備的 id
RSSI	int	當前藍牙設(shè)備的信號強度
advertisData	ArrayBuffer	當前藍牙設(shè)備的廣播內(nèi)容（注意：vConsole 無法打印出 ArrayBuffer 類型數(shù)據(jù)）

示例代碼：

wx.getBluetoothDevices({
  success: function (res) {
    console.log(res)
  }
})

Bug & Tip

tip: Mac系統(tǒng)可能無法獲取advertisData及RSSI，請使用真機調(diào)試
tip: 開發(fā)者工具和 Android 上獲取到的deviceId為設(shè)備 MAC 地址，iOS 上則為設(shè)備 uuid。因此deviceId不能硬編碼到代碼中

wx.getConnectedBluetoothDevices(OBJECT)

根據(jù) uuid 獲取處于已連接狀態(tài)的設(shè)備

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
services	Array	是	藍牙設(shè)備主 service 的 uuid 列表
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
devices	Array	搜索到的設(shè)備列表
errMsg	string	成功：ok，錯誤：詳細信息

device對象

藍牙設(shè)備信息

參數(shù)	類型	說明
name	string	藍牙設(shè)備名稱，某些設(shè)備可能沒有
deviceId	string	用于區(qū)分設(shè)備的 id

示例代碼：

wx.getConnectedBluetoothDevices({
  success: function (res) {
    console.log(res)
  }
})

Bug & Tip

tip: 開發(fā)者工具和 Android 上獲取到的deviceId為設(shè)備 MAC 地址，iOS 上則為設(shè)備 uuid。因此deviceId不能硬編碼到代碼中

wx.onBluetoothDeviceFound(CALLBACK)

監(jiān)聽尋找到新設(shè)備的事件

CALLBACK參數(shù)說明：

參數(shù)	類型	說明
devices	Array	新搜索到的設(shè)備列表

device對象

參數(shù)	類型	說明
deviceId	string	藍牙設(shè)備 id，參考 device 對象
name	string	藍牙設(shè)備名稱，參考 device 對象
RSSI	int	當前藍牙設(shè)備的信號強度
advertisData	ArrayBuffer	當前藍牙設(shè)備的廣播內(nèi)容（注意：vConsole 無法打印出 ArrayBuffer 類型數(shù)據(jù)）

示例代碼：

wx.onBluetoothDeviceFound(function(devices) {
  console.log('new device list has founded')
  console.dir(devices)
})

Bug & Tip

tip: Mac系統(tǒng)可能無法獲取advertisData及RSSI，請使用真機調(diào)試
tip: 開發(fā)者工具和 Android 上獲取到的deviceId為設(shè)備 MAC 地址，iOS 上則為設(shè)備 uuid。因此deviceId不能硬編碼到代碼中

低功耗藍牙接口

wx.createBLEConnection(OBJECT)

連接低功耗藍牙設(shè)備

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 getDevices 接口
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
errMsg	string	成功：ok，錯誤：詳細信息

示例代碼：

wx.createBLEConnection({
  // 這里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中獲取
  deviceId: deviceId,
  success: function (res) {
    console.log(res)
  }
})

wx.closeBLEConnection(OBJECT)

斷開與低功耗藍牙設(shè)備的連接

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 getDevices 接口
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
errMsg	string	成功：ok，錯誤：詳細信息

示例代碼：

wx.closeBLEConnection({
  success: function (res) {
    console.log(res)
  }
})

wx.getBLEDeviceServices(OBJECT)

獲取藍牙設(shè)備所有 service（服務(wù)）

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 getDevices 接口
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
services	array	設(shè)備服務(wù)列表
errMsg	string	成功：ok，錯誤：詳細信息

service對象

藍牙設(shè)備service(服務(wù))信息

參數(shù)	類型	說明
uuid	string	藍牙設(shè)備服務(wù)的 uuid
isPrimary	boolean	該服務(wù)是否為主服務(wù)

示例代碼：

wx.getBLEDeviceServices({
  // 這里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中獲取
  deviceId: deviceId,
  success: function (res) {
    console.log('device services:', res.services)
  }
})

wx.getBLEDeviceCharacteristics(OBJECT)

獲取藍牙設(shè)備所有 characteristic（特征值）

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 device 對象
serviceId	string	是	藍牙服務(wù) uuid
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
characteristics	array	設(shè)備特征值列表
errMsg	string	成功：ok，錯誤：詳細信息

characteristic對象

藍牙設(shè)備characteristic(特征值)信息

參數(shù)	類型	說明
uuid	string	藍牙設(shè)備特征值的 uuid
properties	object	該特征值支持的操作類型

properties對象

參數(shù)	類型	說明
read	boolean	該特征值是否支持 read 操作
write	boolean	該特征值是否支持 write 操作
notify	boolean	該特征值是否支持 notify 操作
indicate	boolean	該特征值是否支持 indicate 操作

示例代碼：

wx.getBLEDeviceCharacteristics({
  // 這里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中獲取
  deviceId: deviceId,
  // 這里的 serviceId 需要在上面的 getBLEDeviceServices 接口中獲取
  serviceId: serviceId,
  success: function (res) {
    console.log('device getBLEDeviceCharacteristics:', res.characteristics)
  }
})

wx.readBLECharacteristicValue(OBJECT)

讀取低功耗藍牙設(shè)備的特征值的二進制數(shù)據(jù)值。注意：必須設(shè)備的特征值支持read才可以成功調(diào)用，具體參照 characteristic 的 properties 屬性

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 device 對象
serviceId	string	是	藍牙特征值對應(yīng)服務(wù)的 uuid
characteristicId	string	是	藍牙特征值的 uuid
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
characteristic	object	設(shè)備特征值信息
errMsg	string	成功：ok，錯誤：詳細信息

characteristic對象

藍牙設(shè)備characteristic(特征值)信息

參數(shù)	類型	說明
characteristicId	string	藍牙設(shè)備特征值的 uuid
serviceId	object	藍牙設(shè)備特征值對應(yīng)服務(wù)的 uuid
value	ArrayBuffer	藍牙設(shè)備特征值對應(yīng)的二進制值（注意：vConsole 無法打印出 ArrayBuffer 類型數(shù)據(jù)）

示例代碼：

// 必須在這里的回調(diào)才能獲取
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value comed:', characteristic)
})

wx.readBLECharacteristicValue({
  // 這里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中獲取
  deviceId: deviceId,
  // 這里的 serviceId 需要在上面的 getBLEDeviceServices 接口中獲取
  serviceId: serviceId,
  // 這里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中獲取
  characteristicId: characteristicId,
  success: function (res) {
    console.log('readBLECharacteristicValue:', res.characteristic.value)
  }
})

Bug & Tip

tip: 并行調(diào)用多次讀寫接口存在讀寫失敗的可能性。
tip:read接口讀取到的信息需要在onBLECharacteristicValueChange方法注冊的回調(diào)中獲取。

wx.writeBLECharacteristicValue(OBJECT)

向低功耗藍牙設(shè)備特征值中寫入二進制數(shù)據(jù)。注意：必須設(shè)備的特征值支持write才可以成功調(diào)用，具體參照 characteristic 的 properties 屬性

tips: 并行調(diào)用多次讀寫接口存在讀寫失敗的可能性

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 device 對象
serviceId	string	是	藍牙特征值對應(yīng)服務(wù)的 uuid
characteristicId	string	是	藍牙特征值的 uuid
value	ArrayBuffer	是	藍牙設(shè)備特征值對應(yīng)的二進制值（注意：vConsole 無法打印出 ArrayBuffer 類型數(shù)據(jù)）
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
errMsg	string	成功：ok，錯誤：詳細信息

示例代碼：

// 這里的回調(diào)可以獲取到 write 導致的特征值改變
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value changed:', characteristic)
})

// 向藍牙設(shè)備發(fā)送一個0x00的16進制數(shù)據(jù)
let buffer = new ArrayBuffer(1)
let dataView = new DataView(buffer)
dataView.setUint8(0, 0)

wx.writeBLECharacteristicValue({
  // 這里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中獲取
  deviceId: deviceId,
  // 這里的 serviceId 需要在上面的 getBLEDeviceServices 接口中獲取
  serviceId: serviceId,
  // 這里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中獲取
  characteristicId: characteristicId,
  // 這里的value是ArrayBuffer類型
  value: buffer,
  success: function (res) {
    console.log('writeBLECharacteristicValue success', res.errMsg)
  }
})

wx.notifyBLECharacteristicValueChanged(OBJECT)

啟用低功耗藍牙設(shè)備特征值變化時的 notify 功能。注意：必須設(shè)備的特征值支持notify才可以成功調(diào)用，具體參照 characteristic 的 properties 屬性

另外，必須先啟用notify才能監(jiān)聽到設(shè)備 characteristicValueChange 事件

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設(shè)備 id，參考 device 對象
serviceId	string	是	藍牙特征值對應(yīng)服務(wù)的 uuid
characteristicId	string	是	藍牙特征值的 uuid
state	boolean	是	true: 啟用 notify; false: 停用 notify
success	Function	是	成功則返回本機藍牙適配器狀態(tài)
fail	Function	否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	Function	否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）

success返回參數(shù)：

參數(shù)	類型	說明
errMsg	string	成功：ok，錯誤：詳細信息

示例代碼：

wx.notifyBLECharacteristicValueChanged({
  state: true, // 啟用 notify 功能
  // 這里的 deviceId 需要在上面的 getBluetoothDevices 或 onBluetoothDeviceFound 接口中獲取
  deviceId: deviceId,
  // 這里的 serviceId 需要在上面的 getBLEDeviceServices 接口中獲取
  serviceId: serviceId,
  // 這里的 characteristicId 需要在上面的 getBLEDeviceCharacteristics 接口中獲取
  characteristicId: characteristicId,
  success: function (res) {
    console.log('notifyBLECharacteristicValueChanged success', res.errMsg)
  }
})

wx.onBLEConnectionStateChanged(CALLBACK)

監(jiān)聽低功耗藍牙連接的錯誤事件，包括設(shè)備丟失，連接異常斷開等等。

CALLBACK參數(shù)說明：

參數(shù)	類型	說明
deviceId	string	藍牙設(shè)備 id，參考 device 對象
connected	boolean	連接目前的狀態(tài)

示例代碼：

wx.onBLEConnectionStateChanged(function(res) {
  // 該方法回調(diào)中可以用于處理連接意外斷開等異常情況
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

wx.onBLECharacteristicValueChange(CALLBACK)

監(jiān)聽低功耗藍牙設(shè)備的特征值變化。必須先啟用notify接口才能接收到設(shè)備推送的notification。

CALLBACK參數(shù)說明：

參數(shù)	類型	說明
deviceId	string	藍牙設(shè)備 id，參考 device 對象
serviceId	string	特征值所屬服務(wù) uuid
characteristicId	string	特征值 uuid
value	ArrayBuffer	特征值最新的值（注意：vConsole 無法打印出 ArrayBuffer 類型數(shù)據(jù)）

示例代碼：

wx.onBLECharacteristicValueChange(function(res) {
  console.log(`characteristic ${res.characteristicId} has changed, now is ${res.value}`)
})

藍牙錯誤碼(errCode)列表

錯誤碼	說明	備注
0	ok	正常
10000	not init	未初始化藍牙適配器
10001	not available	當前藍牙適配器不可用
10002	no device	沒有找到指定設(shè)備
10003	connection fail	連接失敗
10004	no service	沒有找到指定服務(wù)
10005	no characteristic	沒有找到指定特征值
10006	no connection	當前連接已斷開
10007	property not support	當前特征值不支持此操作
10008	system error	其余所有系統(tǒng)上報的異常
10009	system not support	Android 系統(tǒng)特有，系統(tǒng)版本低于 4.3 不支持BLE
10010	no descriptor	沒有找到指定描述符

更多微信小程序開發(fā)教程，可以關(guān)注hi小程序。

第二部分：如何開通一個小商店

您可能感興趣: 微信小程序藍牙開發(fā)

上一篇：微信小程序API剪貼板,setClipboardData設(shè)置系統(tǒng)剪貼板的內(nèi)容 下一篇：微信小程序APIiBeacon,wx.startBeaconDiscovery開始搜索附近的iBeacon設(shè)備