B2G/Bluetooth/WebBluetooth-v2/BluetoothGattCharacteristic

Overview

BluetoothGattCharacteristic represents the characteristic of services. BluetoothGattCharacteristic consists of the characteristic definition, a characteristic value along with properties and configurations which indicate how to access the value, and a list of descriptors which provides related information of this characteristic value.

Interfaces

BluetoothGattCharacteristic

BluetoothGattCharacteristic

[CheckPermissions="bluetooth"]
interface BluetoothGattCharacteristic
{
  // Permission
  const unsigned short PERMISSION_READ              = 0x0001;
  const unsigned short PERMISSION_READ_ENCRYPTED    = 0x0002;
  const unsigned short PERMISSION_READ_ENC_MITM     = 0x0004;
  const unsigned short PERMISSION_WRITE             = 0x0010;
  const unsigned short PERMISSION_WRITE_ENCRYPTED   = 0x0020;
  const unsigned short PERMISSION_WRITE_ENC_MITM    = 0x0040;
  const unsigned short PERMISSION_WRITE_SIGNED      = 0x0080;
  const unsigned short PERMISSION_WRITE_SIGNED_MITM = 0x0100;

  // Property
  const unsigned short PROPERTY_BROADCAST         = 0x0001;
  const unsigned short PROPERTY_READ              = 0x0002;
  const unsigned short PROPERTY_WRITE_NO_RESPONSE = 0x0004;
  const unsigned short PROPERTY_WRITE             = 0x0008;
  const unsigned short PROPERTY_NOTIFY            = 0x0010;
  const unsigned short PROPERTY_INDICATE          = 0x0020;
  const unsigned short PROPERTY_SIGNED_WRITE      = 0x0040;
  const unsigned short PROPERTY_EXTENDED_PROPS    = 0x0080;

  // Write Type
  const unsigned short WRITE_TYPE_NO_RESPONSE     = 0x0001;
  const unsigned short WRITE_TYPE_DEFAULT         = 0x0002;
  const unsigned short WRITE_TYPE_SIGNED          = 0x0004;

  readonly attribute BluetoothGattService                  service;
  [Cached, Pure]
  readonly attribute sequence<BluetoothGattDescriptor>     descriptors;
  readonly attribute DOMString                             uuid;
  readonly attribute unsigned short                        instanceId;
  readonly attribute unsigned short                        permissions;
  readonly attribute unsigned short                        properties;
           attribute unsigned short                        writeType;
  readonly attribute ArrayBuffer?                          value;

  [NewObject, Throws]
  Promise<ArrayBuffer> readValue();
  [NewObject, Throws]
  Promise<ArrayBuffer> writeValue(ArrayBuffer value);
  [NewObject, Throws]
  Promise<void> startNotifications();
  [NewObject, Throws]
  Promise<void> stopNotifications();
  BluetoothGattDescriptor? findDescriptor(DOMString uuid);
};

Properties

• BluetoothGattCharacteristic.service
• BluetoothGattCharacteristic.descriptors
• BluetoothGattCharacteristic.uuid
• BluetoothGattCharacteristic.instanceId
• BluetoothGattCharacteristic.permissions
• BluetoothGattCharacteristic.properties
• BluetoothGattCharacteristic.writeType
• BluetoothGattCharacteristic.value

service

Description

The service which this characteristic belongs to.

Value Type

BluetoothGattService

Default Value

null pointer

descriptors

Description

A cached descriptor array of this characteristic.

Value Type

sequence<BluetoothGattDescriptor>

Default Value

Empty array (array with length = 0)

uuid

Description

This property stores the UUID of this characteristic.

Value Type

DOMString

Default Value

Empty string ("")

instanceId

Description

This property stores the instance id of this characteristic.

Value Type

unsigned short

Default Value

0

permissions

Description

A bit mask which describes the security level required for read/write accesses of this characteristic.

Value Type

unsigned short

Default Value

0

properties

Description

A bit mask which describes how the characteristic value can be used.

Value Type

unsigned short

Default Value

0

writeType

Description

The type of write operation.

Value Type

unsigned short

Default Value

0

value

Description

The cached value of this characteristic.

This value can be updated via readValue() method or via characteristic notification or indication from the remote device.

Value Type

ArrayBuffer or null

Default Value

null pointer

Methods

• BluetoothGattCharacteristic.readValue()
• BluetoothGattCharacteristic.writeValue(ArrayBuffer value)
• BluetoothGattCharacteristic.startNotifications()
• BluetoothGattCharacteristic.stopNotifications()
• BluetoothGattCharacteristic.findDescriptor(DOMString uuid)

readValue()

Description

Read the characteristic value from the remote device. The cached value property will also be updated after retrieving the value.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is resolved along with the value retrieved from the remote device.

writeValue(ArrayBuffer value)

Description

Write the characteristic value to the remote device.

Parameter

value

Desired value to be written to the remote device.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is resolved along with the characteristic value after this write operation.

startNotifications()

Description

Register notification/indication of this characteristic.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is rejected if there is no Client Characteristic Configuration descriptor (CCCD) for this characteristic.

stopNotifications()

Description

Unregister notification/indication of this characteristic.

Return

A Promise to indicate whether the operation is resolved or rejected. The Promise is rejected if there is no Client Characteristic Configuration descriptor (CCCD) for this characteristic.

findDescriptor(DOMString uuid)

Description

The method finds a descriptor of this characteristic from the descriptors property by the given UUID. When multiple descriptors with the same UUID exist, the first one is returned.

Parameters

uuid

UUID DOMString of the descriptor to seek for.

Return

The first descriptor with the given uuid in descriptors property.

A null pointer is returned if no descriptor is found by the given UUID.

Sample

const HEART_RATE_SERVICE = "0000180d-0000-1000-8000-00805f9b34fb";
const HEART_RATE_MEASUREMENT = "00002a37-0000-1000-8000-00805f9b34fb";
const CLIENT_CHAR_CONFIG = "00002902-0000-1000-8000-00805f9b34fb";

if (device.gatt) {
  // get heart rate service
  var heartRateService = device.gatt.findService(HEART_RATE_SERVICE));

  // get heart rate measurement characteristic from service
  if (heartRateService) {
    var heartRateMeasurement = 
      heartRateService.findCharacteristic(HEART_RATE_MEASUREMENT);

    // get Client Characteristic Configuration descriptor from characteristic
    if (heartRateMeasurement) {    
      var cccd = heartRateMeasurement.findDescriptor(CLIENT_CHAR_CONFIG);
    }
  }
}