蓝牙 1040+

接口声明

{ "name": "system.bluetooth" }

导入模块

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

接口定义

bluetooth.openAdapter(OBJECT)

初始化蓝牙模块

参数：

示例：

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 成对调用。

参数：

示例：

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 参数：

success 返回值：

示例：

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 返回值：

示例：

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

bluetooth.startDevicesDiscovery(OBJECT)

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

OBJECT 参数：

示例：

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

bluetooth.stopDevicesDiscovery(OBJECT)

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

OBJECT 参数：

示例：

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 参数：

success 返回值：

devices 返回值：

示例：

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 返回值：

示例：

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 参数：

success 返回值：

devices 返回值：

示例：

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 参数：

示例：

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 参数：

示例：

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 参数：

success 返回值：

services 返回值：

示例：

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 参数：

success 返回值：

characteristics 返回值：

properties 返回值：

示例：

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 参数：

示例：

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 参数：

示例：

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 参数：

示例：

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 返回值：

示例：

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 返回值：

示例：

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

状态码

后台运行限制

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