BLE蓝牙UTS插件(支持Android和iOS)

更新记录

1.0.1（2024-09-09）

实现 iOS 和 android 低功耗蓝牙: 扫描、连接、订阅特征、收发数据，本插件是中心设备(Central)。

权限配置

【1】将 uni_modules -> uw-ble -> utssdk -> app-android -> AndroidManifest.xml 和 uni_modules -> uw-ble -> utssdk -> app-ios -> Info.plist 拷贝到项目工程中(和 App.uvue 同级目录)
【2】根据实际情况在 AndroidManifest.xml 和 Info.plist 中申明需要的权限

快速集成(运行需要打包自定调试基座)

1. 在对应的 uvue 页面引入需要的 type 和接口:

import {
    /*** type ***/
    UwBleFail, // 返回码(errCode == 0 为正常，其他查看 interface.uts 具体说明)
    UwBleDevice, // 蓝牙设备
    UwBleDeviceList, // 包含设备数组的 type
    UwBleService, // 蓝牙服务
    UwBleServiceList, // 包含服务数组的 type
    UwBleCharacter, // 特征
    UwBleCharacterList, // 包含特征数组的 type

    /*** 接口 ***/
    uw_ble_open_adapter, // 初始化蓝牙模块
    uw_ble_android_request_permission, // (安卓端)申请(运行时)权限
    uw_ble_close_adapter, // 关闭蓝牙模块
    uw_ble_adapter_state, // 适配器状态
    uw_ble_is_scanning, // 是否正在扫描
    uw_ble_on_adapter_state_change, // 监听蓝牙适配器状态变化事件
    uw_ble_off_adapter_state_change, // 注销蓝牙适配器状态变化事件
    uw_ble_scan_devices, // 开始搜寻附近的蓝牙外围设备
    uw_ble_stop_scan_devices, // 停止搜寻附近的蓝牙外围设备
    uw_ble_on_device_found, // 监听寻找到新设备的事件
    uw_ble_off_device_found, // 注销寻找到新设备的事件
    uw_ble_scanned_devices, // 获取在蓝牙模块生效期间所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备
    uw_ble_create_connect, // 连接低功耗蓝牙设备
    uw_ble_close_connect, // 断开与低功耗蓝牙设备的连接
    uw_ble_on_connect_state_change, // 监听低功耗蓝牙连接状态的改变事件
    uw_ble_off_connect_state_change, // 注销低功耗蓝牙连接状态的改变事件
    uw_ble_discover_services, // 获取蓝牙设备服务
    uw_ble_get_characters, // 获取蓝牙设备某个服务中的特征值
    uw_ble_notify_character, // 启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值
    uw_ble_on_character_value_change, // 监听低功耗蓝牙设备的特征值变化事件
    uw_ble_off_character_value_change, // 注销低功耗蓝牙设备的特征值变化事件
    uw_ble_read_character_value, // 读取低功耗蓝牙设备的特征值的二进制数据值
    uw_ble_write_character_value // 向低功耗蓝牙设备特征值中写入二进制数据
} from "@/uni_modules/uw-ble";

2. 接口调用

安卓权限申请

注意：安卓12及以上，在使用相应的功能之前需要申请相应的权限，可以使用uni提供的权限接口申请，也可以使用SDK提供的接口申请
// 广播(运行时权限: android 12 以及上，APP 需要主动申请)
"android.permission.BLUETOOTH_ADVERTISE"
// 扫描(运行时权限: android 12 以及上，APP 需要主动申请)
"android.permission.BLUETOOTH_SCAN"
// 连接(运行时权限: android 12 以及上，APP 需要主动申请)
"android.permission.BLUETOOTH_CONNECT"
// 精准定位(运行时权限: android 12 以及上，APP 需要主动申请)
"android.permission.ACCESS_FINE_LOCATION"
// 模糊定位(运行时权限: android 12 以及上，APP 需要主动申请)
"android.permission.ACCESS_COARSE_LOCATION"
// 后台定位(运行时权限: android 12 以及上，APP 需要主动申请)
"android.permission.ACCESS_BACKGROUND_LOCATION"

例如调用扫描接口之前，先申请扫描权限
uw_ble_android_request_permission(['android.permission.ACCESS_FINE_LOCATION', 'android.permission.BLUETOOTH_SCAN'], (err : UwBleFail) => {
    console.log("请求扫描权限成功", err.errCode);
}, () => {
    console.log("请求扫描权限失败");
});

初始化蓝牙模块

