下载文档

uexBluetoothLE
更新时间:2016-01-11

1、简介

蓝牙BLE插件

1.1、说明

蓝牙BLE插件。
iOS 后台蓝牙功能须知

  • iOS设备要在后台使用蓝牙功能,必须首先设置相应的后台蓝夜权限;
  • 如果要在后台进行音频操作,还需要设置后台音乐权限;
  • 在后台扫描蓝牙设备时,serviceUUIDs参数必传,不能无限制扫描;
  • 后台获取到数据如要通知前台,请用LocalNotification;

注:由于本插件的特殊性,暂时没法提供方法的示例,整体示例请参考开源源码中的示例

1.2、开源源码

插件测试用例与源码下载:点击 插件中心至插件详情页 (插件测试用例与插件源码已经提供)

2、API概览

2.1、方法

init 初始化接口

uexBluetoothLE.init()

说明:

回调方法cbInit

  • 所有的回调都会传给执行init()的页面,请务必不要关闭此页面;
  • 建议在root页面执行init();

参数:

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

scanDevice 扫描蓝牙设备

uexBluetoothLE.scanDevice(serviceUUIDs)

说明:

扫描到设备后通过onLeScan回调结果

参数:

参数名称 参数类型 是否必选 说明
serviceUUIDs Array 由service的UUID字符串组成的数组。 serviceUUIDs不传时,插件会扫描所有蓝牙设备;否则,插件会只扫描包含数组中的指定service的蓝牙设备;iOS系统,在进行后台蓝牙设备扫描时,该参数必须,若前台扫描则该参数为可选。

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

stopScanDevice 停止扫描设备

uexBluetoothLE.stopScanDevice()

说明:

停止扫描设备

参数:

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

connect 连接指定蓝牙设备

uexBluetoothLE.connect(param)

说明:

连接指定蓝牙设备。回调方法cbConnect

参数:

  1. var param={
  2. address://(必选)要连接的蓝牙地址
  3. };

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

disconnect 断开蓝牙连接

uexBluetoothLE.disconnect()

说明:

断开蓝牙连接。成功断开后会回调onConnectionStateChange方法

参数:

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

searchForCharacteristic 从指定service中搜索characteristic

uexBluetoothLE.searchForCharacteristic(param)

说明:

从指定service中搜索characteristic。回调方法cbSearchForCharacteristic

