ble

sysAuth settings initManager scan discovery getPeripheral getPeripheralRssi isScanning stopScan connect disconnect isConnected retrievePeripheral retrieveConnectedPeripheral discoverService discoverCharacteristics discoverDescriptorsForCharacteristic setNotify stopNotify readValueForCharacteristic readValueForDescriptor writeValueForCharacteristic writeValueForDescriptor connectPeripherals setSimpleNotify getAllSimpleNotifyData clearAllSimpleNotifyData clean openBluetooth

setBluetoothListener

removeBlueToothListener requestBlePermission setMtu

概述

背景

蓝牙的适用场景

  • 可用于第三方蓝牙设备交互，必须要支持蓝牙 4.0。
  • iOS上：硬件至少是 iphone4s，系统至少是 iOS6。
  • android上：系统版本至少是 android4.3。

蓝牙 4.0 以低功耗著称，一般也叫 BLE（BluetoothLowEnergy）。目前应用比较多的案例：运动手坏、嵌入式设备、智能家居

蓝牙通讯原理概述

在蓝牙通讯中有两个主要的部分,Central 和 Peripheral，有一点类似Client Server。Peripheral 作为周边设备是服务器。Central 作为中心设备是客户端。所有可用的蓝牙设备可以作为周边（Peripheral）也可以作为中央（Central），但不可以同时既是周边也是中央。

一般手机是客户端， 设备（比如手环）是服务器，因为是手机去连接手环这个服务器。周边（Peripheral）是生成或者保存了数据的设备，中央（Central）是使用这些数据的设备。你可以认为周边是一个广播数据的设备，他广播到外部世界说他这儿有数据，并且也说明了能提供的服务。另一边，中央开始扫描附近有没有服务，如果中央发现了想要的服务，然后中央就会请求连接周边，一旦连接建立成功，两个设备之间就开始交换传输数据了。

除了中央和周边，我们还要考虑他俩交换的数据结构。这些数据在服务中被结构化，每个服务由不同的特征（Characteristics）组成，特征是包含一个单一逻辑值的属性类型。

服务和特性

上文中提到了特征（Characteristics），这里简单说明下什么是特征。

特征是与外界交互的最小单位。蓝牙4.0设备通过服务（Service）、特征（Characteristics）和描述符（Descriptor）来形容自己，同一台设备可能包含一个或多个服务，每个服务下面又包含若干个特征，每个特征下面有包含若干个描述符（Descriptor）。比如某台蓝牙4.0设备，用特征A来描述设备信息、用特征B和描述符b来收发数据等。而每个服务、特征和描述符都是用 UUID 来区分和标识的。

注意：

若要支持后台使用蓝牙功能需配置 config.xml 文件 bluetooth-central、bluetooth-peripheral 字段。

Android 6.0以后需要定位权限，否则无法正常使用

模块接口

sysAuth

判断是否有访问蓝牙的权限

sysAuth(callback(ret, err))

##callback(ret, err)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status: true,    //布尔型；是否有访问该功能权限；true（有权限）||false （无权限）
    details: ''      //字符串类型；权限详情，取值范围如下：
                     //notDetermined： 用户从未选择过权限
                     //restricted：无法访问手机蓝牙，该状态用户无法改变
                     //denied：户拒绝该应用访问手机蓝牙，或是访问手机蓝牙服务总开关处于关闭状态
                     //authorized：用户允许该程序可以访问手机蓝牙
}

示例代码