uw_ble_open_adapter((err : UwBleFail) => {
console.log("蓝牙适配器初始化异常", err.errCode);
}, () => {
    console.log("蓝牙适配器初始化成功");
});

关闭蓝牙模块

uw_ble_close_adapter();

适配器状态

const state : UwBleFail = uw_ble_adapter_state();
if (state.errCode == 0) {
    console.log("蓝牙适配器状态可用");
} else {
    console.log("蓝牙适配器状态异常:", err.errCode);
}

是否正在扫描

let isScanning : boolean = uw_ble_is_scanning();
if (isScanning) {
    console.log("正在扫描设备");
}

适配器状态监听(仅iOS有效，安卓仅支持 uw_ble_adapter_state 同步获取)

uw_ble_on_adapter_state_change((err : UwBleFail) => {
    if (err.errCode == 0) {
        console.log("蓝牙适配器状态可用");
    } else {
        console.log("蓝牙适配器状态异常:", err.errCode);
    }
});

注销蓝牙适配器状态变化事件

uw_ble_off_adapter_state_change();

开始搜寻附近的蓝牙外围设备

const serviceIds : string[] = ["xxx"]; // 要搜索的蓝牙设备主 service 的 uuid 列表
const repeats : boolean = false; // 是否允许重复上报同一设备
const interval : number = 0; // 上报设备的间隔，0 表示找到新设备立即上报，其他数值根据传入的间隔上报(单位毫秒)
const level : string = "medium"; // (android)扫描模式('low' | 'medium' | 'high')
uw_ble_scan_devices(serviceIds, repeats, interval, level, (err : UwBleFail) => {
    console.log("扫描接口调用异常:", err.errMsg);
}, () => {
    console.log("扫描接口调用成功，在 uw_ble_on_device_found 回调中监听获取具体的设备信息");
});

注意：安卓12及以上，调用扫描接口之前，需要先申请扫描权限
uw_ble_android_request_permission(['android.permission.BLUETOOTH_SCAN'], (err : UwBleFail) => {
    console.log("请求权限成功", err.errCode);
}, () => {
    console.log("请求权限失败");
});

停止搜寻附近的蓝牙外围设备

uw_ble_stop_scan_devices();

监听寻找到新设备的事件

uw_ble_on_device_found((res : UwBleDeviceList) => {
    const devices : UwBleDevice[] = res.devices;
    for (let i = 0; i < devices.length; i++) {
        const device : UwBleDevice = devices[i];
        console.log("设备id:", device.deviceId);
        console.log("设备名称:", device.name);
        console.log("设备本地化名称:", device.localName);
        console.log("设备信号强度:", device.RSSI);
        console.log("设备服务id:", device.advertisServiceUUIDs);
        console.log("设备advertisData:", device.advertisData);
    }
});

注销寻找到新设备的事件

uw_ble_off_device_found();

获取在蓝牙模块生效期间所有已发现的蓝牙设备，包括已经和本机处于连接状态的设备

const deviceList : UwBleDeviceList = uw_ble_scanned_devices();
const devices : UwBleDevice = deviceList.devices;
for (let i = 0; i < devices.length; i++) {
    const device : UwBleDevice = devices[i];
    console.log("设备id:", device.deviceId);
    console.log("设备名称:", device.name);
    console.log("设备本地化名称:", device.localName);
    console.log("设备信号强度:", device.RSSI);
    console.log("设备服务id:", device.advertisServiceUUIDs);
    console.log("设备advertisData:", device.advertisData);
}

连接低功耗蓝牙设备

const deviceId : string = "xxx"; // 设备id
const timeout : number = 0; // 连接超时时间，0代表不超时，单位毫秒
uw_ble_create_connect(deviceId, timeout, (err : UwBleFail) => {
    console.log("蓝牙设备连接异常:", err.errCode);
}, () => {
    console.log("蓝牙设备连接成功，也可在 uw_ble_on_connect_state_change 回调中监听连接状态");
});

注意：安卓12及以上，调用连接接口之前，需要先申请连接权限
uw_ble_android_request_permission(['android.permission.BLUETOOTH_CONNECT'], (err : UwBleFail) => {
    console.log("请求权限成功", err.errCode);
}, () => {
    console.log("请求权限失败");
});

断开与低功耗蓝牙设备的连接(在 uw_ble_on_connect_state_change 回调中监听连接状态)

const deviceId : string = "xxx"; // 设备id
discover_services(deviceId);

监听低功耗蓝牙连接状态的改变事件

const deviceId : string = "xxx"; // 设备id
uw_ble_on_connect_state_change((deviceId : string, state : boolean) => {
    if (state) {
        console.log("设备已连接:", deviceId, state);
    } else {
        console.log("设备已断开:", deviceId, state);
    }
});

