bluetooth常见问题我要提意见
Bluetooth模块用于管理蓝牙设备,搜索附近蓝牙设备、实现简单数据传输等。
支持搜索发现所有蓝牙设备,但仅支持低功耗蓝牙ble传输协议,不支持蓝牙设备的配对连接传输大量数据。 如果要连接非ble蓝牙设备,可以使用Native.js调用(请到http://ask.dcloud.net.cn搜索bluetooth相关问答)。
方法:
- closeBluetoothAdapter: 关闭蓝牙模块
- getBluetoothAdapterState: 获取本机蓝牙适配器状态
- getBluetoothDevices: 获取已搜索到的蓝牙设备
- getConnectedBluetoothDevices: 根据uuid获取处于已连接的设备
- onBluetoothAdapterStateChange: 监听蓝牙适配器状态变化事件
- onBluetoothDeviceFound: 监听搜索到新设备的事件
- openBluetoothAdapter: 初始化蓝牙模块
- startBluetoothDevicesDiscovery: 开始搜索附近的蓝牙设备
- stopBluetoothDevicesDiscovery: 停止搜寻附近的蓝牙外围设备
- closeBLEConnection: 断开与低功耗蓝牙设备的连接
- createBLEConnection: 连接低功耗蓝牙设备
- setBLEMTU: 设置蓝牙最大传输单元
- getBLEDeviceCharacteristics: 获取蓝牙设备指定服务中所有特征值(characteristic)
- getBLEDeviceRSSI: 获取蓝牙设备的信号强度
- getBLEDeviceServices: 获取蓝牙设备的所有服务(service)
- notifyBLECharacteristicValueChange: 启用低功耗蓝牙设备特征值变化时的notify功能,订阅特征值
- onBLECharacteristicValueChange: 监听低功耗蓝牙设备的特征值变化事件
- onBLEConnectionStateChange: 监听低功耗蓝牙设备连接状态变化事件
- readBLECharacteristicValue: 读取低功耗蓝牙设备指定特征值的二进制数据值
- writeBLECharacteristicValue: 向低功耗蓝牙设备指定特征值写入二进制数据
对象:
- BluetoothDeviceInfo: 蓝牙设备信息
- BluetoothService: 蓝牙设备服务信息
- Bluetoothcharacteristic: 蓝牙设备特征值
- BluetoothcharacteristicProperties: 蓝牙设备特征值支持的操作类型
回调方法:
- BluetoothSuccessCallback: 成功回调函数
- BluetoothFailCallback: 失败回调函数
- BluetoothCompleteCallback: 操作完成回调函数
- BluetoothAdapterStateChangeCallback: 蓝牙适配器状态变化事件回调函数
- BluetoothDeviceFoundCallback: 蓝牙适配器搜索到新设备事件回调函数
- BluetoothDeviceRSSICallback: 获取蓝牙设备信号强度成功回调函数
- BLEConnectionStateChangeCallback: 低功耗蓝牙设备连接状态变化事件回调函数
- BLECharacteristicValueChangeCallback: 低功耗蓝牙设备的特征值变化事件回调函数
权限:
5+功能模块(permissions)
{
// ...
"permissions":{
// ...
"Bluetooth": {
"description": "Bluetooth"
}
}
}
closeBluetoothAdapter
关闭蓝牙模块
void plus.bluetooth.closeBluetoothAdapter(options);
说明:
断开所有已经建立的连接,释放系统资源,要求在蓝牙功能使用完成后调用(于openBluetoothAdapter成对使用)。 关闭成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- success:
(
BluetoothSuccessCallback
)
可选 关闭蓝牙模块成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 关闭蓝牙模块失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 关闭蓝牙模块操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 关闭蓝牙模块
function closeBluetoothAdapter(){
plus.bluetooth.closeBluetoothAdapter({
success:function(e){
console.log('close success: '+JSON.stringify(e));
},
fail:function(e){
console.log('close failed: '+JSON.stringify(e));
}
});
}
getBluetoothAdapterState
获取本机蓝牙适配器状态
void plus.bluetooth.getBluetoothAdapterState(options);
说明:
获取成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- success:
(
BluetoothSuccessCallback
)
可选 获取蓝牙适配器状态成功回调函数
回调函数参数event对象包括以下属性: discovering - Boolean类型,蓝牙适配器是否正在搜索设备; available - Boolean类型,蓝牙适配器是否可用。
- fail:
(
BluetoothFailCallback
)
可选 获取蓝牙适配器状态错误回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 获取蓝牙适配器状态操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 获取蓝牙状态
function getBluetoothState(){
plus.bluetooth.getBluetoothAdapterState({
success:function(e){
console.log('state success: '+JSON.stringify(e));
},
fail:function(e){
console.log('state failed: '+JSON.stringify(e));
}
});
}
getBluetoothDevices
获取已搜索到的蓝牙设备
void plus.bluetooth.getBluetoothDevices(options);
说明:
包括已经和本机处于连接状态的设备。 获取成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- success:
(
BluetoothSuccessCallback
)
可选 获取蓝牙设备成功回调函数
回调函数参数event对象包括以下属性: devices - Array<Object>,设备列表信息。
- fail:
(
BluetoothFailCallback
)
可选 获取蓝牙设备失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 获取蓝牙设备操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 获取已搜索到的蓝牙设备
function getBluetoothDevices(){
plus.bluetooth.getBluetoothDevices({
success:function(e){
var devices = e.devices;
console.log('get devices success: '+e.length);
for(var i in devices){
console.log(i+': '+JSON.stringify(devices[i]));
}
},
fail:function(e){
console.log('get devices failed: '+JSON.stringify(e));
}
});
}
getConnectedBluetoothDevices
根据uuid获取处于已连接的设备
void plus.bluetooth.getConnectedBluetoothDevices(options);
说明:
获取成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- services:
(
Array[String]
)
必选 要获取设备的uuid列表
蓝牙设备主service的uuid列表。
- success:
(
BluetoothSuccessCallback
)
可选 获取已连接设备成功回调函数
回调函数参数event对象包括以下属性: devices - Array<BluetoothDeviceInfo>,设备列表信息(只包含name和deviceId属性)。
- fail:
(
BluetoothFailCallback
)
可选 获取已连接设备失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 获取已连接设备操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 获取已连接的蓝牙设备
function getConnectedDevices(){
plus.bluetooth.getConnectedBluetoothDevices({
success:function(e){
var devices = e.devices;
console.log('connected devices success: '+e.length);
for(var i in devices){
console.log(i+': '+JSON.stringify(devices[i]));
}
},
fail:function(e){
console.log('connected devices failed: '+JSON.stringify(e));
}
});
}
onBluetoothAdapterStateChange
监听蓝牙适配器状态变化事件
void plus.bluetooth.onBluetoothAdapterStateChange(changeCB);
说明:
蓝牙适配器状态发生变化时触发回调。
参数:
- changeCB:
(
BluetoothAdapterStateChangeCallback
)
必选 状态变化回调函数
回调函数参数event对象包括以下属性: discovering - Boolean类型,蓝牙适配器是否正在搜索设备; available - Boolean类型,蓝牙适配器是否可用。
返回值:
void : 无示例:
// 监听状态变化
function listenerStateChange(){
plus.bluetooth.onBluetoothAdapterStateChange(function(e){
console.log('state changed: '+JSON.stringify(e));
});
}
onBluetoothDeviceFound
监听搜索到新设备的事件
void plus.bluetooth.onBluetoothDeviceFound(callback);
说明:
搜索到新设备时触发回调。
参数:
- callback:
(
BluetoothDeviceFoundCallback
)
必选 搜索到新设备回调函数
回调函数参数event对象包括以下属性: devices - Array<BluetoothDeviceInfo>,设备列表信息。
返回值:
void : 无示例:
// 监听发现新设备
function listenerDeviceFound(){
plus.bluetooth.onBluetoothDeviceFound(function(e){
var devices = e.devices;
console.log('device found: '+e.length);
for(var i in devices){
console.log(i+': '+JSON.stringify(devices[i]));
}
});
}
openBluetoothAdapter
初始化蓝牙模块
void plus.bluetooth.openBluetoothAdapter(options);
说明:
初始化成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- success:
(
BluetoothSuccessCallback
)
可选 初始化成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 初始化失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 初始化操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 打开蓝牙模块
function openBluetoothAdapter(){
plus.bluetooth.openBluetoothAdapter({
success:function(e){
console.log('open success: '+JSON.stringify(e));
},
fail:function(e){
console.log('open failed: '+JSON.stringify(e));
}
});
}
startBluetoothDevicesDiscovery
开始搜索附近的蓝牙设备
void plus.bluetooth.startBluetoothDevicesDiscovery(options);
说明:
此操作比较耗费系统资源,请在搜索并连接到设备后调用stopBluetoothDevicesDiscovery方法停止搜索。 搜索成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- services:
(
Array[String]
)
可选 要获取设备的uuid列表
- allowDuplicatesKey:
(
Boolean
)
可选 是否允许重复上报同一设备
如果允许重复上报,则onBlueToothDeviceFound方法会多次上报同一设备,但是RSSI值会有不同。
- interval:
(
Number
)
可选 上报设备的间隔
0表示找到新设备立即上报,其他数值根据传入的间隔上报。
- success:
(
BluetoothSuccessCallback
)
可选 开始搜索成功回调函数
搜索到设备后通过onBluetoothDeviceFound设置的回调返回设备信息,此回调只是表明开始搜索。
- fail:
(
BluetoothFailCallback
)
可选 开始搜索失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 开始搜索操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 开始搜索蓝牙
function startBluetoothDiscovery(){
plus.bluetooth.openBluetoothAdapter({
success:function(e){
console.log('open success: '+JSON.stringify(e));
plus.bluetooth.startBluetoothDevicesDiscovery({
success:function(e){
console.log('start discovery success: '+JSON.stringify(e));
},
fail:function(e){
console.log('start discovery failed: '+JSON.stringify(e));
}
});
},
fail:function(e){
console.log('open failed: '+JSON.stringify(e));
}
});
}
stopBluetoothDevicesDiscovery
停止搜寻附近的蓝牙外围设备
void plus.bluetooth.stopBluetoothDevicesDiscovery(options);
说明:
若已经找到需要的蓝牙设备并不需要继续搜索时,应该调用该接口停止蓝牙搜索。 停止成功后触发options参数中的success回调,失败触发options参数中的fail回调。
参数:
options参数为json类型,包含以下属性:
- success:
(
BluetoothSuccessCallback
)
可选 停止搜寻成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 停止搜寻失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 停止搜寻操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 结束搜索蓝牙
function stopBluetoothDiscovery(){
plus.bluetooth.stopBluetoothDevicesDiscovery({
success:function(e){
console.log('stop discovery success: '+JSON.stringify(e));
plus.bluetooth.closeBluetoothAdapter({
success:function(e){
console.log('close success: '+JSON.stringify(e));
},
fail:function(e){
console.log('close failed: '+JSON.stringify(e));
}
});
},
fail:function(e){
console.log('stop discovery failed: '+JSON.stringify(e));
}
});
}
closeBLEConnection
断开与低功耗蓝牙设备的连接
void plus.bluetooth.closeBLEConnection(options);
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- success:
(
BluetoothSuccessCallback
)
可选 断开连接成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 断开连接失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 断开连接操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 断开蓝牙设备
function closeConnection(){
plus.bluetooth.closeBLEConnection({
deviceId:deviceId,
success:function(e){
console.log('close success: '+JSON.stringify(e));
},
fail:function(e){
console.log('close failed: '+JSON.stringify(e));
}
});
}
createBLEConnection
连接低功耗蓝牙设备
void plus.bluetooth.createBLEConnection(options);
说明:
若之前已有搜索过某个蓝牙设备,并成功建立连接,可直接传入之前搜索获取的deviceId尝试连接该设备,无需进行搜索操作。
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- timeout:
(
Number
)
可选 超时时间
单位为ms(毫秒),不设置此属性表示不会超时。
- success:
(
BluetoothSuccessCallback
)
可选 连接成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 连接失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 连接操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 连接蓝牙设备
function createConnection(){
plus.bluetooth.createBLEConnection({
deviceId:deviceId,
success:function(e){
console.log('create connection success: '+JSON.stringify(e));
},
fail:function(e){
console.log('create connection failed: '+JSON.stringify(e));
}
});
}
setBLEMTU
设置蓝牙最大传输单元
void plus.bluetooth.setBLEMTU(options);
说明:
需在 createBLEConnection 调用成功后调用,mtu 设置范围 (22,512)。 HBuilderX2.8.4+版本支持。
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 设备的 id
- mtu:
(
Number
)
必选 最大传输单元(22,512) 区间内,单位为字节(bytes)
- success:
(
BluetoothSuccessCallback
)
可选 设置蓝牙最大传输单元成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 设置蓝牙最大传输单元失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 设置蓝牙最大传输单元操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无平台支持:
- Android - 5.1+ (支持)
- iOS - ALL (不支持)
示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 连接蓝牙设备设置最大传输单元
function createConnection(){
plus.bluetooth.createBLEConnection({
deviceId:deviceId,
success:function(e){
console.log('create connection success: '+JSON.stringify(e));
plus.bluetooth.setBLEMTU({
deviceId:deviceId,
mtu:512,
success:function(e){
console.log('set MTU success: '+JSON.stringify(e));
},
fail:function(e){
console.log('set MTU failed: '+JSON.stringify(e));
}
});
},
fail:function(e){
console.log('create connection failed: '+JSON.stringify(e));
}
});
}
getBLEDeviceCharacteristics
获取蓝牙设备指定服务中所有特征值(characteristic)
void plus.bluetooth.getBLEDeviceCharacteristics(options);
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- serviceId:
(
String
)
必选 蓝牙服务 uuid
可通过getBLEDeviceServices获取。
- success:
(
BluetoothSuccessCallback
)
可选 获取特征值成功回调函数
回调函数参数event对象包括以下属性: characteristics - Array>Bluetoothcharacteristic<类型,蓝牙设备服务的特征值列表。
- fail:
(
BluetoothFailCallback
)
可选 获取特征值失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 获取特征值操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务uuid,可通过getBLEDeviceServices方法获取
var serviceId = '';
// 获取蓝牙设备指定服务中所有特征值
function getCharacteristics(){
plus.bluetooth.getBLEDeviceCharacteristics({
deviceId:deviceId,
serviceId:serviceId,
success:function(e){
var characteristics = e.characteristics;
console.log('get characteristics success: '+characteristics.length);
for(var i in characteristics){
console.log(i+': '+JSON.stringify(characteristics[i]));
}
},
fail:function(e){
console.log('get characteristics failed: '+JSON.stringify(e));
}
});
}
getBLEDeviceRSSI
获取蓝牙设备的信号强度
void plus.bluetooth.getBLEDeviceRSSI(options);
说明:
需在 createBLEConnection 调用成功后调用。 HBuilderX2.8.4+版本支持。
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 设备的 id
- success:
(
BluetoothDeviceRSSICallback
)
可选 获取蓝牙设备信号强度成功回调函数
回调函数参数event对象包括以下属性: RSSI - Number类型,蓝牙设备的信号强度。
- fail:
(
BluetoothFailCallback
)
可选 获取蓝牙设备信号强度失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 获取蓝牙设备信号强度操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 连接蓝牙设备获取信号强度
function createConnection(){
plus.bluetooth.createBLEConnection({
deviceId:deviceId,
success:function(e){
console.log('create connection success: '+JSON.stringify(e));
plus.bluetooth.getBLEDeviceRSSI({
deviceId:deviceId,
success:function(e){
console.log('RSSI: '+e.RSSI);
},
fail:function(e){
console.log('get RSSI failed: '+JSON.stringify(e));
}
});
},
fail:function(e){
console.log('create connection failed: '+JSON.stringify(e));
}
});
}
getBLEDeviceServices
获取蓝牙设备的所有服务(service)
void plus.bluetooth.getBLEDeviceServices(options);
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- success:
(
BluetoothSuccessCallback
)
可选 获取服务成功回调函数
回调函数参数event对象包括以下属性: services - Array>BluetoothService<类型,蓝牙设备服务的特征值列表。
- fail:
(
BluetoothFailCallback
)
可选 获取服务失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 获取服务操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 获取蓝牙设备的所有服务
function getServices(){
plus.bluetooth.getBLEDeviceServices({
deviceId:deviceId,
success:function(e){
var services = e.services;
console.log('get services success: '+services.length);
for(var i in services){
console.log(i+': '+JSON.stringify(services[i]));
}
},
fail:function(e){
console.log('get services failed: '+JSON.stringify(e));
}
});
}
notifyBLECharacteristicValueChange
启用低功耗蓝牙设备特征值变化时的notify功能,订阅特征值
void plus.bluetooth.notifyBLECharacteristicValueChange(options);
说明:
蓝牙设备服务的特征值必须支持notify或indicate才可以成功调用。 另外,必须先启用notifyBLECharacteristicValueChange才能监听到设备characteristicValueChange事件,即特征值发生变化时通过onBLECharacteristicValueChange注册的事件回调。
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- serviceId:
(
String
)
必选 蓝牙服务的uuid
- characteristicId:
(
String
)
必选 蓝牙特征值的uuid
- state:
(
Boolean
)
必选 是否启用 notify
- success:
(
BluetoothSuccessCallback
)
可选 订阅特征值成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 订阅特征值失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 订阅特征值操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id,可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id,可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 启用低功耗蓝牙设备特征值变化时的notify功能
function startCharacteristicsNotify(){
// 监听低功耗蓝牙设备的特征值变化
plus.bluetooth.onBLECharacteristicValueChange(function(e){
console.log('onBLECharacteristicValueChange: '+JSON.stringify(e));
var value = buffer2hex(e.value);
console.log('value(hex) = '+value);
if(characteristicId == e.characteristicId){
// 更新到页面显示
alert('特征值变化: '+value);
}
});
// 启用notify功能
plus.bluetooth.notifyBLECharacteristicValueChange({
deviceId:deviceId,
serviceId:serviceId,
characteristicId:characteristicId,
success:function(e){
var characteristics = e.characteristics;
console.log('get characteristics success: '+characteristics.length);
for(var i in characteristics){
console.log(i+': '+JSON.stringify(characteristics[i]));
}
},
fail:function(e){
console.log('get characteristics failed: '+JSON.stringify(e));
}
});
}
onBLECharacteristicValueChange
监听低功耗蓝牙设备的特征值变化事件
void plus.bluetooth.onBLECharacteristicValueChange(callback);
参数:
- callback:
(
BLECharacteristicValueChangeCallback
)
必选 特征值变化回调函数
回调函数参数event对象包括以下属性: deviceId - String类型,蓝牙设备id; serviceId - String类型,蓝牙服务的uuid; characteristicId - String类型,蓝牙特征值的uuid; value - ArrayBuffer类型,特征值的最新值。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id,可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id,可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 启用低功耗蓝牙设备特征值变化时的notify功能
function startCharacteristicsNotify(){
// 监听低功耗蓝牙设备的特征值变化
plus.bluetooth.onBLECharacteristicValueChange(function(e){
console.log('onBLECharacteristicValueChange: '+JSON.stringify(e));
var value = buffer2hex(e.value);
console.log('value(hex) = '+value);
if(characteristicId == e.characteristicId){
// 更新到页面显示
alert('特征值变化: '+value);
}
});
// 启用notify功能
plus.bluetooth.notifyBLECharacteristicValueChange({
deviceId:deviceId,
serviceId:serviceId,
characteristicId:characteristicId,
success:function(e){
var characteristics = e.characteristics;
console.log('get characteristics success: '+characteristics.length);
for(var i in characteristics){
console.log(i+': '+JSON.stringify(characteristics[i]));
}
},
fail:function(e){
console.log('get characteristics failed: '+JSON.stringify(e));
}
});
}
onBLEConnectionStateChange
监听低功耗蓝牙设备连接状态变化事件
void plus.bluetooth.onBLEConnectionStateChange(callback);
说明:
包括开发者主动连接或断开连接,设备丢失,连接异常断开等。
参数:
- callback:
(
BLEConnectionStateChangeCallback
)
必选 连接状态变化回调函数
回调函数参数event对象包括以下属性: deviceId - String类型,蓝牙设备id; connected - Boolean类型,是否处于已连接状态。
返回值:
void : 无示例:
// 监听蓝牙设备连接状态
function listenerConnection(){
plus.bluetooth.onBLEConnectionStateChange(function(e){
console.log('connection state changed: '+JSON.stringify(e));
});
}
readBLECharacteristicValue
读取低功耗蓝牙设备指定特征值的二进制数据值
void plus.bluetooth.readBLECharacteristicValue(options);
说明:
指定的特征值需支持read操作才可以成功调用。 并行调用多次可能导致读取失败,读取的数据需要在onBLECharacteristicValueChange方法注册的回调中获取。
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- serviceId:
(
String
)
必选 蓝牙服务的uuid
- characteristicId:
(
String
)
必选 蓝牙特征值的uuid
- success:
(
BluetoothSuccessCallback
)
可选 读取特征值的二进制数据成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 读取特征值的二进制数据失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 读取特征值的二进制数据操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id,可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id,可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 读取低功耗蓝牙设备的特征值
function readCharacteristics(){
plus.bluetooth.readBLECharacteristicValue({
deviceId:deviceId,
serviceId:serviceId,
characteristicId:characteristicId,
success:function(e){
console.log('read characteristics success: '+JSON.stringify(e));
},
fail:function(e){
console.log('read characteristics failed: '+JSON.stringify(e));
}
});
}
writeBLECharacteristicValue
向低功耗蓝牙设备指定特征值写入二进制数据
void plus.bluetooth.writeBLECharacteristicValue(options);
说明:
指定的特征值需支持write操作才可以成功调用。 并行调用多次可能导致读取失败,系统可能会限制单次传输的数据大小,超过最大字节数后可能会发生写入错误,建议每次写入不超过20字节。
参数:
options参数为json类型,包含以下属性:
- deviceId:
(
String
)
必选 蓝牙设备的id
- serviceId:
(
String
)
必选 蓝牙服务的uuid
- characteristicId:
(
String
)
必选 蓝牙特征值的uuid
- value:
(
ArrayBuffer
)
必选 要写入的数据
写入到蓝牙设备指定特征值中的二进制值。
- success:
(
BluetoothSuccessCallback
)
可选 读取特征值的二进制数据成功回调函数
- fail:
(
BluetoothFailCallback
)
可选 读取特征值的二进制数据失败回调函数
- complete:
(
BluetoothCompleteCallback
)
可选 读取特征值的二进制数据操作完成回调函数
调用成功或失败都会触发此回调。
返回值:
void : 无示例:
// 蓝牙设备id,可通过onBluetoothDeviceFound方法获取
var deviceId = '';
// 蓝牙服务id,可通过getBLEDeviceServices方法获取
var serviceId = '';
// 蓝牙特征值id,可通过getBLEDeviceCharacteristics方法获取
var characteristicId = '';
// 要写入的数据
var value = new ArrayBuffer(8);
var iv = new Int32Array(value);
iv[0] = 120, iv[2]=100;
// 写入低功耗蓝牙设备的特征值
function writeCharacteristics(){
plus.bluetooth.writeBLECharacteristicValue({
deviceId:deviceId,
serviceId:serviceId,
characteristicId:characteristicId,
value:value,
success:function(e){
console.log('write characteristics success: '+JSON.stringify(e));
},
fail:function(e){
console.log('write characteristics failed: '+JSON.stringify(e));
}
});
}
BluetoothDeviceInfo
蓝牙设备信息
interface BluetoothDeviceInfo {
readonly attribute String name;
readonly attribute String deviceId;
readonly attribute Number RSSI;
readonly attribute ArrayBuffer advertisData;
readonly attribute Array<String> advertisServiceUUIDs;
readonly attribute String localName;
readonly attribute JSON serviceData;
}
属性:
- name: (String
类型
)蓝牙设备名称
某些设备可能没有此字段值。
- deviceId: (String
类型
)蓝牙设备的id
- RSSI: (Number
类型
)蓝牙设备的信号强度
- advertisData: (ArrayBuffer
类型
)蓝牙设备的广播数据段中的ManufacturerData数据段
- advertisServiceUUIDs: (Array[String]
类型
)蓝牙设备的广播数据段中的ServiceUUIDs数据段
- localName: (String
类型
)蓝牙设备的广播数据段中的LocalName数据段
- serviceData: (JSON
类型
)蓝牙设备的广播数据段中的ServiceData数据段
BluetoothService
蓝牙设备服务信息
interface BluetoothService {
readonly attribute String uuid;
readonly attribute Boolean isPrimary;
}
属性:
- uuid: (String
类型
)蓝牙设备服务的uuid
- isPrimary: (Boolean
类型
)是否为设备的主服务
Bluetoothcharacteristic
蓝牙设备特征值
interface Bluetoothcharacteristic {
readonly attribute String uuid;
readonly attribute BluetoothcharacteristicProperties properties;
}
属性:
- uuid: (String
类型
)蓝牙设备特征值的uuid
- properties: (BluetoothcharacteristicProperties
类型
)设备特征值支持的操作类型
BluetoothcharacteristicProperties
蓝牙设备特征值支持的操作类型
interface BluetoothcharacteristicProperties {
readonly attribute Boolean read;
readonly attribute Boolean write;
readonly attribute Boolean notify;
readonly attribute Boolean indicate;
}
属性:
- read: (Boolean
类型
)特征值是否支持read操作
- write: (Boolean
类型
)特征值是否支持write操作
- notify: (Boolean
类型
)特征值是否支持notify操作
- indicate: (Boolean
类型
)特征值是否支持indicate操作
BluetoothSuccessCallback
成功回调函数
void onSuccess(Object event){
}
说明:
不同接口触发的成功回调参数event包含的属性存在差异,具体参考对应的接口描述说明。
参数:
- event:
(
Object
)
必选 回调参数
回调参数包含的属性由调用接口决定,具体参考对应的接口描述说明。
返回值:
void : 无BluetoothFailCallback
失败回调函数
function void onFail(Exception error){
// Handle error
var code = error.code; // 错误编码
var message = error.message; // 错误描述信息
}
参数:
- error:
(
Exception
)
必选 回调参数,错误信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。
返回值:
void : 无BluetoothCompleteCallback
操作完成回调函数
function void onComplete(Object event){
}
说明:
调用成功或失败都会触发此回调。
参数:
- event:
(
Object
)
可选 回调参数
调用成功时回调参数与BluetoothSuccessCallback一致,调用失败时回调参数与BluetoothFailCallback一致。
返回值:
void : 无BluetoothAdapterStateChangeCallback
蓝牙适配器状态变化事件回调函数
function void onStateChange(Object event){
// event.available
// event.discovering
}
说明:
蓝牙适配器状态发生变化时触发此回调。
参数:
- event:
(
Object
)
可选 返回参数
回调函数参数event对象包括以下属性: available - Boolean,蓝牙适配器是否可用; discovering - Boolean,蓝牙适配器是否处于搜索状态。
返回值:
void : 无BluetoothDeviceFoundCallback
蓝牙适配器搜索到新设备事件回调函数
function void onDeviceFound(Object event){
// event.devices
}
说明:
搜索到蓝牙设备时触发此回调。
参数:
- event:
(
Object
)
可选 返回参数
回调函数参数event对象包括以下属性: devices - Array<BluetoothDeviceInfo>,设备列表信息。
返回值:
void : 无BluetoothDeviceRSSICallback
获取蓝牙设备信号强度成功回调函数
function void onDeviceRSSI(Object event){
// event.RSSI
}
说明:
获取蓝牙设备信号强度时触发此回调。
参数:
- event:
(
Object
)
可选 返回参数
回调函数参数event对象包括以下属性: RSSI - Number,信号强度。
返回值:
void : 无BLEConnectionStateChangeCallback
低功耗蓝牙设备连接状态变化事件回调函数
function void onStateChange(Object event){
// event.deviceId
// event.connected
}
说明:
蓝牙设备连接状态发生变化时触发此回调。
参数:
- event:
(
Object
)
可选 返回参数
回调函数参数event对象包括以下属性: deviceId - String类型,蓝牙设备id; connected - Boolean类型,是否处于已连接状态。
返回值:
void : 无BLECharacteristicValueChangeCallback
低功耗蓝牙设备的特征值变化事件回调函数
function void onValueChange(Object event){
// event.deviceId
// event.serviceId
// event.characteristicId
// event.value
}
说明:
蓝牙设备对应的特征值发生变化时触发此回调。
参数:
- event:
(
Object
)
可选 返回参数
回调函数参数event对象包括以下属性: deviceId - String类型,蓝牙设备id; serviceId - String类型,蓝牙服务的uuid; characteristicId - String类型,蓝牙特征值的uuid; value - ArrayBuffer类型,特征值的最新值。