物联网开发平台
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 物联网开发平台 > 应用端开发指南 > 自主品牌小程序开发 > 应用端 SDK > 蓝牙模块 SDK > 设备适配器

设备适配器

最近更新时间：2022-03-04 18:12:37

我的收藏

本页目录：

基本介绍

设备适配器（DeviceAdapter）提供了操作蓝牙设备的基本方法，是真正用来连接设备以及跟设备进行通信的模块。
每个蓝牙协议的设备，都对应一个设备适配器实例，设备适配器会在连接设备（调用 bluetoothAdapter.connectDevice() ）之后实例化，并在设备断开连接后销毁。根据不同的 serviceId 来区别不同类型设备的适配器。
开发者可根据各蓝牙设备协议，自行实现设备适配器。

自定义设备适配器

自定义设备适配器类需要继承 DeviceAdapter，并补充以下实现。
实现内容
serviceId：自定义设备适配器类需要设置该静态属性，代表该设备的主服务 ID。
deviceFilter：自定义设备适配器类需要实现该静态方法，在搜索蓝牙设备时会将每个搜索到的设备信息传入该函数。如果判断是本产品的设备，则需在除入参 deviceInfo 之外返回设备唯一标识 deviceName 及 serviceId，否则返回空。
handleBLEMessage：自定义设备适配器类需要实现该方法，用于处理收到 onBLECharacteristicValueChange 回调后的协议解析。
返回值中如果返回 reportData，则会将该部分数据上报到云端（注意需与产品定义物模型匹配），其他字段则会透传到 message 事件的 payload 中。
示例代码
import { DeviceAdapter } from 'qcloud-iotexplorer-bluetooth-adapter';

class DemoDeviceAdapter extends DeviceAdapter {
  static serviceId = '0000FFF0-0000-1000-8000-00805F9B34CC';

  static deviceFilter(deviceInfo) {
    if (deviceInfo.advertisServiceUUIDs) {
      const matchedServiceId = deviceInfo.advertisServiceUUIDs.find(id => id === DemoDeviceAdapter.serviceId);
      if (matchedServiceId && deviceInfo.advertisData) {
        try {
          const macArr = deviceInfo.advertisData.slice(2);
          const mac = macArr.join(':');
          return {
            ...deviceInfo,
            deviceName: mac,
            serviceId: matchedServiceId,
          };
        } catch (err) {
          console.error('parse mac error', err);
        }
      }
    }
  }

  handleBLEMessage(hex) {
    return {
      type: 'unknown',
      data: hex,
    };
  }
}

const blueToothAdapter = new BlueToothAdapter({
  deviceAdapters: [
    DemoDeviceAdapter,
  ],
});

获取设备适配器实例

设备适配器会在连接设备之后实例化，通过蓝牙适配器连接设备后，返回对应的设备适配器。
示例代码
const deviceAdapter = blueToothAdapter.connectDevice(deviceInfo, options);

API参考文档

设备适配器属性

属性名
属性描述
类型
explorerDeviceId
只读，设备的 explorerDeviceId。
string
isConnected
只读，当前是否已连接设备。
boolean
deviceId
只读，设备的 deviceId。
string
serviceId
只读，设备的主服务 ID，与构造函数上的静态属性 DeviceAdapter.serviceId 一致。
string
originName
只读，设备的原始名称，即小程序接口搜索出来时的 name 字段。
string

获取设备服务列表

获取蓝牙低功耗设备所有服务 (service)
1. 接口定义
deviceAdapter.getBLEDeviceServices();
2. 返回结果
返回一个Promise，参数同 wx.getBLEDeviceServices 的 services。

获取服务的特征值列表

获取蓝牙低功耗设备某个服务中所有特征 (characteristic)
1. 接口定义
deviceAdapter.getBLEDeviceCharacteristics({ serviceId: string });
2. 输入参数
参数名称
参数描述
类型
必填
serviceId
指定要获取特征值列表的serviceId。默认值：主服务 ID。
string
否
3. 返回结果
返回一个Promise，参数同 wx.getBLEDeviceCharacteristics 的 characteristics。

读取指定特征值的二进制数据