注销低功耗蓝牙连接状态的改变事件

uw_ble_off_connect_state_change();

获取蓝牙设备的服务

// 必须先调用 uw_ble_create_connect 连接设备
const deviceId : string = "xxx"; // 设备id
uw_ble_discover_services(deviceId, (err : UwBleFail) => {
    console.log("获取服务异常:", err.errCode);
}, (res : UwBleServiceList) => {
    const services : UwBleService[] = res.services;
    for (let i = 0; i < services.length; i++) {
        const service : UwBleService = services[i];
        console.log("服务id:", service.uuid);
        console.log("是否主服务:", service.isPrimary);
    }
});

获取蓝牙设备某个服务中的特征值

// 必须按顺序: 调用 uw_ble_create_connect 连接设备，调用 uw_ble_discover_services 获取服务id
const deviceId : string = "xxx"; // 设备id
const serviceId : string = "xxx"; // 服务id
uw_ble_get_characters(deviceId, serviceId, (err : UwBleFail) => {
    console.log("获取特征异常:", err.errCode);
}, (res : UwBleCharacterList) => {
    const characters : UwBleCharacter[] = res.characters;
    for (let i = 0; i < characters.length; i++) {
        const character : UwBleCharacter = characters[i];
        console.log("特征id:", character.uuid);
        console.log("特征是否支持 read 操作:", character.read);
        console.log("特征是否支持 write 操作:", character.write);
        console.log("特征是否支持 notify 操作:", character.notify);
        console.log("特征是否支持 indicate 操作:", character.indicate);
    }
});

启用低功耗蓝牙设备特征值变化时的 notify 功能

// 必须按顺序: 调用 uw_ble_create_connect 连接设备，调用 uw_ble_discover_services 获取服务id，调用 uw_ble_get_characters 获取特征id
const deviceId : string = "xxx"; // 设备id
const serviceId : string = "xxx"; // 服务id
const characterId : string = "xxx"; // 特征id
const type : string = "notification"; // 发送数据的方式("indication" | "notification")
uw_ble_notify_character(deviceId, serviceId, characterId, type, (err : UwBleFail) => {
    console.log("订阅特征异常:", err.errCode);
}, () => {
    console.log("订阅特征成功，可在 uw_ble_on_character_value_change 中监听具体的特征值变化");             
});

监听低功耗蓝牙设备的特征值变化事件

uw_ble_on_character_value_change((deviceid : string, serviceId : string, characterId : string, value : Number[]) => {
    console.log("特征值变化(设备id):", deviceid);
    console.log("特征值变化(服务id):", serviceId);
    console.log("特征值变化(特征id):", characterId);
    console.log("特征值变化(特征值):", value);
});

注销低功耗蓝牙设备的特征值变化事件

const deviceId : string = "xxx"; // 设备id
uw_ble_off_character_value_change();

读取低功耗蓝牙设备的特征值的二进制数据值

read_character_value(deviceId);

向低功耗蓝牙设备特征值中写入二进制数据

// 必须按顺序: 调用 uw_ble_create_connect 连接设备，调用 uw_ble_discover_services 获取服务id，调用 uw_ble_get_characters 获取特征id
const deviceId : string = "xxx"; // 设备id
const serviceId : string = "xxx"; // 服务id
const characterId : string = "xxx"; // 特征id
const writeType : string = "xxx"; 蓝牙特征值的写模式设置，write(强制回复写)，writeNoResponse(强制无回复写)
let buffer : number[] = [0x0f, 0xa1, 0xd2, 0x04, 0x00, 0x01, 0x79]; // 特征值(二进制数据)
uw_ble_write_character_value(deviceId, serviceId, characterId, writeType, buffer, (err : UwBleFail) => {
    console.log("写特征值异常:", err.errCode);
}, () => {
    console.log("写特征值成功");
});

1.0.0（2024-08-19）

第一版发布

平台兼容性

Vue2	Vue3
×	√

App	快应用	微信小程序	支付宝小程序	百度小程序	字节小程序	QQ小程序
HBuilderX 4.23，Android：8.0，iOS：13，HarmonyNext：不确定	×	×	×	×	×	×

钉钉小程序	快手小程序	飞书小程序	京东小程序
×	×	×	×

H5-Safari	Android Browser	微信浏览器(Android)	QQ浏览器(Android)	Chrome	IE	Edge	Firefox	PC-Safari
×	×	×	×	×	×	×	×	×