B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt

Overview

BluetoothGatt provides bluetooth Generic Attribute Profile (GATT) client functionality to enable communication with a remote LE device. Applications have to call device.connectGatt() to create a BluetoothGatt for a remote LE device.

Interface

• BluetoothGatt
• BluetoothConnectionState

BluetoothGatt

[CheckPermissions="bluetooth"]
interface BluetoothGatt : EventTarget
{
  [Cached, Pure]
  readonly attribute sequence<BluetoothGattService> services;
  readonly attribute BluetoothConnectionState connectionState;

                attribute EventHandler onservicechanged;
                attribute EventHandler oncharacteristicchanged;
                attribute EventHandler onconnectionstatechanged;

  [NewObject, Throws] Promise<> connect();
  [NewObject, Throws] Promise<> disconnect();
  [NewObject, Throws] Promise<short> readRemoteRssi();
  BluetoothGattService findService(DOMString serviceUuid);
  // Reliable write
  [NewObject, Throws] Promise<> beginReliableWrite();
  [NewObject, Throws] Promise<> executeReliableWrite();
  [NewObject, Throws] Promise<> abortReliableWrite();
};

BluetoothConnectionState

enum BluetoothConnectionState {
  "connected",
  "connecting",
  "disconnected",
  "disconnecting"
};

Properties

• BluetoothGatt.services
• BluetoothGatt.connectionState

services

Description

The list of GATT services offered by the remote LE device.

Value type

sequence<BluetoothGattService>

Default Value

An empty array (array with length = 0)

connectionState

Description

The current connection state of GATT client to the remote LE device.

Value type

BluetoothConnectionState

Default Value

BluetoothConnectionState.disconnected

Event Handlers

• BluetoothGatt.onservicechanged
• BluetoothGatt.oncharacteristicchanged
• BluetoothGatt.onconnectionstatechanged

onservicechanged

Description

A handler to trigger when GATT services on the remote LE device have been added, removed, or modified. Access to property services in this event handler would get the updated list. See BT4.1 3.G.2.5.2 and 3.G.7.1 for detailed information.

Sample

var gatt = device.gatt;
if (gatt) {
  gatt.onservicechanged = function onServiceChanged() {
    console.log("Services on remote LE device have been added, removed, or modified. Check the services list to ensure services in use still exist.");
  };
}

oncharacteristicchanged

Description

A handler to trigger as a result of a remote characteristic notification.

Parameter

characteristicEvent

The event is a BluetoothGattCharacteristicEvent with property characteristic as the changed characteristic.

Sample

var gatt = device.gatt;
if (gatt) {
  gatt.oncharacteristicchanged = function onCharacteristicChanged(evt) {
    var characteristic = evt.characteristic;
    console.log("The value of characteristic (uuid:", characteristic.uuid, ") changed to", characteristic.value);
  };
}

onconnectionstatechanged

Description

A handler to trigger when current connection state of GATT client to the remote LE device (i.e., property connectionState) has changed.

Sample

var gatt = device.gatt;
if (gatt) {
  gatt.onconnectionstatechanged = function onConnectionStateChanged() {
    console.log("Connection state changed to", gatt.connectionState);
  };
}

Methods

• BluetoothGatt.connect()
• BluetoothGatt.disconnect()
• BluetoothGatt.readRemoteRssi()
• BluetoothGatt.beginReliableWrite()
• BluetoothGatt.executeReliableWrite()
• BluetoothGatt.abortReliableWrite()
• BluetoothGatt.findService(DOMString serviceUuid)

connect()

Description

The method is used to re-connect to the remote LE device after the connection has been dropped.

This is an asynchronous method and its result is returned via a Promise. Once the method is called, property connectionState becomes connecting and a corresponding onconnectionstatechanged would be triggered. If the connect operation succeeds, another onconnectionstatechanged would be triggered before the Promise is resolved to indicate property connectionState becomes connected.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise would be rejected if 1) property connectionState is not disconnected when the method is called, or 2) the remote LE device is not in range. The re-connection will be triggered once the device is back in range and, if re-connection succeeds, an onconnectionstatechanged would be fired to indicate property connectionState becomes connected.

Sample

var gatt = device.gatt;
if (gatt) {
  gatt.onconnectionstatechanged = function onConnectionStateChanged() {
    console.log("Connection state changed to", gatt.connectionState);

    if (gatt.connectionState === "disconnected") {
      console.log("Re-connect to remote LE device.");

      gatt.connect().then { function onResolve() {
        console.log("Re-connection succeeds. ConnectionState becomes:", gatt.connectionState);
      }, function onReject(aReason) {
        console.log("Rejected with this reason: ", aReason, ". ConnectionState becomes:", gatt.connectionState);
      });
    }
  };
}

disconnect()

Description

The method disconnects an established connection.

This is an asynchronous method and its result is returned via a Promise. Once the method is called, property connectionState becomes disconnecting and a corresponding onconnectionstatechanged would be triggered. If the connect operation succeeds, another onconnectionstatechanged would be triggered before the Promise is resolved to indicate property connectionState becomes disconnected.

Return

A Promise to indicate whether the operation is resolved or rejected. If the property connectionState is not connected when the method is called, the Promise would be rejected.

Sample

var gatt = device.gatt;
if (gatt && gatt.connectionState === "connected") {
  gatt.disconnect().then { function onResolve() {
    console.log("Disconnection succeeds. ConnectionState becomes:", gatt.connectionState);
  }, function onReject(aReason) {
    console.log("Rejected with this reason: ", aReason, ". ConnectionState becomes:", gatt.connectionState);
  };
}

readRemoteRssi()

Description

The method reads the RSSI for a connected remote LE device.

Return

A Promise to indicate whether the operation is resolved or rejected. If the Promise is resolved, it returns a short integer representing the RSSI value. If the property connectionState is not connected when the method is called, the Promise would be rejected.

Sample

var gatt = device.gatt;
if (gatt && gatt.connectionState === "connected") {
  gatt.readRemoteRssi().then { function onResolve(rssi) {
    console.log("Remote RSSI value:", rssi);
  }, function onReject(aReason) {
    console.log("Rejected with this reason: ", aReason);
  };
}

beginReliableWrite()

Description

The method initiates a reliable write transaction for the remote LE device.

Once a reliable write transaction has been initiated, all calls to characteristic.writeValue() are sent to the remote device for verification and queued up for atomic execution. An Promise that carries the written value is returned in response to every characteristic.writeValue() call and the application is responsible for verifying whether the value has been transmitted accurately. After all characteristics have been queued up and verified, executeReliableWrite() will execute all writes. If a characteristic was not written correctly, calling abortReliableWrite() will cancel the current transaction without commiting any values on the remote LE device.

Return

A Promise to indicate whether the operation is resolved or rejected.

executeReliableWrite()

Description

The method executes a reliable write transaction for the remote LE device. It will commit all queued up characteristic value write operations for the remote LE device.

Return

A Promise to indicate whether the operation is resolved or rejected.

abortReliableWrite()

Description

The method cancels a reliable write transaction for the remote LE device. Calling this method will discard all queued characteristic value write operations for the remote LE device.

Return

A Promise to indicate whether the operation is resolved or rejected.

findService(DOMString serviceUuid)

Description

The method is a helper to find the BluetoothGattService object of given service UUID from the offered GATT services list (i.e., property services). If multiple BluetoothGattService objects of given service UUID exist, the first BluetoothGattService object of the service is returned.

Return

A BluetoothGattService object of given service UUID.

Sample

var gatt = device.gatt;
if (gatt) {
  heartRateService = gatt.findService(0x180D);
}

See Also

• BluetoothDevice