腾讯会议蓝牙-开放平台文档-文档中心-腾讯云

功能描述
使用场景
业务方需要扫描连接蓝牙耳机、音响等设备。
整体流程
初始化蓝牙设备。
扫描发现外围设备。
连接设备。
获取外围设备提供的服务。
获取服务的特征 characteristics。
读写服务的特征值。
断开蓝牙连接、关闭蓝牙适配器。
注意：
腾讯会议 Android 端从3.14版本开始支持蓝牙相关能力，IOS 端暂不支持。
扫描发现外围设备后，需要停止扫描（扫描设备比较耗费系统资源，请在搜索到需要的设备后及时调用）。
初始化蓝牙设备
JSAPI 接口
openBluetoothAdapter(): Promise<void>
代码示例
// 初始化蓝牙设备
wemeet.bluetooth.openBluetoothAdapter()
  .then(() => {
    console.log('openBluetoothAdapter seccuss');
    // 蓝牙设备初始化成功
  })
  .catch(err => {
    console.error('openBluetoothAdapter failed');
  });
﻿
扫描发现外围设备
JSAPI 接口
startBluetoothDevicesDiscovery(param?: BluetoothDevicesDiscoveryParam): Promise<void>
﻿
interface BluetoothDevicesDiscoveryParam {
  /**
   * 期望搜索到的蓝牙设备id
   */
  deviceId?: string;
  /**
   * 单位ms，非必填；默认为3000ms
   * 因为扫描十分耗费系统资源，开启scan以后，会在执行完扫描周期（或发现目标设备）后自动结束扫描
   */
  period?: number;
}
        
/**
 * BLE扫描完成的回调事件返回类型
 */
export interface BluetoothDeviceDiscoveryEventData {
  /**
   * 蓝牙设备列表
   */
  devices: BluetoothDeviceItem[];
}
﻿
/**
 * 蓝牙设备信息
 */
export interface BluetoothDeviceItem {
  /**
   * 蓝牙设备id
   */
  deviceId: string;
  /**
   * 蓝牙名称
   */
  name: string;
  /**
   * 前蓝牙设备广播数据段中的ManufacturerData数据段
   * @support ANDROID >= 3.17.0
   */
  advertiseData?: string[];
  /**
   * 蓝牙设备广播数据段中的LocalName数据段
   * @support ANDROID >= 3.17.0
   */
  localName?: string;
  /**
   * 蓝牙信号强度（单位dBm）
   * @support ANDROID >= 3.17.0
   */
  rssi?: number;
  /**
   * 蓝牙设备是否可连接（Android 8.0以下不支持该属性）
   * @support ANDROID >= 3.17.0
   */
  connectable?: boolean;
}
代码示例
场景1：全局扫描
const bluetoothDeviceDiscoveryHandler = (resp) => {
  // 蓝牙设备列表
  const { devices } = resp;
﻿
  const targetDevice = devices[0]; // 假设第一个就是目标设备
  const { deviceId } = targetDevice；// 获取到设备的deviceId
﻿
  // 扫描到目标设备后，请结束扫描任务
  wemeet.bluetooth.stopBluetoothDevicesDiscovery();
});
﻿
// 蓝牙扫描完成的回调
wemeet.addEventListener('bluetooth-device-discovery', bluetoothDeviceDiscoveryHandler);
﻿
wemeet.bluetooth.startBluetoothDevicesDiscovery({
  period: 3000, // 扫描周期 单位ms 非必填 默认为3000ms
})
  .then(() => {
    console.log('startBluetoothDevicesDiscovery seccuss');
  })
  .catch(err => {
    console.error('startBluetoothDevicesDiscovery failed');
  });
﻿
场景2：指定特定的设备进行扫描
const bluetoothDeviceDiscoveryHandler = (resp) => {
  // 蓝牙设备列表
  const { devices } = resp;
﻿
  const targetDevice = devices[0]; // 第一个就是目标设备
  const { deviceId } = targetDevice；// 获取到设备的deviceId
﻿
  // 扫描到目标设备后，请结束扫描任务
  wemeet.bluetooth.stopBluetoothDevicesDiscovery();
});
﻿
// 蓝牙扫描完成的回调
wemeet.addEventListener('bluetooth-device-discovery', bluetoothDeviceDiscoveryHandler);
﻿
wemeet.bluetooth.startBluetoothDevicesDiscovery({
  deviceId: 'xxxxx', // 期望搜索到的蓝牙设备id
  period: 5000, // 扫描周期 单位ms 非必填 默认为3000ms
})
  .then(() => {
    console.log('startBluetoothDevicesDiscovery seccuss');
  })
  .catch(err => {
    console.error('startBluetoothDevicesDiscovery failed');
  });
﻿
连接蓝牙设备
JSAPI 接口
createBLEConnection(options: BLEConnectionParam): Promise<void>
﻿
interface BLEConnectionParam {
  /**
   * 需要连接的BLE设备id
   */
  deviceId: string;
}
﻿
代码示例
wemeet.bluetooth.createBLEConnection({
    deviceId: 'xxxxxxxxxx',
})
    .then(() => {
        // 连接的ble设备提成功
    })
    .catch(error => {
        console.error('createBLEConnection failed', error);
    });
