快应用 蓝牙

2020-08-07 16:22 更新

接口声明

{ "name": "system.bluetooth" }

导入模块

import bluetooth from '@system.bluetooth' 或 var bluetooth = require("@system.bluetooth")

接口定义

bluetooth.openAdapter(OBJECT)

初始化蓝牙模块

参数:

参数名类型必填说明
operateAdapterBoolean是否打开系统蓝牙开关。设置为 true,在系统蓝牙开关关闭的情况下会弹框提示是否打开。默认值 false。
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.openAdapter({
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.closeAdapter(OBJECT)

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

参数:

参数名类型必填说明
operateAdapterBoolean是否关闭系统蓝牙开关。设置为 true,调用时会关闭系统蓝牙开关。默认值 false。
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.closeAdapter({
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.getAdapterState(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调
success 返回值:
参数名类型描述
availableBoolean蓝牙适配器是否可用
discoveringBoolean是否正在搜索设备

示例:

bluetooth.getAdapterState({
  success: function(data) {
    console.log(
      `handling adapter state, available = ${data.available}, discovering = ${
        data.discovering
      }`
    )
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.onadapterstatechange = function(data)

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

data 返回值:

参数名类型描述
availableBoolean蓝牙适配器是否可用
discoveringBoolean蓝牙适配器是否处于搜索状态

示例:

bluetooth.onadapterstatechange = function(data) {
  console.log('adapterState changed, now is', data.available)
}

bluetooth.startDevicesDiscovery(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
servicesString[]要搜索的主 service 的 uuid 列表。某些蓝牙设备会广播自己的主 service 的 uuid。如果设置此参数,则只搜索广播包有对应 uuid 的主服务的蓝牙设备。建议主要通过该参数过滤掉周边不需要处理的其他蓝牙设备。
allowDuplicatesKeyBoolean默认值为 false。是否允许重复上报同一设备。如果允许重复上报,则 bluetooth.ondevicefound 方法会多次上报同一设备,但是 RSSI 值会有不同。
intervalNumber单位毫秒,默认值为 0。上报设备的间隔。0 表示找到新设备立即上报,其他数值根据传入的间隔上报。
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.startDevicesDiscovery({
  services: ['FEE7'],
  success: function() {
    console.log('success')
  }
})

bluetooth.stopDevicesDiscovery(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.stopDevicesDiscovery({
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.getDevices(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。
success 返回值:
参数名类型描述
devicesObject[]蓝牙模块生效期间已发现的蓝牙设备
devices 返回值:
参数名类型说明
nameString蓝牙设备名称,某些设备可能没有
deviceIdString用于区分设备的 id
RSSINumber当前蓝牙设备的信号强度
advertisDataArrayBuffer当前蓝牙设备的广播数据段中的 ManufacturerData 数据段
advertisServiceUUIDsString[]当前蓝牙设备的广播数据段中的 ServiceUUIDs 数据段
localNameString当前蓝牙设备的广播数据段中的 LocalName 数据段
serviceDataObject当前蓝牙设备的广播数据段中的 ServiceData 数据段,key 为 uuid 的 String 值,value 为对应的 ServiceData 的 ArrayBuffer

示例:

function ab2hex(buffer) {
  var hexArr = Array.prototype.map.call(new Uint8Array(buffer), function(bit) {
    return ('00' + bit.toString(16)).slice(-2)
  })
  return hexArr.join('')
}
bluetooth.getDevices({
  success: function(data) {
    console.log('get device list has founded')
    data.devices.forEach(device => {
      console.log(`handling devive:${JSON.stringify(device)}`)
      console.log(`handling advertisData = ${ab2hex(device.advertisData)}`)
      for (let key in device.serviceData) {
        console.log(
          `handling serviceData: uuid = ${key}, serviceData = ${ab2hex(
            device.serviceData[key]
          )}`
        )
      }
    })
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.ondevicefound = function(data)

监听寻找到新设备的事件

data 返回值:

参数名类型描述
devicesObject[]新搜索到的设备列表,devices 返回值见 getDevices

示例:

function ab2hex(buffer) {
  var hexArr = Array.prototype.map.call(new Uint8Array(buffer), function(bit) {
    return ('00' + bit.toString(16)).slice(-2)
  })
  return hexArr.join('')
}
bluetooth.ondevicefound = function(data) {
  console.log('new device list has founded')
  data.devices.forEach(device => {
    console.log(`handling find new devive:${JSON.stringify(device)}`)
    console.log(`handling advertisData = ${ab2hex(device.advertisData)}`)

    for (let key in device.serviceData) {
      console.log(
        `handling serviceData: uuid = ${key}, serviceData = ${ab2hex(
          device.serviceData[key]
        )}`
      )
    }
  })
}

bluetooth.getConnectedDevices(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。
servicesString[]蓝牙设备主 service 的 uuid 列表
success 返回值:
参数名类型描述
devicesObject[]uuid 对应的的已连接设备列表
devices 返回值:
参数名类型说明
nameString蓝牙设备名称,某些设备可能没有
deviceIdString用于区分设备的 id

示例:

bluetooth.getConnectedDevices({
  success: function(data) {
    console.log(data)
    if (data.devices[0]) {
      console.log(data.devices[0].name)
    }
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.createBLEConnection(OBJECT)

连接低功耗蓝牙设备。若快应用有搜索过某个蓝牙设备,并成功建立连接,可直接传入之前搜索获取的 deviceId 直接尝试连接该设备,无需进行搜索操作。

OBJECT 参数:

参数名类型必填说明
deviceIdString用于区分设备的 id
timeoutNumber超时时间,单位 ms,不填表示不会超时
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.createBLEConnection({
  deviceId: deviceId,
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.closeBLEConnection (OBJECT)

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

OBJECT 参数:

参数名类型必填说明
deviceIdString用于区分设备的 id
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.closeBLEConnection({
  deviceId: deviceId,
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.getBLEDeviceServices(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
deviceIdString蓝牙设备 id
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。
success 返回值:
参数名类型描述
servicesObject[]设备服务列表
services 返回值:
参数名类型说明
uuidString蓝牙设备服务的 uuid
isPrimaryBoolean该服务是否为主服务

示例:

bluetooth.getBLEDeviceServices({
  deviceId: deviceId,
  success: function(data) {
    data.services.forEach(service => {
      console.log(
        `handling device services: uuid = ${service.uuid}, isPrimary = ${
          service.isPrimary
        }`
      )
    })
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.getBLEDeviceCharacteristics(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。
deviceIdString蓝牙设备 id
serviceIdString蓝牙服务 uuid,需要使用 getBLEDeviceServices 获取
success 返回值:
参数名类型描述
characteristicsObject[]设备服务列表
characteristics 返回值:
参数名类型说明
uuidString蓝牙设备特征值的 uuid
propertiesObject该特征值支持的操作类型
properties 返回值:
参数名类型说明
readBoolean该特征值是否支持 read 操作
writeBoolean该特征值是否支持 write 操作
notifyBoolean该特征值是否支持 notify 操作
indicateBoolean该特征值是否支持 indicate 操作

示例:

bluetooth.getBLEDeviceCharacteristics({
  deviceId: deviceId,
  serviceId: serviceId,
  success: function(data) {
    data.characteristics.forEach(characteristic => {
      console.log(
        `handling device characteristic : uuid = ${
          characteristic.uuid
        }, can read = ${characteristic.properties.read}`
      )
    })
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.readBLECharacteristicValue(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
deviceIdString蓝牙设备 id
serviceIdString蓝牙特征值对应服务的 uuid
characteristicIdString蓝牙特征值的 uuid
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.readBLECharacteristicValue({
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId: deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId: serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId: characteristicId,
  success: function() {
    // 执行操作成功,读取的值会在onblecharacteristicvaluechange 接口中上报
    console.log('success')
  }
})

bluetooth.writeBLECharacteristicValue(OBJECT)

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

OBJECT 参数:

参数名类型必填说明
deviceIdString蓝牙设备 id
serviceIdString蓝牙特征值对应服务的 uuid
characteristicIdString蓝牙特征值的 uuid
valueArrayBuffer蓝牙设备特征值对应的二进制值
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.writeBLECharacteristicValue({
  // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound接口中获取
  deviceId: deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId: serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId: characteristicId,
  // 这里的value是ArrayBuffer类型
  value: buffer,
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.notifyBLECharacteristicValueChange(OBJECT)

启用低功耗蓝牙设备特征值变化时的 notify 功能,订阅特征值。注意:必须设备的特征值支持 notify 或者 indicate 才可以成功调用。另外,必须先启用 notifyBLECharacteristicValueChange 才能监听到设备 characteristicValueChange 事件

OBJECT 参数:

参数名类型必填说明
deviceIdString蓝牙设备 id
serviceIdString蓝牙特征值对应服务的 uuid
characteristicIdString蓝牙特征值的 uuid
stateBoolean是否启用 notify
successFunction成功回调。
failFunction失败回调。
completeFunction执行结束后的回调。

示例:

bluetooth.notifyBLECharacteristicValueChange({
  // 启用 notify 功能
  state: true,
  // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  deviceId: deviceId,
  // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  serviceId: serviceId,
  // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  characteristicId: characteristicId,
  success: function() {
    console.log('success')
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  },
  complete: function() {
    console.log('complete')
  }
})

bluetooth.onblecharacteristicvaluechange = function(data)

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

data 返回值:

参数名类型描述
deviceIdString蓝牙设备 id
serviceIdString蓝牙特征值对应服务的 uuid
characteristicIdString蓝牙特征值的 uuid
valueArrayBuffer特征值最新的值

示例:

function ab2hex(buffer) {
  var hexArr = Array.prototype.map.call(new Uint8Array(buffer), function(bit) {
    return ('00' + bit.toString(16)).slice(-2)
  })
  return hexArr.join('')
}
bluetooth.onblecharacteristicvaluechange = function(data) {
  console.log(
    `handling characteristic value change: deviceId = ${
      data.deviceId
    }, serviceId = ${data.serviceId}, characteristicId = ${
      data.characteristicId
    }, value = ${ab2hex(data.value)}`
  )
}

bluetooth.onbleconnectionstatechange = function(data)

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

data 返回值:

参数名类型描述
deviceIdString蓝牙设备 id
connectedBoolean是否处于已连接状态

示例:

bluetooth.onbleconnectionstatechange = function(data) {
  console.log(
    `handling device state change: deviceId = ${data.deviceId}, connected = ${
      data.connected
    }`
  )
}

状态码

错误码错误信息描述
0ok正常
10000not init未初始化蓝牙适配器
10001not available当前系统蓝牙未打开
10002no device没有找到指定设备
10003connection fail连接失败
10004no service没有找到指定服务
10005no characteristic没有找到指定特征值
10006no connection当前连接已断开
10007property not support当前特征值不支持此操作
10008system error其余所有系统上报的异常
10009system not support系统版本低于 4.3 不支持 BLE
10010 1060+location not turned on定位开关未打开

后台运行限制

禁止使用。后台运行详细用法参见 后台运行脚本


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号