var privacy = api.require('ble');
privacy.sysAuth(function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS 系统

可提供的1.0.0及更高版本

settings

调整系统设置页面

settings()

示例代码

var privacy = api.require('ble');
privacy.settings();

可用性

iOS 系统

可提供的1.2.6及更高版本

initManager

初始化蓝牙4.0管理器

initManager(cllback(ret))

params

single

  • 类型：布尔 true 为单例模式,false为非单例模式;默认为false;
  • 描述：（可选项）则扫描附近的所有支持蓝牙4.0的设备

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
    state: 'poweredOn'       //字符串类型；蓝牙4.0设备连接状态，取值范围如下：
                             //poweredOn：设备开启状态 -- 可用状态
                             //poweredOff：设备关闭状态
                             //resetting：正在重置状态
                             //unauthorized：设备未授权状态
                             //unknown：初始的时候是未知的
                             //unsupported：设备不支持的状态
}

示例代码

var ble = api.require('ble');
ble.initManager(function(ret) {
    if (ret.state == "poweredOn") {
        api.alert({ msg: "初始化成功" });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scan

开始搜索蓝牙4.0设备，模块内部会不断的扫描更新附近的蓝牙4.0设备信息，可通过 getPeripheral 接口来获取扫描到的设备信息。若要停止扫描则调用 stopScan 接口

scan({params}, callback(ret, err))

params

serviceUUIDs

  • 类型：数组
  • 描述：（可选项）要扫描的蓝牙4.0设备的服务（service）的 UUID（字符串） 组成的数组，若不传则扫描附近的所有支持蓝牙4.0的设备

clean

  • 类型：布尔
  • 描述：（可选项）扫描前是否清空已搜索到的记录在本地的外围设备信息
  • 默认：true

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status: true   //布尔类型；是否获取成功，true|false
}

示例代码

var ble = api.require('ble');
ble.scan({
    serviceUUIDs: ['', '']
}, function(ret) {
    if (ret.status) {
        alert('开始扫描');
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

discovery

经典蓝牙扫描方式，可通过 getPeripheral 接口来获取扫描到的设备信息，扫描结束后会自动停止。注意仅单例模式下才能正常调用此方法

discovery(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status: true   //布尔类型；开启扫描是否成功，true|false
}

示例代码

var ble = api.require('ble');
ble.discovery(function(ret) {
    if (ret.status) {
        alert('开始扫描');
    }
});

可用性

Android系统

可提供的1.2.2及更高版本

getPeripheral

获取当前扫描到的所有外围设备信息

getPeripheral(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 描述：每发现新设备便会回调当前发现的所有蓝牙4.0设备信息
  • 注意：在 iOS 端，有两个 Name，一个是GAP name,另一个是 advertising name，设备没有连接外设时，获取的perpheral.name会是advertising name，然后当设备第一次连接成功外设后，GAP name就会被缓存下来，以后在连接时，获取的也都是GAP Name, 这样就造成了修改名称后苹果设备不更新的问题
  • 内部字段：
{
    peripherals:[{          //数组类型；获取到的当前扫描到的蓝牙4.0设备
      manufacturerData:'',  //字符串类型；蓝牙广播的数据；自定义数据，需硬件工程师设置，iOS上key值:CBAdvDataManufacturerData
      uuid: '',             //字符串类型；扫描到的蓝牙设备的 UUID
      name: '',             //字符串类型；扫描到的蓝牙设备的名字
      advertisingName: '',  //字符串类型；蓝牙的广告名，仅支持iOS平台
      serviceData: '',      //字符串类型；蓝牙设备广播的service data数据
      rssi:                 //数字类型；扫描到的蓝牙设备的信号强度，在 iOS 平台上可通过 getPeripheralRssi 接口获取
    },...]
}

示例代码

var ble = api.require('ble');
ble.getPeripheral(function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getPeripheralRssi

获取当前扫描到的所有外围设备的 rssi

注意：

  • 本接口仅支持iOS平台，且仅在 iOS8（含）以上系统上使用。iOS7以下系统可在 Peripheral 的返回信息里获得。
  • 通过本接口获取 rssi 必须先建立连接，苹果的官方文档说明如下：
While connected, retrieves the current RSSI of the link.

getPeripheralRssi({params},callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：要获取rssi值的外围设备的 UUID

callback(ret, err)

ret：

  • 类型：JSON 对象
  • 描述：获取的rssi信息
  • 内部字段：
{
     status: true,       //布尔类型；是否成功获取rssi，true|false
     rssi:''             //数字类型；rssi 值
}

err：

  • 类型：JSON 对象
  • 描述：获取rssi失败错误码
  • 内部字段：
{
     code:1       //数字类型；错误码，取值范围如下：
                  //1：peripheralUUID不正确
                  //2： peripheral 不存在
                  //3：未知错误
}

示例代码

var ble = api.require('ble');
ble.getPeripheralRssi(function(ret) {
    if (ret.status) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

isScanning

判断是否正在扫描

isScanning(callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status: true   //布尔类型；是否在扫描，true|false
}

示例代码

var ble = api.require('ble');
ble.isScanning(function(ret) {
    if (ret) {
        alert('正在扫描');
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopScan

停止搜索附近的蓝牙设备

stopScan()

示例代码

var ble = api.require('ble');
ble.stopScan();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

connect

连接指定外围设备。iOS端无超时判断，android端默认有30秒超时判断

connect({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：要连接的外围设备的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true      //布尔类型；是否连接成功，true|false
     peripheralUUID:'' //字符串类型；uuid，当 err内code 未1时，本参数无值
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：uuid为空
                      //2：未搜索到该蓝牙设备
                      //3：该设备为已连接状态
}

示例代码

var ble = api.require('ble');
ble.connect({
    peripheralUUID: ''
}, function(ret, err) {
    if (ret.status) {
        alert("连接成功！");
    } else {
        alert(err.code);
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

disconnect

断开与指定外围设备的连接

disconnect({params}, callback(ret))

params

peripheralUUID：

  • 类型：字符串
  • 描述：要断开连接的外围设备的 UUID

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true,       //布尔类型；是否成功断开连接，true|false
     peripheralUUID:''   //字符串类型；断开外围设备的 UUID
}

示例代码

var ble = api.require('ble');
ble.disconnect({
    peripheralUUID: ''
}, function(ret, err) {
    if (ret.status) {
        alert("断开连接成功！");
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

isConnected

判断与指定外围设备是否为连接状态

isConnected({params}, callback(ret))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定外围设备的 UUID

##callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
{
    status: true,       //布尔类型；是否连接，true|false
    peripheralUUID:''   //字符串类型；外围设备的 UUID
}

示例代码

var ble = api.require('ble');
ble.isConnected({
    peripheralUUID: ''
}, function(ret) {
    if (ret) {
        alert('已连接');
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

retrievePeripheral

根据 UUID 找到所有匹配的蓝牙外围设备信息Android 平台暂不支持本接口

retrievePeripheral({params}, callback(ret))

params

peripheralUUIDs：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID 组成的数组

callback(ret)

ret：

  • 类型：JSON 对象
  • 描述：若没有则返回空
  • 内部字段：
{
    peripherals:[{ //数组类型；获取到的蓝牙外围设备信息
      uuid: '',    //字符串类型；获取到的蓝牙设备的uuid
      name: '',    //字符串类型；获取到的蓝牙设备的名字
      rssi:  ,     //数字类型；获取到的蓝牙设备的信号强度，在 iOS 平台上已 deprecated，可通过 getPeripheralRssi 接口获取
      services:[]  //数组类型；获取到的蓝牙设备的所有服务 UUID 的集合
    },...]
}

示例代码

var ble = api.require('ble');
ble.retrievePeripheral({
    peripheralUUIDs: ['', '']
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

retrieveConnectedPeripheral

根据指定的服务，找到当前系统处于连接状态的蓝牙中包含这个服务的所有蓝牙外围设备信息Andaroid 平台暂不支持本接口

retrieveConnectedPeripheral({params}, callback(ret))

params

serviceUUIDs

  • 类型：数组
  • 描述：指定的蓝牙4.0设备的服务（service）的 UUID（字符串） 组成的数组

callback(ret)

ret：

  • 类型：JSON 对象
  • 描述：若没有则返回空
  • 内部字段：
{
    peripherals:[{ //数组类型；获取到的当前处于连接状态的蓝牙外围设备
      uuid: '',    //字符串类型；处于连接状态的蓝牙设备的uuid
      name: '',    //字符串类型；处于连接状态的蓝牙设备的名字
      rssi:   ,    //数字类型；处于连接状态的蓝牙设备的信号强度，在 iOS 平台上已 deprecated，可通过 getPeripheralRssi 接口获取
      services:[]  //数组类型；处于连接状态的蓝牙设备的所有服务 UUID 的集合
    },...]
}

示例代码

var ble = api.require('ble');
ble.retrieveConnectedPeripheral({
    serviceUUIDs: ['dsfs', 'sdf']
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

discoverService

根据指定的外围设备 UUID 获取该外围设备的所有服务

discoverService({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true ,   //布尔类型；是否获取成功，true|false
     services:[]      //数组类型；获取的所有服务号集合
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.discoverService({
    peripheralUUID: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

discoverCharacteristics

根据指定的外围设备 UUID 及其服务 UUID 获取该外围设备的所有特征（Characteristic）

discoverCharacteristics({params}, callback(ret, err))

params

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true ,      //布尔类型；是否获取成功，true|false
     characteristics:[{  //数组类型；获取的所有特征信息的集合
        uuid: '',        //字符串类型；特征的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        permissions: '', //字符串类型；特征的权限，取值范围如下：
                         //readable：
                         //writeable：
                         //readEncryptionRequired：
                         //writeEncryptionRequired：
        properties: ''    //字符串类型；特征的属性，取值范围如下：
                         //broadcast：
                         //read：
                         //writeWithoutResponse：
                         //write：
                         //notify：
                         //indicate：
                         //authenticatedSignedWrites：
                         //extendedProperties：
                         //notifyEncryptionRequired：
                         //indicateEncryptionRequired：
     }]   
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：未找到指定服务（service）
                      //4：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.discoverCharacteristics({
    
    serviceUUID:'',
    peripheralUUID: ''
    
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

discoverDescriptorsForCharacteristic

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 获取该外围设备的所有描述符（Descriptor）

discoverDescriptorsForCharacteristic({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true ,      //布尔类型；是否读取成功，true|false
     descriptors:[{      //数组类型；获取的所有描述符信息的集合
        uuid: '',        //字符串类型；描述符的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        characteristicUUID:'',//字符串类型；特征的 UUID 
        decode: ,        //布尔类型；描述符的值是否是二进制类型数据
        value:           //字符串类型；描述符的值，若 decode 为 true，则该值为转码后的值
     }]      
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：未找到指定特征（characteristic）
                      //5：未找到指定服务（service）
                      //6：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.discoverDescriptorsForCharacteristic({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setNotify

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 监听数据回发。注意：要在discoverCharacteristics接口回调后调用否则找不到特征

setNotify({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 描述：每有数据接收便会触发此回调
  • 内部字段：
{
     status: true ,      //布尔类型；是否获取数据，true|false
     characteristic:{    //JSON对象；获取监听的特征的信息
        uuid: '',        //字符串类型；特征的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        value:  ,        //字符串类型；特征的值
        permissions: '', //字符串类型；特征的权限，取值范围如下：
                         //readable：
                         //writeable：
                         //readEncryptionRequired：
                         //writeEncryptionRequired：
        propertie: ''    //字符串类型；特征的属性，取值范围如下：
                         //broadcast：
                         //read：
                         //writeWithoutResponse：
                         //write：
                         //notify：
                         //indicate：
                         //authenticatedSignedWrites：
                         //extendedProperties：
                         //notifyEncryptionRequired：
                         //indicateEncryptionRequired：
     }      
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：未找到指定特征（characteristic）
                      //5：未找到指定服务（service）
                      //6：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.setNotify({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

stopNotify

停止监听数据。调用setNotify接口后开始监听数据，不需要继续监听时调用disconnect断开链接，在iOS 平台上还需要调用此接口来停止监听。

stopNotify()

示例代码

var ble = api.require('ble');
ble.stopNotify();

可用性

iOS系统

可提供的1.0.4及更高版本

readValueForCharacteristic

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 读取数据

readValueForCharacteristic({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 描述：每有数据接收便会触发此回调
  • 内部字段：
{
     status: true ,      //布尔类型；是否读取成功，true|false
     characteristic:{    //JSON对象；获取监听的特征的信息
        uuid: '',        //字符串类型；特征的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        value:  ,        //字符串类型；特征的值
        permissions: '', //字符串类型；特征的权限，取值范围如下：
                         //readable：
                         //writeable：
                         //readEncryptionRequired：
                         //writeEncryptionRequired：
        propertie: ''    //字符串类型；特征的属性，取值范围如下：
                         //broadcast：
                         //read：
                         //writeWithoutResponse：
                         //write：
                         //notify：
                         //indicate：
                         //authenticatedSignedWrites：
                         //extendedProperties：
                         //notifyEncryptionRequired：
                         //indicateEncryptionRequired：
     }      
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：未找到指定特征（characteristic）
                      //5：未找到指定服务（service）
                      //6：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.readValueForCharacteristic({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

readValueForDescriptor

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 及其描述符获取数据

readValueForDescriptor({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

descriptorUUID

  • 类型：字符串
  • 描述：指定的描述符的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true ,      //布尔类型；是否读取成功，true|false
     descriptor:{        //JSON对象；获取的所有描述符信息
        uuid: '',        //字符串类型；描述符的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        characteristicUUID:'',//字符串类型；特征的 UUID 
        decode: ,        //布尔类型；描述符的值是否是二进制类型数据
        value:           //字符串类型；描述符的值，若 decode 为 true，则该值为转码后的值
     }      
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：descriptorUUID 为空
                      //5：未找到指定描述符（descriptor）
                      //6：未找到指定特征（characteristic）
                      //7：未找到指定服务（service）
                      //8：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.readValueForDescriptor({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: '',
    descriptorUUID: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

writeValueForCharacteristic

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 写数据

writeValueForCharacteristic({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

value

  • 类型：字符串
  • 描述：要写入的数据 ，十六进制的字符串

writeType

  • 类型：字符串
  • 描述：（可选项）写入数据时的类型
  • 默认：auto
  • 取值范围：
    • auto：模块自动选择类型
    • response：有回调
    • withoutResponse：无回调
    • signed: 签名 (signed只支持Android)

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 描述：每有数据接收便会触发此回调
  • 内部字段：
{
     status: true ,      //布尔类型；是否发送成功，true|false
     characteristic:{    //JSON对象；获取监听的特征的信息
        uuid: '',        //字符串类型；特征的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        permissions: '', //字符串类型；特征的权限，取值范围如下：
                         //readable：
                         //writeable：
                         //readEncryptionRequired：
                         //writeEncryptionRequired：
        propertie: ''    //字符串类型；特征的属性，取值范围如下：
                         //broadcast：
                         //read：
                         //writeWithoutResponse：
                         //write：
                         //notify：
                         //indicate：
                         //authenticatedSignedWrites：
                         //extendedProperties：
                         //notifyEncryptionRequired：
                         //indicateEncryptionRequired：
     }      
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：value 为空
                      //5：未找到指定特征（characteristic）
                      //6：未找到指定服务（service）
                      //7：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.writeValueForCharacteristic({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: '',
    value: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

writeValueForDescriptor

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 及其描述符发送数据

writeValueForDescriptor({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

descriptorUUID

  • 类型：字符串
  • 描述：指定的描述符的 UUID

value

  • 类型：字符串
  • 描述：要发送的数据，十六进制的字符串

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true ,      //布尔类型；是否发送成功，true|false
     characteristic:{    //JSON对象；获取监听的特征的信息
        uuid: '',        //字符串类型；特征的 UUID 
        serviceUUID: '', //字符串类型；服务的 UUID 
        permissions: '', //字符串类型；特征的权限，取值范围如下：
                         //readable：
                         //writeable：
                         //readEncryptionRequired：
                         //writeEncryptionRequired：
        propertie: '' ,  //字符串类型；特征的属性，取值范围如下：
                         //broadcast：
                         //read：
                         //writeWithoutResponse：
                         //write：
                         //notify：
                         //indicate：
                         //authenticatedSignedWrites：
                         //extendedProperties：
                         //notifyEncryptionRequired：
                         //indicateEncryptionRequired：
        descriptors:[{        //数组类型；获取的所有描述符信息的集合
            uuid: '',         //字符串类型；描述符的 UUID 
            serviceUUID: '',  //字符串类型；服务的 UUID 
            characteristicUUID:'',//字符串类型；特征的 UUID 
            decode: ,         //布尔类型；描述符的值是否是二进制类型数据
            value:            //字符串类型；描述符的值，若 decode 为 true，则该值为转码后的值
        }] 
     }       
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；失败时返回错误码，取值范围如下：
                      //-1：未知错误
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：descriptorUUID 为空
                      //5：value 为空
                      //6：未找到指定描述符（descriptor）
                      //7：未找到指定特征（characteristic）
                      //8：未找到指定服务（service）
                      //9：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.writeValueForDescriptor({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: '',
    descriptorUUID: ''
}, function(ret) {
    if (ret) {
        api.alert({ msg: JSON.stringify(ret) });
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

connectPeripherals

连接多台外围设备

connectPeripherals({params}, callback(ret))

params

peripheralUUIDs：

  • 类型：数组
  • 描述：要连接的外围设备的 UUID 字符串组成的数组

callback(ret)

ret:

  • 类型：JSON 对象
  • 描述：peripheralUUIDs 传入多少个 id 则本回调执行多少次
  • 内部字段：
{
     status: true      //布尔类型；是否连接成功，true|false
     peripheralUUID:'' //字符串类型；所要链接的外围设备的 id
}

示例代码

var ble = api.require('ble');
ble.connectPeripherals({
    peripheralUUIDs: ['', '', '']
}, function(ret, err) {
    if (ret.status) {
        alert(ret.peripheralUUID + "连接成功！");
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

setSimpleNotify

根据指定的外围设备 UUID 及其服务 UUID 和特征 UUID 监听数据

注意：本接口同setNotify接口的区别是，本接口只是告诉模块要开始监听指定的蓝牙设备。不在回调函数里返回数据。监听到的数据需要用getAllSimpleNotifyData接口获取。

setSimpleNotify({params}, callback(ret, err))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

serviceUUID

  • 类型：字符串
  • 描述：指定的服务的 UUID

characteristicUUID

  • 类型：字符串
  • 描述：指定的特征的 UUID

callback(ret, err)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true        //布尔类型；是否获取数据，true|false  
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
     code: 1          //数字类型；连接失败时返回错误码，取值范围如下：
                      //1：peripheralUUID 为空
                      //2：serviceUUID 为空
                      //3：characteristicUUID 为空
                      //4：未找到指定特征（characteristic）
                      //5：未找到指定服务（service）
                      //6：尚未搜索到该蓝牙设备
}

示例代码

var ble = api.require('ble');
ble.setSimpleNotify({
    peripheralUUID: '',
    serviceUUID: '',
    characteristicUUID: ''
}, function(ret, err) {
    if (!ret.status) {
        api.alert({ msg: JSON.stringify(err) });
    }
});

可用性

iOS系统，Android系统

# **getAllSimpleNotifyData**

获取模块当前缓存的所监听蓝牙设备的所有数据

getAllSimpleNotifyData(callback(ret))

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     '':                  //模块当前缓存到的外围设备的 UUID，以此为 key 读取取相应的数据信息
     {                    //JSON对象；模块当前缓存到的外围设备发来的数据信息 
        serviceUUID: '',  //字符串类型；服务的 UUID 
        characterUUID: '',//字符串类型；特征的 UUID 
        data:['','','']   //数组类型；特征的值组成的数组，内部元素值为字符串类型
     }       
}

示例代码

var ble = api.require('ble');
ble.getAllSimpleNotifyData(function(ret) {
    api.alert({ msg: JSON.stringify(ret) });
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clearAllSimpleNotifyData

清空模块当前缓存的所监听蓝牙设备的所有数据

clearAllSimpleNotifyData()

示例代码

var ble = api.require('ble');
ble.clearAllSimpleNotifyData();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

clean

清空已搜索到的记录在本地的外围设备信息。建议在没有连接的情况下调用，否则与外围设备相关的一系列接口均会失效

clean()

示例代码

var ble = api.require('ble');
ble.clean();

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openBluetooth

打开蓝牙

openBluetooth()

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
    status:,             //布尔类型；蓝牙是否打开     
}

err:

  • 类型：JSON 对象
  • 内部字段：
{
   msg:'',      //字符串类型  ；错误信息
}

示例代码

var ble = api.require('ble');
ble.openBluetooth(function(ret) {
alert(JSON.stringify(ret));
});

可用性

Android系统

可提供的1.0.0及更高版本

setBluetoothListener

设置蓝牙状态监听

setBluetoothListener(cllback(ret))

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
    state: 'poweredOn'       //字符串类型；蓝牙4.0设备连接状态，取值范围如下：
                             //poweredOn：蓝牙开启状态 
                             //poweredOff：设备关闭状态
                             //turningOn：正在开启
                           //turningOff: 正在关闭
                             
}

示例代码

var ble = api.require('ble');
ble.setBluetoothListener(function(ret) {
});

可用性

Android系统

可提供的1.1.9及更高版本

removeBlueToothListener

取消蓝牙状态监听

removeBlueToothListener(cllback(ret))

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
    status: true       //布尔类型；是否成功
                             
}

示例代码

var ble = api.require('ble');
ble.setBluetoothListener(function(ret) {
});

可用性

Android系统

可提供的1.1.9及更高版本

requestBlePermission

targetsdk为31时用于申请Android12设备上所需要的蓝牙权限

requestBlePermission()

示例代码

var ble = api.require('ble');
ble.requestBlePermission();

可用性

Android系统

可提供的1.2.4及更高版本

setMtu

当发现指定的蓝牙服务后，通过设置mtu提高对方发送数据的容量。注意由于Android系统不同厂商定制化差异以及手机ble版本不同，mtu可设置的最大值不统一;mtu设置成功之后，需要等待几秒钟等待设备更新设置之后再进行其他操作。

setMtu({params}, callback(ret))

params

peripheralUUID：

  • 类型：字符串
  • 描述：指定的蓝牙外围设备的 UUID

mtu：

  • 类型：数字
  • 描述：指定要修改的mtu的值，默认为20

callback(ret)

ret:

  • 类型：JSON 对象
  • 内部字段：
{
     status: true ,   //布尔类型；是否成功，true|false
     code: 1,         //数字类型；
                      //0：设置成功
                      //-1：设置失败
                      //-2：未发现指定peripheralUUID的服务
     mtu:             //当前的mtu值    
}

示例代码

var ble = api.require('ble');
ble.setMtu({
    peripheralUUID: '',
    mtu:20
},function(ret){
    alert(JSON.stringify(ret));
});

可用性

Android系统

可提供的1.2.5及更高版本

是否仍需要帮助？ 请保持联络！
最后更新于 2024/12/2