读取蓝牙低功耗设备特征值的二进制数据。注意：必须设备的特征支持 read 才可以成功调用。
1. 接口定义
deviceAdapter.readBLECharacteristicValue({
  serviceId: string,
  characteristicId: string
});
2. 输入参数
参数名称
参数描述
类型
必填
serviceId
指定某个蓝牙服务。默认值：主服务 ID。
string
否
characteristicId
需要读取的特征值 ID。默认值：取主服务下的第一个 read 特征值。
string
否
3. 返回结果
返回一个Promise，参数同 wx.readBLECharacteristicValue 的返回结果。

启用设备特征值变化时的 notify 功能

启用蓝牙低功耗设备特征值变化时的 notify 功能，订阅特征。
1. 接口定义
deviceAdapter.notifyBLECharacteristicValueChange({
    characteristicId?: string,
    serviceId?: string,
    state?: boolean
});
2. 输入参数
参数名称
参数描述
类型
必填
serviceId
需要订阅的服务 ID，默认会取主服务 ID。
string
否
characteristicId
需要订阅的特征值 ID，默认会取主服务下的第一个 notify 或 indicate 特征值。
string
否
state
是否启用 notify，默认为 true。
boolean
否

获取设备的信号强度

获取蓝牙低功耗设备的信号强度 (Received Signal Strength Indication, RSSI)。
1. 接口定义
deviceAdapter.getBLEDeviceRSSI();
2. 返回结果
返回一个Promise，参数同 wx.getBLEDeviceRSSI 的 RSSI。

协商设置蓝牙最大传输单元

协商设置蓝牙低功耗的最大传输单元 (Maximum Transmission Unit, MTU)，本接口仅支持在 Android 系统下调用，iOS 因系统限制不支持。
1. 接口定义
deviceAdapter.setBLEMTU({ mtu: number });
2. 输入参数
参数名称
参数描述
类型
必填
mtu
最大传输单元。设置范围为 (22,512) 区间内，单位为 bytes。
number
是
3. 返回结果
参数名称
参数描述
类型
必填
mtu
最终协商的 MTU 值。如果协商失败则无此参数。
number
否

写入二进制数据到指定特征值中

向蓝牙低功耗设备特征值中写入二进制数据。注意：必须设备的特征支持 write 才可以成功调用。
1. 接口定义
deviceAdapter.write(hexString: string, options: Object);
2. 输入参数
参数名称
参数描述
类型
必填
hexString
需要写给蓝牙设备的十六进制字符串。
string
是
options.serviceId
需要写入的服务 ID，默认值：取主服务 ID。
string
否
options.writeId
需要写入的特征值 ID。默认值：取主服务下的第一个 writeId。
string
否
3. 返回结果
返回一个Promise，参数同 wx.writeBLECharacteristicValue 的返回结果。

断开设备连接

底层调用 wx.closeBLEConnection 断开与蓝牙低功耗设备的连接，触发设备适配器的 disconnect 事件。
接口定义
deviceAdapter.disconnectDevice();

设备适配器事件

监听事件

1. 接口定义
deviceAdapter.on(type, listener);
2. 输入参数
参数名称
参数描述
类型
必填
type
事件名称。
string
是
listener
事件触发时的回调函数。
function
是

取消监听事件

1. 接口定义
deviceAdapter.off(type, listener);
2. 输入参数
参数名称
参数描述
类型
必填
type
要取消监听的事件。
string
是
listener
要取消监听的事件的回调函数，不传则清除该事件的所有回调函数。
function
否

事件列表

connect 事件：设备连接后触发。
disconnect 事件：设备断开后触发。
message 事件：当收到 onBLECharacteristicValueChange 回调，并经过 handleBLEMessage 处理后触发。
参数名
参数描述
类型
timestamp
收到设备消息的时间戳，单位毫秒。
number
dataReported
收到设备的消息是否已上报云端。
boolean
（其他）
handleBLEMessage 函数返回的其他参数将会透传到 message 事件中。
any
bLEConnectionStateChange 事件：当 onBleConnectionStateChange 触发时触发，若 connected 为 true，则接下来会触发 connect 事件，否则会触发 disconnect 事件。
参数名
参数描述
类型
connected
设备是否连接。
boolean

中国站