蓝牙适配器

最近更新时间:2023-07-24 16:36:13

我的收藏

基本介绍

蓝牙适配器(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 参数说明
参考 设备适配器(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 });

// 接受一个DeviceAdapter
blueToothAdapter.addAdapter(LLSyncDeviceAdapter);

// 接受多个DeviceAdapter
blueToothAdapter.addAdapter([
BleComboEspDeviceAdapter,
BleComboLLSyncDeviceAdapter,
]);

初始化蓝牙模块

包括初始化蓝牙模块、打通小程序间蓝牙通信、注册全局回调等。
本接口可重复调用,可在每次使用蓝牙模块前调用。

1. 接口定义

blueToothAdapter.init();

2. 返回结果

返回一个带缓存的 Promise,初始化成功后 resolve。若初始化未完成或已初始化成功,则多次调用后返回同一个 Promise。若初始化失败,则该缓存的 Promise 在 reject 之后会被释放,再次调用则将重新初始化。

3. 示例代码

blueToothAdapter.init().then(() => {
// 调用蓝牙模块能力
});

开始搜索蓝牙设备

开始搜寻附近的蓝牙外围设备。将搜索到的所有蓝牙设备依次调用设备适配器的过滤函数 DeviceAdapter.deviceFilter,如果过滤函数返回蓝牙设备信息,将触发 onSearch 回调函数。
接口底层将会调用 wx.startBluetoothDevicesDiscovery,比较耗费系统资源,务必在不需要搜索(如已搜索到设备、离开搜索页面)之后调用 停止搜索蓝牙设备

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
蓝牙设备 deviceId,参数同 微信蓝牙接口 回调的 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
设备信息,可将 开始搜索蓝牙设备搜索单个蓝牙设备 返回的蓝牙设备信息传入。
object
options
其他配置项。
object
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

获取所有搜索到的蓝牙设备

底层调用 wx.getBluetoothDevices 获取在蓝牙模块生效期间所有搜索到的蓝牙设备,默认会过滤掉 name === '未知设备' 的蓝牙设备。

1. 接口定义

blueToothAdapter.getBluetoothDevices();

2. 返回结果

返回搜索到的蓝牙设备列表,参数同 wx.getBluetoothDevices

蓝牙适配器事件

监听事件

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