接口聲明

{ "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)

獲取本機藍牙適配器狀態(tài)。

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)

監(jiān)聽藍牙適配器狀態(tài)變化事件

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)

停止搜尋附近的藍牙外圍設備。若已經找到需要的藍牙設備并不需要繼續(xù)搜索時，建議調用該接口停止藍牙搜索。

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)

獲取在藍牙模塊生效期間所有已發(fā)現的藍牙設備。包括已經和本機處于連接狀態(tài)的設備。

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)

監(jiān)聽尋找到新設備的事件

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 獲取處于已連接狀態(tài)的設備。

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() {
    // 執(zhí)行操作成功，讀取的值會在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 才能監(jiān)聽到設備 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)

監(jiān)聽低功耗藍牙設備的特征值變化。必須先啟用 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)

監(jiān)聽低功耗藍牙連接狀態(tài)的改變事件。包括開發(fā)者主動連接或斷開連接，設備丟失，連接異常斷開等等

data 返回值：

示例：

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

狀態(tài)碼

后臺運行限制

禁止使用。后臺運行詳細用法參見 后臺運行腳本。