获取外围设备提供的服务
JSAPI 接口
getBLEDeviceServices(param: BLEDeviceServicesParam): Promise<BLEDeviceServicesResp>
﻿
interface BLEDeviceServicesParam {
  /**
   * 需要连接的BLE设备id
   */
  deviceId: string;
}
﻿
interface BLEDeviceServicesResp {
  /**
   * 连接的ble设备提供的所有service
   */
  services: BLEServiceItem[];
}
﻿
﻿
/**
 * ble设备提供的service
 */
export interface BLEServiceItem {
  /**
   * service的uuid
   */
  serviceId: string;
  /**
   * 服务的类型
   * 0表示主服务，1表示非主服务
   */
  type: BLEServiceType;
}
代码示例
wemeet.bluetooth.getBLEDeviceServices({
    deviceId: 'xxxxxxxxxx',
})
    .then((resp) => {
        // 连接的ble设备提供的所有service
        const { services } = resp;
        // 假设目标service 是第一个；
        const targetService = services[0];
        // service的uuid
        const { serviceId, type } = targetService;
    })
    .catch(error => {
        console.error('getBLEDeviceServices failed', error);
    });
﻿
获取服务的特征 characteristics
JSAPI 接口
getBLEDeviceCharacteristics(param: BLEDeviceCharacteristicsParam): Promise<BLEDeviceCharacteristicsResp>
﻿
interface BLEDeviceCharacteristicsParam {
  /**
   * 需要连接的BLE设备id
   */
  deviceId: string;
  /**
   * service的uuid
   */
  serviceId: string;
}
﻿
interface BLEDeviceCharacteristicsResp {
  /**
   * 所支持的characteristic列表
   */
  characteristics: BLECharacteristicItem[];
}
﻿
﻿
/**
 * ble设备提供的characteristic
 */
export interface BLECharacteristicItem {
  /**
   * characteristic的uuid
   */
  characteristicId: string;
  /**
   * 特征支持的属性，返回特征支持的属性列表
   */
  property: BLECharacteristicProperty[];
}
﻿
/**
 * BLE设备的特征属性
 */
export enum BLECharacteristicProperty {
  /**
   * 广播特征
   */
  PROPERTY_BROADCAST = 1,
  /**
   * 其他特征
   */
  PROPERTY_EXTENDED_PROPS = 128,
  /**
   * 支持indicate的特征
   */
  PROPERTY_INDICATE = 32,
  /**
   * 支持notify的特征
   */
  PROPERTY_NOTIFY = 16,
  /**
   * 支持读的特征
   */
  PROPERTY_READ = 2,
  /**
   * 支持带签名写的特征
   */
  PROPERTY_SIGNED_WRITE = 64,
  /**
   * 支持写的特征
   */
  PROPERTY_WRITE = 8,
  /**
   * 支持无回调写的特征
   */
  PROPERTY_WRITE_NO_RESPONSE = 4,
}
﻿
代码示例
wemeet.bluetooth.getBLEDeviceCharacteristics({
    deviceId: 'xxxxxxxxxx',
    serviceId: 'xxxxxxxxx',
})
    .then((resp) => {
        // 连接的ble设备提供的某个服务中所有特征
        const { characteristics } = resp;
        // 假设目标characteristic 是第一个；
        const targetCharacteristic = characteristics[0];
        // service的uuid
        const {
            characteristicId, // 蓝牙设备特征的 UUID
            property, // 该特征支持的操作类型
        } = targetCharacteristic;
    })
    .catch(error => {
        console.error('getCharacteristics failed', error);
    });
﻿
读写服务的特征值
JSAPI 接口
// 向蓝牙低功耗设备特征值中写入二进制数据
writeBLECharacteristicValue(param: BLECharacteristicWriteParam): Promise<void>
﻿
interface BLECharacteristicWriteParam {
  /**
   * service的uuid
   */
  serviceId: string;
  /**
   * characteristic的uuid
   */
  characteristicId: string;
  /**
   * 需要写入ble设备的特征值
   */
  value: string;
}
﻿
﻿
// 向蓝牙低功耗设备特征值中写入数据
readBLECharacteristicValue(param: BLECharacteristicReadParam): Promise<void>
﻿
interface BLECharacteristicReadParam {
  /**
   * service的uuid
   */
  serviceId: string;
  /**
   * characteristic的uuid
   */
  characteristicId: string;
}
﻿
﻿
// 设置蓝牙低功耗设备特征值变化时的 notify 功能，订阅特征
setBLECharacteristicValueChangeNotify(param: BLECharacteristicsChangeNotifyParam): Promise<void>
﻿
interface BLECharacteristicsChangeNotifyParam {
  /**
   * service的uuid
   */
  serviceId: string;
  /**
   * characteristic的uuid
   */
  characteristicId: string;
  /**
   * characteristic的descriptor属性的uuid
   */
  descriptorId: string;
  /**
   * 是否开启notify
   */
  enable: boolean;
}
﻿
代码示例
// 向蓝牙低功耗设备特征值中写入数据
wemeet.bluetooth.writeBLECharacteristicValue({
  serviceId: 'xxxxx',
  characteristicId: 'xxxxx',
  value: 'xxxxx',
})
  .then(() => {
    console.log('writeBLECharacteristicValue success');
  })
  .catch(err => {
    console.error('writeBLECharacteristicValue failed', err);
  });
