基本介绍
蓝牙适配器(BlueToothAdapter),提供了搜索设备、连接设备等方法,进而实现和蓝牙设备之间的通信。
名词解释
名词 | 含义 |
serviceId | 服务 id,蓝牙服务的 uuid,搜索设备时主要通过 serviceId 来过滤我们需要的设备。 |
deviceId | 小程序 API 搜索出来的设备的标识,连接设备时主要通过 deviceId 来标识需要连接的设备。 |
explorerDeviceId | 物联网开发平台侧定义的设备 ID,查询设备数据和上报设备数据时以设备 ID 作为设备标识。 |
DeviceAdapter 设备适配器 | 真正用来连接设备以及跟设备进行通信的模块,每一个设备连接对应一个设备适配器实例,设备适配器会在连接设备后实例化,并在设备断开连接后销毁。根据不同的 serviceId 来区别不同类型设备的适配器构造函数。 |
初始化
安装依赖
import { BlueToothAdapter } from 'qcloud-iotexplorer-bluetooth-adapter';
获取蓝牙适配器实例
1. 接口定义
new BlueToothAdapter(options: Object);
2. 输入参数
参数名称 | 参数描述 | 类型 | 必填 |
deviceAdapter | 设备适配器 | array | 否 |
ignoreAnonymousDevices | 忽略 name === '未知设备' 的蓝牙设备,默认值:true | boolean | 否 |
devMode | 开发模式 | boolean | function | 否 |
DeviceAdapter 参数说明
3. 返回结果
参数名称 | 参数描述 | 类型 |
- | 蓝牙适配器实例。 | object |
4. 示例代码
import { BlueToothAdapter } from 'qcloud-iotexplorer-bluetooth-adapter';import { LLSyncDeviceAdapter } from 'qcloud-iotexplorer-bluetooth-adapter-llsync';import appDevSdk from './appDevSdk';LLSyncDeviceAdapter.injectOptions({// AppDevSdk实例,文档参考[小程序SDK]appDevSdk,});export const blueToothAdapter = new BlueToothAdapter({deviceAdapters: [LLSyncDeviceAdapter,],});
API 参考文档
添加设备适配器
调用本接口将其构造函数添加到蓝牙适配器中,可添加一个或多个设备适配器
1. 接口定义
blueToothAdapter.addAdapter(deviceAdapter);
2. 输出参数
参数名 | 参数描述 | 类型 | 必填 |
deviceAdapter | 要添加的设备适配器的构造函数 | Function | Array | 是 |
3. 示例代码
import { LLSyncDeviceAdapter } from 'qcloud-iotexplorer-bluetooth-adapter-llsync';import {BleComboEspDeviceAdapter,BleComboLLSyncDeviceAdapter,} from 'qcloud-iotexplorer-appdev-plugin-wificonf-blecombo';LLSyncDeviceAdapter.injectOptions({ appDevSdk });// 接受一个DeviceAdapterblueToothAdapter.addAdapter(LLSyncDeviceAdapter);// 接受多个DeviceAdapterblueToothAdapter.addAdapter([BleComboEspDeviceAdapter,BleComboLLSyncDeviceAdapter,]);
初始化蓝牙模块
包括初始化蓝牙模块、打通小程序间蓝牙通信、注册全局回调等。
本接口可重复调用,可在每次使用蓝牙模块前调用。
1. 接口定义
blueToothAdapter.init();
2. 返回结果
返回一个带缓存的 Promise,初始化成功后 resolve。若初始化未完成或已初始化成功,则多次调用后返回同一个 Promise。若初始化失败,则该缓存的 Promise 在 reject 之后会被释放,再次调用则将重新初始化。
3. 示例代码
blueToothAdapter.init().then(() => {// 调用蓝牙模块能力});
开始搜索蓝牙设备
开始搜寻附近的蓝牙外围设备。将搜索到的所有蓝牙设备依次调用设备适配器的过滤函数
DeviceAdapter.deviceFilter
,如果过滤函数返回蓝牙设备信息,将触发 onSearch
回调函数。1. 接口定义
blueToothAdapter.startSearch(options: Object);
2. 输入参数
参数名称 | 参数描述 | 类型 | 必填 |
onSearch | 当搜索设备结果更新后调用,返回搜索到的设备列表。 | function | 是 |
onError | 当搜索过程中发生错误后调用,触发后设备搜索将会中止。 | function | 是 |
serviceId | 使用指定serviceId的设备适配器,默认会使用已添加的全部 DeviceAdapter。 | string | 否 |
serviceIds | 参数描述同 serviceId。 | string[] | 否 |
ignoreServiceIds | 通过serviceId忽略使用某些设备适配器。 | string[] | 否 |
ignoreDeviceIds | 需要过滤掉的 deviceId 列表(例如刚添加完的设备),搜索结果中将不会出现这些设备。 | string[] | 否 |
timeout | 超过指定时长没有搜索到设备,将会触发超时错误。默认值:20000;单位:ms。 | number | 否 |
3. 返回结果
返回一个 Promise。
4. 示例代码
blueToothAdapter.startSearch({onSearch: (devices) => {console.log('搜索到设备:', devices);if (devices.length > 0) {blueToothAdapter.stopBleSearch();}},onError: (err) => {console.log('搜索设备出错', err);}});
搜索单个蓝牙设备
开始搜索蓝牙设备,在找到第一个满足条件的设备后停止搜索。
1. 接口定义
blueToothAdapter.searchDevice(options: Object);
2. 输入参数
参数名称 | 参数描述 | 类型 | 必填 |
deviceId | string | 是 | |
deviceName | 腾讯云物联网开发平台的 deviceName。 | string | 否 |
serviceId | 使用指定 serviceId 的设备适配器,默认会使用已添加的全部 DeviceAdapter。 | string | 否 |
serviceIds | 参数描述同 serviceId。 | string[] | 否 |
ignoreDeviceIds | 可选,需要过滤掉的 deviceId 列表(例如刚添加完的设备),搜索结果中将不会出现这些设备。 | string[] | 否 |
3. 返回结果
返回一个 Promise,结果为搜索到第一个满足条件的设备。
4. 示例代码
blueToothAdapter.searchDevice({ serviceId: 'xxx' }); // 搜索指定serviceId的设备
停止搜索蓝牙设备
接口定义
blueToothAdapter.stopSearch();
连接蓝牙设备
传入设备信息连接蓝牙设备,连接成功后实例化蓝牙设备对应的设备适配器并返回。
1. 接口定义
blueToothAdapter.connectDevice(deviceInfo, options);
2. 输入参数
deviceInfo 参数说明
参数名称 | 参数描述 | 类型 | 必填 |
deviceId | 蓝牙设备 id,同微信蓝牙接口回调的 deviceId。 | string | 否 |
name | 蓝牙设备名称,同微信蓝牙接口回调的 name。 | string | 否 |
productId | 腾讯云物联网开发平台的产品 ID。 | string | 否 |
deviceName | 腾讯云物联网开发平台的设备名称。 | string | 否 |
serviceId | 蓝牙设备 serviceId。 | string | 否 |
options 参数说明
参数名称 | 参数描述 | 类型 | 必填 |
autoNotify | 可选,默认为 true。 指定为 true 时,在连接设备后,会自动去拉取服务列表,以及主服务下的特征值列表,并会自动订阅第一个 notifyId 或 indicateId 特征值的 notify。 若设备含有多个服务或多个 notify 特征值,请传 false,并自行通过 getBLEDeviceServices、getBLEDeviceCharacteristics、notifyBLECharacteristicValueChange 等方法获取及订阅特征值。 | boolean | 否 |
3. 返回结果
返回一个
Promise<DeviceAdapter>
,参数如下表:参数名称 | 参数描述 | 类型 | 必填 |
- | 设备适配器实例。 | object | 是 |
4. 示例代码
const deviceAdapter = await blueToothAdapter.connectDevice(device);
获取设备适配器实例
获取设备适配器实例,调用
blublueToothAdapter.connectDevice
之后会实例化设备适配器 1. 接口定义
blueToothAdapter.getDeviceAdapter(options: Object);
2. 参数说明
参数名称 | 参数描述 | 类型 | 必填 |
deviceId | 蓝牙设备 id,同微信蓝牙接口回调的 deviceId,优先级高于 explorerDeviceId。 | string | 否 |
explorerDeviceId | 腾讯云物联网开发平台的 deviceId。 | string | 否 |
3. 返回结果
返回一个 Promise,参数如下:
参数名称 | 参数描述 | 类型 | 必填 |
- | 设备适配器实例。 | object | undefined | 否 |
获取所有搜索到的蓝牙设备
1. 接口定义
blueToothAdapter.getBluetoothDevices();
2. 返回结果
蓝牙适配器事件
监听事件
1. 接口定义
blueToothAdapter.on(type, listener);
2. 输入参数
参数名称 | 参数描述 | 类型 | 必填 |
type | 事件名称。 | string | 是 |
listener | 事件触发时的回调函数。 | function | 是 |
3. 示例代码
blueToothAdapter.on('adapterStateChange', ({ available, discovering ]}) => {console.warn('event adapterStateChange emit', { available, discovering });});
取消监听事件
取消监听蓝牙适配器事件。
1. 接口定义
blueToothAdapter.off(type, listener);
2. 输入参数
参数名称 | 参数描述 | 类型 | 必填 |
type | 要取消监听的事件。 | string | 是 |
listener | 要取消监听的事件的回调函数,不传则清除该事件的所有回调函数。 | function | 否 |
3. 示例代码
const onAdapterStateChange = blueToothAdapter.on('adapterStateChange', ({ available, discovering ]}) => {console.warn('event adapterStateChange emit', { available, discovering });});blueToothAdapter.off('adapterStateChange', onAdapterStateChange);
事件列表
adapterStateChange 事件:当蓝牙适配器状态变化时触发回调,返回当前状态。事件回调函数参数如下:
参数名称 | 参数描述 | 类型 |
available | 蓝牙适配器是否可用。 | boolean |
discovering | 蓝牙适配器是否处于搜索状态。 | boolean |