更新记录

1.0.0(2022-07-11)

第一个版本


平台兼容性

Android Android CPU类型 iOS
适用版本区间:4.4w - 11.0 armeabi-v7a:未测试,arm64-v8a:未测试,x86:未测试 适用版本区间:9 - 15

原生插件通用使用流程:

  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 IOS
4.4w(20)-最新 9.0-最新

简单介绍

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 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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

注意:

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

startBluetoothDevicesDiscovery(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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

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


onBluetoothDeviceFound(options,callback)

监听寻找到新设备的事件

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
devices String 设备信息JSON格式数组字符串信息

devices的结构

属性 类型 说明
name string 蓝牙设备名称,某些设备可能没有
deviceId string 用于区分设备的 id
RSSI number 当前蓝牙设备的信号强度
advertisData string 当前蓝牙设备的广播数据段中的 ManufacturerData 数据段(十六进制字符串,每2个字符对应一个字节)
advertisServiceUUIDs Array 当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName string 当前蓝牙设备的广播数据段中的 LocalName 数据段

示例代码

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 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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

onBluetoothAdapterStateChange(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
available boolean 蓝牙是否可用
discovering boolean 是否正在搜索附近设备

示例代码

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

getConnectedBluetoothDevices(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
devices String 设备信息JSON格式数组字符串信息

devices的结构

属性 类型 说明
name string 蓝牙设备名称,某些设备可能没有
deviceId string 用于区分设备的 id
RSSI number 当前蓝牙设备的信号强度
advertisData string 当前蓝牙设备的广播数据段中的 ManufacturerData 数据段(十六进制字符串,每2个字符对应一个字节)
advertisServiceUUIDs Array 当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName string 当前蓝牙设备的广播数据段中的 LocalName 数据段

示例代码

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

getBluetoothDevices(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
devices String 设备信息JSON格式数组字符串信息

devices的结构

属性 类型 说明
name string 蓝牙设备名称,某些设备可能没有
deviceId string 用于区分设备的 id
restore boolean 是否是可以后台恢复的设备,true-可直接使用createBLEConnection进行恢复连接动作
RSSI number 当前蓝牙设备的信号强度
advertisData string 当前蓝牙设备的广播数据段中的 ManufacturerData 数据段(十六进制字符串,每2个字符对应一个字节)
advertisServiceUUIDs Array 当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localName string 当前蓝牙设备的广播数据段中的 LocalName 数据段

示例代码

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

getBluetoothAdapterState(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
available boolean 蓝牙是否可用
discovering boolean 是否正在搜索附近设备

示例代码

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

closeBluetoothAdapter(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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

writeBLECharacteristicValue(options,callback)

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

options 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id
serviceId string 蓝牙特征值对应服务的 uuid
characteristicId string 蓝牙特征值的 uuid
value string 蓝牙设备特征值二进制字节数组对应转换的十六进制字符串值

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id
serviceId string 蓝牙特征值对应服务的 uuid
characteristicId string 蓝牙特征值的 uuid

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

// 必须在这里的回调才能获取到值
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 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
deviceId string 蓝牙设备ID
connected boolean 是否处于已连接状态

示例代码

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

onBLECharacteristicValueChange(options,callback)

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

options 参数说明

属性 类型 是否必填 说明

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
deviceId string 蓝牙设备 id
serviceId string 蓝牙特征值对应服务的 uuid
characteristicId String 蓝牙特征值的 uuid
value String 蓝牙设备特征值二进制字节数组对应转换的十六进制字符串值

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id
serviceId string 蓝牙特征值对应服务的 uuid
characteristicId string 蓝牙特征值的 uuid

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

// 必须在这里的回调才能获取到值
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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id
serviceId string 蓝牙特征值对应服务的 uuid
characteristicId string 蓝牙特征值的 uuid

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
services String JSON数组格式字符串

services内对象结构

属性 类型 说明
uuid string 蓝牙设备服务的 uuid
isPrimary boolean 该服务是否为主服务

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
deviceId string 蓝牙设备 id
RSSI number 信号强度值

示例代码

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

getBLEDeviceCharacteristics(options,callback)

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

options 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id
serviceId string 蓝牙特征值对应服务的 uuid

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明
characteristics String JSON数组格式字符串

characteristics内对象结构

属性 类型 说明
uuid string 蓝牙设备特征值的 uuid
properties Object 该特征值支持的操作类型

properties 的结构

属性 类型 说明
read boolean 该特征值是否支持 read 操作
write boolean 该特征值是否支持 write 操作
notify boolean 该特征值是否支持 notify 操作
indicate boolean 该特征值是否支持 indicate 操作

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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

removeAutoReconnect(options,callback)

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

options 参数说明

属性 类型 是否必填 说明
deviceId string 蓝牙设备 id

callback 回调函数参数对象说明

属性 类型 说明
status String 接口调用状态
message String 状态说明

示例代码

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

状态码status说明

status 说明
2500 操作成功
2501 蓝牙不可用
2502 设备未发现
2503 服务或特征等未找到
2504 不支持的操作
2505 未知系统错误

隐私、权限声明

1. 本插件需要申请的系统权限列表:

蓝牙权限,模糊地理位置权限(高版本安卓系统(>6.0)要求的关联权限)

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

许可协议

请参考开源项目地址的开源协议

使用中有什么不明白的地方,就向插件作者提问吧~ 我要提问