微信小程序API 蓝牙适配器接口

蓝牙适配器接口

基础库版本 1.1.0 开始支持，低版本需做兼容处理

iOS 微信客户端 6.5.6 版本开始支持，Android 客户端暂不支持

wx.openBluetoothAdapter(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

初始化蓝牙适配器

OBJECT参数说明：

示例代码：

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

Bug & Tip

1. tip: 由于系统的问题，目前仅在 mac 版的开发工具上支持蓝牙调试
2. tip: 基础库版本 1.1.0 开始支持，低版本需做兼容处理

wx.closeBluetoothAdapter(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

关闭蓝牙模块。调用该方法将断开所有已建立的链接并释放系统资源

OBJECT参数说明：

示例代码：

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

wx.getBluetoothAdapterState(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

获取本机蓝牙适配器状态

OBJECT参数说明：

success返回参数：

示例代码：

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

wx.onBluetoothAdapterStateChange(CALLBACK)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

监听蓝牙适配器状态变化事件

CALLBACK参数说明：

示例代码：

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

wx.startBluetoothDevicesDiscovery(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

开始搜寻附近的蓝牙外围设备。注意，该操作比较耗费系统资源，请在搜索并连接到设备后调用 stop 方法停止搜索。

OBJECT参数说明：

services参数说明：某些蓝牙设备会广播自己的主 service 的 uuid。如果这里传入该数组，那么根据该 uuid 列表，只搜索有这个主服务的设备。

success返回参数：

示例代码：

// 以微信硬件平台的蓝牙智能灯为例，主服务的 UUID 是 FEE7。传入这个参数，只搜索主服务 UUID 为 FEE7 的设备
wx.startBluetoothDevicesDiscovery({
  services: ['FEE7'],
  success: function (res) {
    console.log(res)
  }
})

wx.stopBluetoothDevicesDiscovery(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

停止搜寻附近的蓝牙外围设备。请在确保找到需要连接的设备后调用该方法停止搜索。

OBJECT参数说明：

success返回参数：

adapterState

蓝牙适配器状态信息

示例代码：

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

wx.getBluetoothDevices(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

获取所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备

OBJECT参数说明：

success返回参数：

device 对象

蓝牙设备信息

示例代码：

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

Bug & Tip

1. tip: Mac系统可能无法获取advertisData及RSSI，请使用真机调试
2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

wx.getConnectedBluetoothDevices(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

根据 uuid 获取处于已连接状态的设备

OBJECT参数说明：

success返回参数：

device对象

蓝牙设备信息

示例代码：

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

Bug & Tip

1. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

wx.onBluetoothDeviceFound(CALLBACK)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

监听寻找到新设备的事件

CALLBACK参数说明：

device对象

示例代码：

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

Bug & Tip

1. tip: Mac系统可能无法获取advertisData及RSSI，请使用真机调试
2. tip: 开发者工具和 Android 上获取到的deviceId为设备 MAC 地址，iOS 上则为设备 uuid。因此deviceId不能硬编码到代码中

低功耗蓝牙接口

wx.createBLEConnection(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

连接低功耗蓝牙设备

OBJECT参数说明：

success返回参数：

示例代码：

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

wx.closeBLEConnection(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

断开与低功耗蓝牙设备的连接

OBJECT参数说明：

success返回参数：

示例代码：

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

wx.getBLEDeviceServices(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

获取蓝牙设备所有 service（服务）

OBJECT参数说明：

success返回参数：

service对象

蓝牙设备service(服务)信息

示例代码：

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

wx.getBLEDeviceCharacteristics(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

获取蓝牙设备所有 characteristic（特征值）

OBJECT参数说明：

success返回参数：

characteristic对象

蓝牙设备characteristic(特征值)信息

properties对象

示例代码：

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

wx.readBLECharacteristicValue(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持read才可以成功调用，具体参照 characteristic 的 properties 属性

OBJECT参数说明：

success返回参数：

characteristic对象

蓝牙设备characteristic(特征值)信息

示例代码：

// 必须在这里的回调才能获取
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

1. tip: 并行调用多次读写接口存在读写失败的可能性。
2. tip:read接口读取到的信息需要在onBLECharacteristicValueChange方法注册的回调中获取。

wx.writeBLECharacteristicValue(OBJECT)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持write才可以成功调用，具体参照 characteristic 的 properties 属性

tips: 并行调用多次读写接口存在读写失败的可能性

OBJECT参数说明：

success返回参数：

示例代码：

// 这里的回调可以获取到 write 导致的特征值改变
wx.onBLECharacteristicValueChange(function(characteristic) {
  console.log('characteristic value changed:', characteristic)
})

// 向蓝牙设备发送一个0x00的16进制数据
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)

基础库版本 1.1.0 开始支持，低版本需做兼容处理

启用低功耗蓝牙设备特征值变化时的 notify 功能。注意：必须设备的特征值支持notify才可以成功调用，具体参照 characteristic 的 properties 属性

另外，必须先启用notify才能监听到设备 characteristicValueChange 事件

OBJECT参数说明：

success返回参数：

示例代码：

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)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

监听低功耗蓝牙连接的错误事件，包括设备丢失，连接异常断开等等。

CALLBACK参数说明：

示例代码：

wx.onBLEConnectionStateChanged(function(res) {
  // 该方法回调中可以用于处理连接意外断开等异常情况
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

wx.onBLECharacteristicValueChange(CALLBACK)

---

基础库版本 1.1.0 开始支持，低版本需做兼容处理

监听低功耗蓝牙设备的特征值变化。必须先启用notify接口才能接收到设备推送的notification。

CALLBACK参数说明：

示例代码：

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

蓝牙错误码(errCode)列表

wx.makeBluetoothPair(Object object)

基础库 2.12.0 开始支持，低版本需做兼容处理。

蓝牙配对接口，仅安卓使用。安卓上蓝牙连接时，部分设备需先配对。

参数

Object object