更新记录

1.0.1（2024-05-10） 下载此版本

• 优化了一些连接稳定问题
• 修复订阅接收数据问题
• 增加蓝牙权限判断

1.0.0（2022-07-11） 下载此版本

第一个版本

平台兼容性

原生插件通用使用流程：

1. 购买插件，选择该插件绑定的项目。
2. 在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
3. 根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
4. 打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
5. 开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

蓝牙 API 原生插件兼容说明

简单介绍

Android：基于BLE框架进行实现和完善

框架地址：BLE框架地址

IOS：基于BabyBluetooth框架进行实现和完善

框架地址：BabyBluetooth框架地址

后台运行支持：

iOS后台运行权限配置

iOS 云打包后台权限配置教程

后台运行配置：

"UIBackgroundModes" : [ "bluetooth-central", "fetch" ]

参考示例项目manifest.json源码视图

插件API格式采用和uni-app官方接口基本一致的风格进行搭建和编写，实现功能包含：

• 适配器的状态监听，打开及关闭
• 连接设备和断开设备
• 断线重连
• 获取服务和特征
• 读、写、订阅特征数据

演示预览

演示工程地址：sand-plugin-bluetooth-test项目地址

API目录

openBluetoothAdapter(options,callback)

初始化蓝牙模块

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.openBluetoothAdapter({},(res)=>{
    if(res.status=='2500'){
        //
    }
})

注意：

• 大部分操作类API（监听类API除外）都需要在openBluetoothAdapter之后进行调用，否则会失败，status返回2501-蓝牙未初始化或未开启
• 可通过 onBluetoothAdapterStateChange 监听手机蓝牙状态的改变

startBluetoothDevicesDiscovery(options,callback)

开始搜寻附近的蓝牙外围设备。此操作比较耗费系统资源，请在搜索并连接到设备后调用 stopBluetoothDevicesDiscovery 方法停止搜索。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.startBluetoothDevicesDiscovery({},(res)=>{
    if(res.status=='2500'){
        //
    }
})

注意：开启后获取扫描到的设备需要使用 onBluetoothDeviceFound 进行异步获取，建议先进行监听再扫描

onBluetoothDeviceFound(options,callback)

监听寻找到新设备的事件

options 参数说明

callback 回调函数参数对象说明

devices的结构

示例代码

ble.onBluetoothDeviceFound({},(res)=>{
    if(res.status=='2500'){
        //发现新设备
        let devices=JSON.parse(res.devices);
        console.log(res.devices);
    }
})

注意：

• 受限于uni-app原生插件对返回类型的要求，第二层数据只能采用String类型，需要使用JSON.parse方式进行对象解析
• 监听在插件中只会保存一份，即最后一次调用 onBluetoothDeviceFound 的callback会触发回调事件

stopBluetoothDevicesDiscovery(options,callback)

停止搜寻附近的蓝牙外围设备。若已经找到需要的蓝牙设备并不需要继续搜索时，建议调用该接口停止蓝牙搜索。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.stopBluetoothDevicesDiscovery({},(res)=>{
    if(res.status=='2500'){
        //
    }
})

onBluetoothAdapterStateChange(options,callback)

监听蓝牙适配器状态变化事件

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.onBluetoothAdapterStateChange({},(res)=>{
    if(res.status=='2500'){
        //
    }
})

getConnectedBluetoothDevices(options,callback)

获取处于已连接状态的设备。

options 参数说明

callback 回调函数参数对象说明

devices的结构

示例代码

ble.getConnectedBluetoothDevices({},(res)=>{
    if(res.status=='2500'){
        //发现新设备
        let devices=JSON.parse(res.devices);
        console.log(res.devices);
    }
})

getBluetoothDevices(options,callback)

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

options 参数说明

callback 回调函数参数对象说明

devices的结构

示例代码

ble.getBluetoothDevices({},(res)=>{
    if(res.status=='2500'){
        //发现新设备
        let devices=JSON.parse(res.devices);
        console.log(res.devices);
    }
})

getBluetoothAdapterState(options,callback)

获取本机蓝牙适配器状态。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.getBluetoothAdapterState({},(res)=>{
    if(res.status=='2500'){
        //
    }
})

closeBluetoothAdapter(options,callback)

关闭蓝牙模块。调用该方法将断开所有已建立的连接并释放系统资源。建议在使用蓝牙流程后，与 openBluetoothAdapter 成对调用。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.closeBluetoothAdapter({},(res)=>{
    if(res.status=='2500'){
        //
    }
})

writeBLECharacteristicValue(options,callback)

向低功耗蓝牙设备特征值中写入二进制数据。注意：必须设备的特征值支持 write 才可以成功调用。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.writeBLECharacteristicValue({
    deviceId:'DDCC-EE-AA-BB-CC',
    serviceId:'0000-1902-C503',
    characteristicId:'0000-1902-C503-0001',
    value:'0010'//两个字节：[0,1]
},(res)=>{
    if(res.status=='2500'){
        //写数据完成
    }
})

readBLECharacteristicValue(options,callback)

读取低功耗蓝牙设备的特征值的二进制数据值。注意：必须设备的特征值支持 read 才可以成功调用。

options 参数说明

callback 回调函数参数对象说明

示例代码

// 必须在这里的回调才能获取到值
ble.onBLECharacteristicValueChange({},(res)=>{
    if(res.status=='2500'){
        console.log(res.deviceId);
        console.log(res.serviceId);
        console.log(res.characteristicId);
        console.log(res.value);
    }
});
ble.readBLECharacteristicValue({
    deviceId:'DDCC-EE-AA-BB-CC',
    serviceId:'0000-1902-C503',
    characteristicId:'0000-1902-C503-0001'
},(res)=>{
    if(res.status=='2500'){
        //读取API调用成功,请在onBLECharacteristicValueChange获取特征值数据
    }
});