﻿
﻿
// 读取蓝牙低功耗设备特征值的二进制数据
const bleCharacterHandler = (resp) => {
  console.log('bleCharacterValue changed', resp);
};
// 需要监听'ble-characteristic-value-change'获取真正的数据
wemeet.addEventListener('ble-characteristic-value-change', bleCharacterHandler);
﻿
wemeet.bluetooth.readBLECharacteristicValue({
  serviceId: 'xxxxx',
  characteristicId: 'xxxxx',
})
  .then(() => {
    console.log('readBLECharacteristicValue success');
    // 真正的数据在ble-characteristic-value-change事件中获取
  })
  .catch(err => {
    console.error('readBLECharacteristicValue failed', err);
  });
﻿
﻿
// 设置蓝牙低功耗设备特征值变化时的 notify 功能，订阅特征
wemeet.bluetooth.setBLECharacteristicValueChangeNotify({
    serviceId: 'xxxxxxxxxx',
    characteristicId: 'xxxxxxxxx',
﻿
    // 表示ble设备供读取数据的characteristic的descriptor属性的uuid
    descriptorId: 'xxxxxxxxxxxxx',
    enable: true, // 是否开启notify
})
    .catch(error => {
        console.error('setBLECharacteristicValueChangeNotify failed', error);
    });
﻿
const bleCharaValueChangeHandler = (resp) => {
    const {
        characteristicId, // 蓝牙特征的 UUID
        value, // ble设备通知中心设备发生变化的特征值
    } = resp;
    console.log(`characteristic ${characteristicId} changed with: ${value}`);
};
﻿
// 监听BLE特征值变化事件
wemeet.addEventListener('ble-characteristic-value-change', bleCharaValueChangeHandler);
﻿
断开蓝牙连接、关闭蓝牙适配器
JSAPI 接口
closeBluetoothAdapter(): Promise<void>
closeBLEConnection(): Promise<void>
stopBluetoothDevicesDiscovery(): Promise<void>
﻿
代码示例
wemeet.bluetooth.closeBLEConnection();
wemeet.bluetooth.closeBluetoothAdapter();
其他事件
// 监听蓝牙低功耗连接状态改变事件
// 包括开发者主动连接或断开连接，设备丢失，连接异常断开等等
wemeet.addEventListener('bluetooth-connection-state', (resp) => {
    const {
     deviceId, // 蓝牙设备id
     connected, // 是否处于已连接状态
    } = resp;
});
﻿
// 监听蓝牙适配器状态变化事件
wemeet.addEventListener('bluetooth-adapter-state-change', (resp) => {
    const {
        available, // 蓝牙适配器是否可用
    } = resp;
});
﻿
﻿
错误码
/**
 * 蓝牙通用错误码
 */
export enum BluetoothError {
  /**
   * 正常
   */
  OK = 0,
  /**
   * 已连接
   */
  CONNECTED = -1,
  /**
   * 蓝牙适配器初始化失败
   */
  ADAPTER_NOT_INIT = 10000,
  /**
   * 当前蓝牙适配器不可用，一般为蓝牙未启动
   */
  ADAPTER_NOT_AVAILABLE = 10001,
  /**
   * 没有找到指定设备
   */
  DEVICE_NOT_FOUND = 10002,
  /**
   * 连接失败
   */
  CONNECTION_FAIL = 10003,
  /**
   * 没有找到指定服务
   */
  NO_SERVICE = 10004,
  /**
   * 没有找到指定特征
   */
  NO_CHARACTERISTIC = 10005,
  /**
   * 当前连接已断开
   */
  NO_CONNECTION = 10006,
  /**
   * 当前characteristic不支持此操作
   */
  PROPERTY_NOT_SUPPORT = 10007,
  /**
   * 系统异常
   */
  SYSTEM_ERROR = 10008,
  /**
   * 系统不支持，例如Android版本低于3.4不支持BLE
   */
  SYSTEM_NOT_SUPPORT = 10009,
  /**
   * 操作超时，如扫描超时未发现设备
   */
  OPERATE_TIME_OUT = 10012,
  /**
   * 操作超时，如扫描超时未发现设备
   */
  INVALID_DATA = 10013,
}
﻿
﻿
蓝牙

本页目录：

功能描述

使用场景

整体流程

初始化蓝牙设备

JSAPI 接口

代码示例

扫描发现外围设备

JSAPI 接口

代码示例

场景1：全局扫描

场景2：指定特定的设备进行扫描

连接蓝牙设备

JSAPI 接口

代码示例

获取外围设备提供的服务

JSAPI 接口

代码示例

获取服务的特征 characteristics

JSAPI 接口

代码示例

读写服务的特征值

JSAPI 接口

代码示例

断开蓝牙连接、关闭蓝牙适配器

JSAPI 接口

代码示例

其他事件

错误码
