閱讀(57.2k) 書簽贊(3) 我要糾錯

微信小程序API 藍牙適配器接口

2022-05-11 16:55 更新

藍牙適配器接口

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: 基礎庫版本 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	是否正在搜索設備
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)

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

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
services	Array	否	藍牙設備主 service 的 uuid 列表
allowDuplicatesKey	boolean	否	是否允許重復上報同一設備，如果允許重復上報，則onDeviceFound 方法會多次上報同一設備，但是 RSSI 值會有不同
interval	integer	否	上報設備的間隔，默認為0，意思是找到新設備立即上報，否則根據(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ù)說明：某些藍牙設備會廣播自己的主 service 的 uuid。如果這里傳入該數(shù)組，那么根據(jù)該 uuid 列表，只搜索有這個主服務的設備。

success返回參數(shù)：

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

示例代碼：

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

wx.stopBluetoothDevicesDiscovery(OBJECT)

停止搜尋附近的藍牙外圍設備。請在確保找到需要連接的設備后調(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	是否正在搜索設備
available	boolean	藍牙適配器是否可用

示例代碼：

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

wx.getBluetoothDevices(OBJECT)

獲取所有已發(fā)現(xiàn)的藍牙設備，包括已經(jīng)和本機處于連接狀態(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ù)	類型	說明
devices	Array	uuid 對應的的已連接設備列表
errMsg	string	成功：ok，錯誤：詳細信息

device 對象

藍牙設備信息

參數(shù)	類型	說明
name	string	藍牙設備名稱，某些設備可能沒有
deviceId	string	用于區(qū)分設備的 id
RSSI	int	當前藍牙設備的信號強度
advertisData	ArrayBuffer	當前藍牙設備的廣播內(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為設備 MAC 地址，iOS 上則為設備 uuid。因此deviceId不能硬編碼到代碼中

wx.getConnectedBluetoothDevices(OBJECT)

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

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
services	Array	是	藍牙設備主 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	搜索到的設備列表
errMsg	string	成功：ok，錯誤：詳細信息

device對象

藍牙設備信息

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

示例代碼：

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

Bug & Tip

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

wx.onBluetoothDeviceFound(CALLBACK)

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

CALLBACK參數(shù)說明：

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

device對象

參數(shù)	類型	說明
deviceId	string	藍牙設備 id，參考 device 對象
name	string	藍牙設備名稱，參考 device 對象
RSSI	int	當前藍牙設備的信號強度
advertisData	ArrayBuffer	當前藍牙設備的廣播內(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為設備 MAC 地址，iOS 上則為設備 uuid。因此deviceId不能硬編碼到代碼中

低功耗藍牙接口

wx.createBLEConnection(OBJECT)

連接低功耗藍牙設備

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 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)

斷開與低功耗藍牙設備的連接

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 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)

獲取藍牙設備所有 service（服務）

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 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	設備服務列表
errMsg	string	成功：ok，錯誤：詳細信息

service對象

藍牙設備service(服務)信息

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

示例代碼：

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

wx.getBLEDeviceCharacteristics(OBJECT)

獲取藍牙設備所有 characteristic（特征值）

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 id，參考 device 對象
serviceId	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ù)	類型	說明
characteristics	array	設備特征值列表
errMsg	string	成功：ok，錯誤：詳細信息

characteristic對象

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

參數(shù)	類型	說明
uuid	string	藍牙設備特征值的 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ù)據(jù)值。注意：必須設備的特征值支持read才可以成功調(diào)用，具體參照 characteristic 的 properties 屬性

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 id，參考 device 對象
serviceId	string	是	藍牙特征值對應服務的 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	設備特征值信息
errMsg	string	成功：ok，錯誤：詳細信息

characteristic對象

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

參數(shù)	類型	說明
characteristicId	string	藍牙設備特征值的 uuid
serviceId	object	藍牙設備特征值對應服務的 uuid
value	ArrayBuffer	藍牙設備特征值對應的二進制值（注意：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ù)據(jù)。注意：必須設備的特征值支持write才可以成功調(diào)用，具體參照 characteristic 的 properties 屬性

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

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 id，參考 device 對象
serviceId	string	是	藍牙特征值對應服務的 uuid
characteristicId	string	是	藍牙特征值的 uuid
value	ArrayBuffer	是	藍牙設備特征值對應的二進制值（注意：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)
})

// 向藍牙設備發(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)

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

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

OBJECT參數(shù)說明：

參數(shù)	類型	必填	說明
deviceId	string	是	藍牙設備 id，參考 device 對象
serviceId	string	是	藍牙特征值對應服務的 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)聽低功耗藍牙連接的錯誤事件，包括設備丟失，連接異常斷開等等。

CALLBACK參數(shù)說明：

參數(shù)	類型	說明
deviceId	string	藍牙設備 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)聽低功耗藍牙設備的特征值變化。必須先啟用notify接口才能接收到設備推送的notification。

CALLBACK參數(shù)說明：

參數(shù)	類型	說明
deviceId	string	藍牙設備 id，參考 device 對象
serviceId	string	特征值所屬服務 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	沒有找到指定設備
10003	connection fail	連接失敗
10004	no service	沒有找到指定服務
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	沒有找到指定描述符

wx.makeBluetoothPair(Object object)

藍牙配對接口，僅安卓使用。安卓上藍牙連接時，部分設備需先配對。

參數(shù)

Object object

屬性	類型	默認值	必填	說明
deviceId	string		是	藍牙設備 id
pin	ArrayBuffer		否	pin 碼
timeout	number	20	否	超時時間
success	function		否	接口調(diào)用成功的回調(diào)函數(shù)
fail	function		否	接口調(diào)用失敗的回調(diào)函數(shù)
complete	function		否	接口調(diào)用結(jié)束的回調(diào)函數(shù)（調(diào)用成功、失敗都會執(zhí)行）