注意：

• 接口读取到的信息需要在 onBLECharacteristicValueChange 方法注册的回调中获取。

onBLEConnectionStateChange(options,callback)

监听低功耗蓝牙连接状态的改变事件。包括开发者主动连接或断开连接，设备丢失，连接异常断开等等

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.onBLEConnectionStateChange({},(res)=>{
    if(res.status=='2500'){
        //
        console.log(res.deviceId,'连接状态变化',res.connected);
    }
})

onBLECharacteristicValueChange(options,callback)

监听低功耗蓝牙设备的特征值变化事件。必须先启用 notifyBLECharacteristicValueChange 接口才能接收到设备推送的 notification。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.onBLECharacteristicValueChange({},(res)=>{
    if(res.status=='2500'){
        console.log(res.deviceId);
        console.log(res.serviceId);
        console.log(res.characteristicId);
        console.log(res.value);
    }
});

notifyBLECharacteristicValueChange(options,callback)

启用低功耗蓝牙设备特征值变化时的 notify 功能，订阅特征值。注意：必须设备的特征值支持 notify 或者 indicate 才可以成功调用。

options 参数说明

callback 回调函数参数对象说明

示例代码

// 必须在这里的回调才能获取到值
ble.onBLECharacteristicValueChange({},(res)=>{
    if(res.status=='2500'){
        console.log(res.deviceId);
        console.log(res.serviceId);
        console.log(res.characteristicId);
        console.log(res.value);
    }
});
ble.notifyBLECharacteristicValueChange({
    deviceId:'DDCC-EE-AA-BB-CC',
    serviceId:'0000-1902-C503',
    characteristicId:'0000-1902-C503-0001'
},(res)=>{
    if(res.status=='2500'){
        //订阅API调用成功,请在onBLECharacteristicValueChange获取特征值数据
    }
});

cancelNotifyBLECharacteristicValueChange(options,callback)

取消特征值订阅

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.cancelNotifyBLECharacteristicValueChange({
    deviceId:'DDCC-EE-AA-BB-CC',
    serviceId:'0000-1902-C503',
    characteristicId:'0000-1902-C503-0001'
},(res)=>{
    if(res.status=='2500'){
        //订阅API调用成功，已取消订阅
    }
});

getBLEDeviceServices(options,callback)

获取蓝牙设备所有服务(service)。

options 参数说明

callback 回调函数参数对象说明

services内对象结构

示例代码

ble.getBLEDeviceServices({
    deviceId:'DDCC-EE-AA-BB-CC'
},(res)=>{
    if(res.status=='2500'){
        let services=JSON.parse(res.services);
        console.log(services);
    }
});

getBLEDeviceRSSI(options,callback)

获取蓝牙设备的实时信号强度。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.getBLEDeviceRSSI({
    deviceId:'DDCC-EE-AA-BB-CC'
},(res)=>{
    if(res.status=='2500'){
        console.log(res.RSSI);
    }
});

getBLEDeviceCharacteristics(options,callback)

获取蓝牙设备某个服务中所有特征值(characteristic)。

options 参数说明

callback 回调函数参数对象说明

characteristics内对象结构

properties 的结构

示例代码

ble.getBLEDeviceCharacteristics({
    deviceId:'DDCC-EE-AA-BB-CC',
    serviceId:'0000-1902-C503'
},(res)=>{
    if(res.status=='2500'){
        let characteristics=JSON.parse(res.characteristics);
        console.log(characteristics);
    }
});

createBLEConnection(options,callback)

连接低功耗蓝牙设备。

若APP在之前已有搜索过某个蓝牙设备，并成功建立连接，可直接传入之前搜索获取的 deviceId 直接尝试连接该设备，无需进行搜索操作。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.onBLEConnectionStateChange({},(res)=>{
    if(res.status=='2500'){
        //
        console.log(res.deviceId,'连接状态变化',res.connected);
    }
});
ble.createBLEConnection({
    deviceId:'DDCC-EE-AA-BB-CC'
},(res)=>{
    if(res.status=='2500'){
        //接口调用成功，请在onBLEConnectionStateChange 监听状态变化
    }
});

closeBLEConnection(options,callback)

断开与低功耗蓝牙设备的连接。

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.onBLEConnectionStateChange({},(res)=>{
    if(res.status=='2500'){
        //
        console.log(res.deviceId,'连接状态变化',res.connected);
    }
});
ble.closeBLEConnection({
    deviceId:'DDCC-EE-AA-BB-CC'
},(res)=>{
    if(res.status=='2500'){
        //接口调用成功，请在onBLEConnectionStateChange 监听状态变化
    }
});

addAutoReconnect(options,callback)

将设备加入断线重连队列中，设备断开后将自动进行重连操作

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.addAutoReconnect({
    deviceId:'DDCC-EE-AA-BB-CC'
},(res)=>{
    if(res.status=='2500'){
        //接口调用成功，已成功加入断线重连队列
    }
});

removeAutoReconnect(options,callback)

将设备从断线重连队列中移除，设备断开后不会自动重连，需要手动调用createBLEConnection重新连接

options 参数说明

callback 回调函数参数对象说明

示例代码

ble.removeAutoReconnect({
    deviceId:'DDCC-EE-AA-BB-CC'
},(res)=>{
    if(res.status=='2500'){
        //接口调用成功，已成功从断线重连队列移除
    }
});

状态码status说明