参数:

  1. var param={
  2. serviceUUID://(必选)string,要搜索的service的UUID
  3. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

searchForDescriptor 从指定characteristic中搜索descriptor

uexBluetoothLE.searchForDescriptor(param)

说明:

从指定characteristic中搜索descriptor。回调方法cbSearchForDescriptor

参数:

  1. var param={
  2. serviceUUID:,//(必选)被搜索的characteristic所在的service的UUID
  3. characteristicUUID://(必选)string 要搜索的characteristics的UUID
  4. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

readCharacteristic 读取Characteristic

uexBluetoothLE.readCharacteristic(param)

说明:

读取Characteristic。回调方法cbReadCharacteristic

参数:

  1. var param={
  2. serviceUUID://(必选)service的UUID
  3. characteristicUUID://(必选)characteristic的UUID
  4. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

writeCharacteristic 写入数据到Characteristic

uexBluetoothLE.writeCharacteristic(param)

说明:

写入数据到Characteristic。回调方法cbWriteCharacteristic。监听方法onCharacteristicChanged
用户需要将实际要写入的值先base64编码成String,再调用此方法.

参数:

  1. var param={
  2. serviceUUID:,//service的UUID
  3. characteristicUUID:,//characteristic的UUID
  4. value://要写入的值
  5. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

readDescriptor 读取Descriptor

uexBluetoothLE.readDescriptor(param)

说明:

读取Descriptor。回调方法cbReadDescriptor

参数:

  1. var param={
  2. serviceUUID://service的UUID
  3. characteristicUUID://characteristic的UUID
  4. descriptorUUID://descriptor的UUID
  5. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

writeDescriptor 写入数据到Descriptor

uexBluetoothLE.writeDescriptor(param)

说明:

写入数据到Descriptor。回调方法cbWriteDescriptor
用户需要将实际要写入的值先base64编码成String,再调用此方法.

参数:

  1. var param={
  2. serviceUUID://service的UUID
  3. characteristicUUID://characteristic的UUID
  4. descrtiptorUUID://descriptor的UUID
  5. value://要写入的值
  6. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

2.2、回调方法

cbInit 初始化的回调方法

uexBluetoothLE.cbInit(data)

参数:

  1. var data={
  2. resultCode://(必选) 0-BLE启动成功,1-BLE启动失败
  3. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbInit = cbInit;
  3. }
  4. function cbInit(data){
  5. alert("cbInit:" + data);
  6. }

cbConnect 连接指定蓝牙设备的回调方法

uexBluetoothLE.cbConnect(data)

参数:

  1. var data={
  2. services://(必选) service的UUID构成的数组
  3. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbConnect = cbConnect;
  3. }
  4. function cbConnect(data){
  5. alert("cbConnect:" + data);
  6. }

cbSearchForCharacteristic 从指定service中搜索characteristic的回调方法

uexBluetoothLE.cbSearchForCharacteristic(data)

参数:

  1. var data={
  2. serviceUUID:,//(必选)被搜索的service的UUID
  3. characteristics://(必选)list<uexBLECharacteristic> 此service下的uexBLECharacteristic结构构成的数组
  4. }

uexBLECharacteristic结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbSearchForCharacteristic = cbSearchForCharacteristic;
  3. }
  4. function cbSearchForCharacteristic(data){
  5. alert("cbSearchForCharacteristic:" + data);
  6. }

cbSearchForDescriptor 从指定characteristic中搜索descriptor的回调方法

uexBluetoothLE.cbSearchForDescriptor(data)

参数:

  1. var data={
  2. serviceUUID://被搜索的characteristic所在的service的UUID
  3. characteristicUUID:,//被搜索的characteristic的UUID
  4. descriptors:,//list<uexLBEDescriptor> 此characteristic下的uexBLEDescriptor结构构成的数组,
  5. }

uexBLEDescriptor结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbSearchForDescriptor = cbSearchForDescriptor;
  3. }
  4. function cbSearchForDescriptor(data){
  5. alert("cbSearchForDescriptor:" + data);
  6. }

cbReadCharacteristic 读取Characteristic的回调方法

uexBluetoothLE.cbReadCharacteristic(data)

参数:

  1. var data={
  2. resultCode://0-成功,1-失败
  3. data://uexBLECharacteristic的Json格式
  4. }

uexBLECharacteristic结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbReadCharacteristic = cbReadCharacteristic;
  3. }
  4. function cbReadCharacteristic(data){
  5. alert("cbReadCharacteristic:" + data);
  6. }

cbWriteCharacteristic 写入数据到Characteristic的回调方法

uexBluetoothLE.cbWriteCharacteristic(data)

参数:

  1. var data={
  2. resultCode://0-成功,1-失败
  3. data:uexBLECharacteristicJson格式
  4. }

uexBLECharacteristic结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbWriteCharacteristic = cbWriteCharacteristic;
  3. }
  4. function cbWriteCharacteristic(data){
  5. alert("cbWriteCharacteristic:" + data);
  6. }

cbReadDescriptor 读取Descriptor的回调方法

uexBluetoothLE.cbReadDescriptor(data)

参数:

  1. var data={
  2. resultCode://0-成功,1-失败
  3. data://uexBLEDescriptor的Json格式
  4. }

uexBLEDescriptor结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbReadDescriptor = cbReadDescriptor;
  3. }
  4. function cbReadDescriptor(data){
  5. alert("cbReadDescriptor:" + data);
  6. }

cbWriteDescriptor 写入数据到Descriptor的回调方法

uexBluetoothLE.cbWriteDescriptor(data)

参数:

  1. var data={
  2. resultCode://0-成功,1-失败
  3. data:uexBLEDescriptorJson格式
  4. }

uexBLEDescriptor结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.cbWriteDescriptor = cbWriteDescriptor;
  3. }
  4. function cbWriteDescriptor(data){
  5. alert("cbWriteDescriptor:" + data);
  6. }

2.3、监听方法

