微信小程序开发教程手册
> 微信小程序开发教程手册 > 微信小程序API 蓝牙

蓝牙适配器接口

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

ios 微信客户端 6.5.6 版本开始支持，android 客户端暂不支持

wx.openBluetoothAdapter(OBJECT)

初始化蓝牙适配器

OBJECT参数说明：

参数 类型 必填 说明
success Function 是 成功则返回成功初始化信息
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例代码：

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

Bug & Tip

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

wx.closeBluetoothAdapter(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
success Function 是 成功则返回成功关闭模块信息
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

示例代码：

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

wx.getBluetoothAdapterState(OBJECT)

获取本机蓝牙适配器状态

OBJECT参数说明：

参数 类型 必填 说明
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
adapterState object 蓝牙适配器信息
errMsg string 成功：ok，错误：详细信息

adapterState

蓝牙适配器状态信息

参数 类型 说明
discovering boolean 是否正在搜索设备
available boolean 蓝牙适配器是否可用

示例代码：

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

wx.onBluetoothAdapterStateChange(CALLBACK)

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

CALLBACK参数说明：

参数 类型 说明
available boolean 蓝牙适配器是否可用
discovering boolean 蓝牙适配器是否处于搜索状态

示例代码：

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

wx.startBluetoothDevicesDiscovery(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
services Array 否 蓝牙设备主 service 的 uuid 列表
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

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

success返回参数：

参数 类型 说明
errMsg string 成功：ok，错误：详细信息

示例代码：

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

wx.stopBluetoothDevicesDiscovery(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
errMsg string 成功：ok，错误：详细信息

adapterState

蓝牙适配器状态信息

参数 类型 说明
discovering boolean 是否正在搜索设备
available boolean 蓝牙适配器是否可用

示例代码：

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

wx.getBluetoothDevices(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
services Array 否 蓝牙设备主 service 的 uuid 列表
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
devices Array uuid 对应的的已连接设备列表
errMsg string 成功：ok，错误：详细信息

device 对象

蓝牙设备信息

参数 类型 说明
name string 蓝牙设备名称，某些设备可能没有
deviceId string 用于区分设备的 id
RSSI int 当前蓝牙设备的信号强度
advertisData ArrayBuffer 当前蓝牙设备的广播内容

示例代码：

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

Bug & Tip

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

wx.onBluetoothDeviceFound(CALLBACK)

监听寻找到新设备的事件

CALLBACK参数说明：

参数 类型 说明
devices Array 新搜索到的设备列表

device对象

参数 类型 说明
deviceId string 蓝牙设备 id，参考 device 对象
name string 蓝牙设备名称，参考 device 对象
RSSI int 当前蓝牙设备的信号强度
advertisData ArrayBuffer 当前蓝牙设备的广播内容

示例代码：

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.getConnectedBluetoothDevices(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
services Array 是 蓝牙设备主 service 的 uuid 列表
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
devices Array 搜索到的设备列表
errMsg string 成功：ok，错误：详细信息

device对象

蓝牙设备信息

参数 类型 说明
name string 蓝牙设备名称，某些设备可能没有
deviceId string 用于区分设备的 id

示例代码：

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

Bug & Tip

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

低功耗蓝牙接口

wx.createBLEConnection(OBJECT)

连接低功耗蓝牙设备

OBJECT参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 getDevices 接口
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
errMsg string 成功：ok，错误：详细信息

示例代码：

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

wx.closeBLEConnection(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 getDevices 接口
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
errMsg string 成功：ok，错误：详细信息

示例代码：

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

wx.onBLEConnectionStateChanged(CALLBACK)

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

CALLBACK参数说明：

参数 类型 说明
deviceId string 蓝牙设备 id，参考 device 对象
connected boolean 连接目前的状态

示例代码：

wx.onBLEConnectionStateChanged(function(res) {
  console.log(`device ${res.deviceId} state has changed, connected: ${res.connected}`)
})

wx.getBLEDeviceServices(OBJECT)

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

OBJECT参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 getDevices 接口
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
services array 设备服务列表
errMsg string 成功：ok，错误：详细信息

service对象

蓝牙设备service(服务)信息

参数 类型 说明
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参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 device 对象
serviceId string 是 蓝牙服务 uuid
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
characteristics array 设备特征值列表
errMsg string 成功：ok，错误：详细信息

characteristic对象

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

参数 类型 说明
uuid string 蓝牙设备特征值的 uuid
properties object 该特征值支持的操作类型
properties对象
参数 类型 说明
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)

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

OBJECT参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 device 对象
serviceId string 是 蓝牙特征值对应服务的 uuid
characteristicId string 是 蓝牙特征值的 uuid
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
characteristic object 设备特征值信息
errMsg string 成功：ok，错误：详细信息

characteristic对象

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

参数 类型 说明
characteristicId string 蓝牙设备特征值的 uuid
serviceId object 蓝牙设备特征值对应服务的 uuid
value ArrayBuffer 蓝牙设备特征值对应的二进制值

示例代码：

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

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

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

OBJECT参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 device 对象
serviceId string 是 蓝牙特征值对应服务的 uuid
characteristicId string 是 蓝牙特征值的 uuid
value ArrayBuffer 是 蓝牙设备特征值对应的二进制值
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
errMsg string 成功：ok，错误：详细信息

示例代码：

// 这里的回调可以获取到 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)

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

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

OBJECT参数说明：

参数 类型 必填 说明
deviceId string 是 蓝牙设备 id，参考 device 对象
serviceId string 是 蓝牙特征值对应服务的 uuid
characteristicId string 是 蓝牙特征值的 uuid
state boolean 是 true: 启用 notify; false: 停用 notify
success Function 是 成功则返回本机蓝牙适配器状态
fail Function 否 接口调用失败的回调函数
complete Function 否 接口调用结束的回调函数（调用成功、失败都会执行）

success返回参数：

参数 类型 说明
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)

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

CALLBACK参数说明：

参数 类型 说明
deviceId string 蓝牙设备 id，参考 device 对象
connected boolean 连接目前的状态

示例代码：

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

wx.onBLECharacteristicValueChange(CALLBACK)

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

CALLBACK参数说明：

参数 类型 说明
deviceId string 蓝牙设备 id，参考 device 对象
serviceId string 特征值所属服务 uuid
characteristicId string 特征值 uuid
value ArrayBuffer 特征值最新的值

示例代码：

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