B2G/Bluetooth/WebBluetooth-v2/BluetoothDevice

Overview

BluetoothDevice provides information regarding a given remote bluetooth device.

Interfaces

BluetoothDevice

[CheckPermissions="bluetooth"]
interface BluetoothDevice: EventTarget
{
  readonly attribute DOMString address;
  readonly attribute BluetoothClassOfDevice cod;
  readonly attribute DOMString name;
  readonly attribute boolean paired;
  [Cached, Pure]
  readonly attribute sequence<DOMString> uuids;
  readonly attribute BluetoothDeviceType type;
  readonly attribute BluetoothGatt? gatt;

           attribute EventHandler onattributechanged;

  Promise<sequence<DOMString>> fetchUuids();
  Promise<BluetoothGatt> connectGatt(boolean aAutoConnect);
};

BluetoothDeviceAttribute

enum BluetoothDeviceAttribute
{
  "unknown",
  "cod",
  "name",
  "paired",
  "uuids"
}

BluetoothDeviceType

enum BluetoothDeviceType
{
  "unknown",
  "classic",
  "le",
  "dual",
}

Properties

address

Description: The address property provides the address of the device on the bluetooth micro-network.

Value type: DOMString

Default value: Empty string ("")

Sample

var address = device.address;

cod

Description: The cod property is a BluetoothClassOfDevice object that provides much information about the device's capabilities.

Value type: BluetoothClassOfDevice

Default value: A BluetoothClassOfDevice object whose attributes are default values.

Sample

var cod = device.cod;

var majorDeviceClass = cod.BluetoothMajorDeviceClass;
var majorServiceClass = cod.BluetoothMajorServiceClass;
var minorDeviceClass = cod.BluetoothMinorDeviceClass;

name

Description: The name property is the human readable name of the device.

Value type: DOMString

Default value: Empty string ("")

Sample

var name = device.name;

paired

Description: The paired property indicates whether this remote device is paired to current device's adapter (true) or not (false).

Value type: boolean

Default value: false

Sample

var paired = device.paired;

uuids

Description: [Cached, Pure]; The property stores the cached UUID list of each bluetooth service that the remote device provides. If applications require the up-to-date UUID list is required, call fetchUuids() to update this property. This property is marked with [Cached] because the same JS Array object is returned until a fetchUuids() call happens, and marked with [Pure] rather than [Constant] because uuids is updated once fetchUuids() executes.

Value type: sequence<DOMString>

Default value: An empty array (array with length = 0)

Sample

var uuids = device.uuids;

type

Description: The type property indicates the device type of the remote device.

Value type: BluetoothDeviceType

Default value: BluetoothDeviceType.unknown

Sample

var type = device.type;

gatt

Description: The gatt property is object used to conduct GATT client operations on this remote LE device. Applications have to call connectGatt() to update this property. This property must be null pointer for devices of type classic or unknown.

Value type: BluetoothGatt

Default value: Null pointer

Sample

var gatt = device.gatt;

Event Handlers

BluetoothDevice.onattributechanged

onattributechanged

Description: A handler to trigger when on of the remote device's properties has changed. Note access to the changed property in this event handler would get the updated value.

Paramter

aAttributeEvent

The event is a BluetoothAttributeEvent with property attrs that contains changed BluetoothDeviceAttributes.

Sample

device.onattributechanged = function onDeviceAttributeChanged(evt) {
  for (var i in evt.attrs) {
    switch (evt.attrs[i]) {
      case 'name':
        console.log("device name changed to", device.name);
        break;
      case 'paired':
        console.log("device paired changed to", device.paired);
        break;
      default:
        break;
    }
  }
}

Methods

fetchUuids()

Description: The method fetches the up-to-date UUID list of each bluetooth service that the device provides. If the fetchUuids operation succeeds, an onattributechanged would be triggered right before the Promise is resolved to indicate device.uuids has changed.

Return: A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns a DOMString array.

Sample

device.fetchUuids().then { function onResolve(uuids) {
  console.log("Resolved with uuids:");
  for (var i = 0; i < uuids.length; i++) {   
    console.log("uuid", i, "is", uuids[i]);
  }
}, function onReject(aReason) {
  console.log("Rejected with this reason: " + aReason);
});

connectGatt(boolean aAutoConnect)

Description: The method creates a BluetoothGatt object, assigns it to property gatt, and then connects to remote LE device.

Parameter

aAutoConnect

Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true).

Return: A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns a BluetoothGatt object whose connectionState is connected. The promise is rejected if creation of BluetoothGatt object or connection to remote LE device fails.

Sample

var autoConnect = false;

device.connectGatt(autoConnect).then { function onResolve(gatt) {
  // gatt.connectionState is connected.
  console.log("Resolved with gatt. Connection state:", gatt.connectionState);
}, function onReject(aReason) {
  console.log("Rejected with this reason: " + aReason);
});