onLeScan 扫描到设备的回调方法

uexBluetoothLE.onLeScan(data)

参数:

  1. var data={
  2. address:,
  3. name:
  4. }

各字段含义如下:

参数名称 参数类型 是否必选 说明
address String Android的address参数传回的是设备的mac地址;iOS的address参数传回的是设备的UUID
name String 蓝牙设备名称

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.onLeScan = onLeScan;
  3. }
  4. function onLeScan(data){
  5. alert("onLeScan:" + data);
  6. }

onConnectionStateChange 连接状态改变的监听方法

uexBluetoothLE.onConnectionStateChange(data)

参数:

  1. var data={
  2. resultCode://(必选)0-已连接上,1-已断开
  3. }

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.onConnectionStateChange = onConnectionStateChange;
  3. }
  4. function onConnectionStateChange(data){
  5. alert("onConnectionStateChange:" + data);
  6. }

onCharacteristicChanged Characteristic内容改变的监听方法

uexBluetoothLE.onCharacteristicChanged(data)

参数:

参数名称 参数类型 是否必选 说明
data Json uexBLECharacteristic的Json格式数据,uexBLECharacteristic结构说明见附录

平台支持:

Android 4.3+
iOS 7.1+

版本支持:

Android 3.0.0+
iOS 3.0.0+

示例:

  1. window.uexOnload = function(type){
  2. uexBluetoothLE.onCharacteristicChanged = onCharacteristicChanged;
  3. }
  4. function onCharacteristicChanged(data){
  5. alert("onCharacteristicChanged:" + data);
  6. }

3、附录

3.1 uexBLEDescriptor结构说明

  1. var uexBLEDescriptor{
  2. serviceUUID:,//此descriptor所属的service的UUID
  3. characteristicUUID:,//此descriptor所属的characteristic的UUID
  4. UUID:,//string,此descriptor的UUID
  5. value:,//string,此descriptor的值
  6. needDecode://是否需要base64解码 true/false,为true时,用户需要将value进行base64解码
  7. }

permissions权限说明请参考permissions权限说明
``

3.2 uexBLECharacteristic结构说明

  1. var uexBLECharacteristic{
  2. serviceUUID:,//string,此Characteristic所属的service的UUID
  3. UUID:,//string,此Characteristic的UUID
  4. value:,//string,此Characteristic的值,base64编码,用户获取到value之后,需要先进行base64解码
  5. permissions:,//(仅iOS)Number,此Characteristic的权限说明
  6. writeType;,//(仅Android)Number,此Characteristic的写入方式
  7. descriptors://list<uexBLEDescriptor> uexBLEDescriptor结构的数组,描述了此Characteristic下所有的Descriptor
  8. }

permissions权限说明请参考permissions权限说明
writeType写入方式请参考writeType

3.3 permissions权限说明

3.3.1 iOS权限说明

flag desription
1 Permits broadcasts of the characteristic value using a characteristic configuration descriptor.
2 Permits reads of the characteristic value.
4 Permits writes of the characteristic value, without a response.
8 Permits writes of the characteristic value.
16 Permits notifications of the characteristic value, without a response.
32 Permits indications of the characteristic value.
64 Permits signed writes of the characteristic value
128 If set, additional characteristic properties are defined in the characteristic extended properties descriptor.
256 If set, only trusted devices can enable notifications of the characteristic value.
512 If set, only trusted devices can enable indications of the characteristic value.

3.4 writeType

  1. 待补充

4、更新历史

iOS

API版本:uexBluetoothLE-3.0.4

最近更新时间:2016-1-5

历史发布版本 更新内容
3.0.4 修复cbInit回调参数错误的bug
3.0.3 添加IDE支持
3.0.2 修复一个会导致Characteristic写入失败的bug
3.0.1 修改读写的字符串均为为Base64编码
3.0.0 低功耗蓝牙插件 for iOS

Android

API版本:uexBluetoothLE-3.0.3

最近更新时间:2016-1-7

历史发布版本 更新内容
3.0.3 修正回调数据不正确的问题
3.0.2 init时自动调用开启蓝牙
3.0.1 js接口数据传输用Base64编码
3.0.0 蓝牙BLE插件