B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt

Overview

BluetoothGatt provides bluetooth Generic Attribute Profile (GATT) client functionality to enable communication with 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 oncharacteristicchanged;
           attribute EventHandler onconnectionstatechanged;

  [NewObject] Promise<void> connect();
  [NewObject] Promise<void> disconnect();
  [NewObject] Promise<void> discoverServices();
  [NewObject] Promise<short> readRemoteRssi();
  // Reliable write
  [NewObject] Promise<void> beginReliableWrite();
  [NewObject] Promise<void> executeReliableWrite();
  [NewObject] Promise<void> abortReliableWrite();
};

BluetoothConnectionState

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

Properties

• BluetoothGatt.services
• BluetoothGatt.connectionState

services

Description

The list of GATT services offered by the remote LE device. This property is set to default value (an empty array) before connection is established.

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. This property is set to default value (BluetoothConnectionState.disconnected) before connection is established.

Value type

BluetoothConnectionState

Default Value

BluetoothConnectionState.disconnected

Event Handlers

• BluetoothGatt.oncharacteristicchanged
• BluetoothGatt.onconnectionstatechanged

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.discoverServices()
• BluetoothGatt.readRemoteRssi()
• BluetoothGatt.beginReliableWrite()
• BluetoothGatt.executeReliableWrite()
• BluetoothGatt.abortReliableWrite()

connect()

Description

The method connects to the remote LE device.

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.

Sample

var gatt = device.gatt;
if (gatt) {
  gatt.connect(false).then ( function onResolve() {
    console.log("Connection established. ConnectionState becomes:", gatt.connectionState);
  }, function onReject(aReason) {
    console.log("Rejected with this reason: ", aReason, ". ConnectionState becomes:", gatt.connectionState);
  });
}

Note

Auto connection establishment procedure defined in bluetooth specification(3.C.9.3.5) is not supported yet.

Please see Bug 1126123 for details.

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.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);
  };
}

discoverServices()

Description

The method discovers services, characteristics, and descriptors offered by the remote GATT server.

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.discoverServices().then ( function onResolve() {
    console.log("Services, characteristics, and descriptors are successfully discovered.");
  }, function onReject(aReason) {
    console.log("Rejected with this reason: ", aReason);
  };
}

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 committing 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.

See Also

• BluetoothDevice