B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt

From MozillaWiki
Jump to: navigation, search

Overview

BluetoothGatt provides bluetooth Generic Attribute Profile (GATT) client functionality to enable communication with a remote LE device.

Interface

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

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

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

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

Retrieved from "https://wiki.mozilla.org/index.php?title=B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt&oldid=1051039"