B2G/Bluetooth/WebBluetooth-v2/BluetoothGatt
From MozillaWiki
< B2G | Bluetooth | WebBluetooth-v2
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
- 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.