BluetoothRemoteGATTCharacteristic.getDescriptors() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTCharacteristic.prototype.getDescriptors(descriptor)

Beschreibung

Mit getDescriptors() fragst du die Descriptoren einer GATT-Charakteristik auf einem entfernten Bluetooth-Low-Energy-Gerät ab. Descriptoren liefern Zusatzinformationen zur Charakteristik, etwa eine lesbare Beschreibung (Characteristic User Description, 0x2901), das Datenformat (0x2904) oder die Konfiguration für Benachrichtigungen (Client Characteristic Configuration, 0x2902).

Rufst du die Methode ohne Argument auf, erhältst du alle Descriptoren der Charakteristik. Gibst du eine UUID an, bekommst du nur die Descriptoren mit genau dieser UUID. Brauchst du nur einen einzigen Descriptor, ist getDescriptor() meist die einfachere Wahl.

Die Methode funktioniert nur, wenn der GATT-Server verbunden ist (device.gatt.connected === true). Außerdem musst du den zugehörigen Dienst beim Aufruf von navigator.bluetooth.requestDevice() in filters oder optionalServices angegeben haben. Sonst lehnt der Browser den Zugriff ab.

Parameter

Name	Typ	Default	Beschreibung
$descriptor	string \| number		Optional. Die UUID des gesuchten Descriptors: als vollständige 128-Bit-UUID (`'00002901-0000-1000-8000-00805f9b34fb'`), als 16- oder 32-Bit-Alias (`0x2901`) oder als registrierter Name (`'gatt.characteristic_user_description'`). Fehlt der Parameter, werden alle Descriptoren zurückgegeben.

Rückgabewert

Typ

Promise<BluetoothRemoteGATTDescriptor[]>

Beschreibung

Ein Promise, das zu einem Array von BluetoothRemoteGATTDescriptor-Objekten aufgelöst wird. Wird kein passender Descriptor gefunden, wird das Promise mit einem NotFoundError abgelehnt.

Beispiele

Alle Descriptoren einer Charakteristik auflisten

const listDescriptors = async () => {
  // Muss durch eine Nutzeraktion ausgelöst werden (z. B. einen Klick)
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['heart_rate'] }]
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('heart_rate');
  const characteristic = await service.getCharacteristic('heart_rate_measurement');

  const descriptors = await characteristic.getDescriptors();
  for (const d of descriptors) {
    console.log('Descriptor-UUID:', d.uuid);
  }
};

document.querySelector('#scan').addEventListener('click', listDescriptors);

Descriptor-UUID: 00002902-0000-1000-8000-00805f9b34fb

Nach UUID filtern und die Benutzerbeschreibung lesen

const readUserDescriptions = async (characteristic) => {
  try {
    // 0x2901 = Characteristic User Description
    const descriptors = await characteristic.getDescriptors(0x2901);
    const decoder = new TextDecoder('utf-8');
    for (const d of descriptors) {
      const value = await d.readValue(); // DataView
      console.log('Beschreibung:', decoder.decode(value));
    }
  } catch (err) {
    if (err.name === 'NotFoundError') {
      console.log('Keine Benutzerbeschreibung vorhanden.');
    } else {
      throw err;
    }
  }
};

Beschreibung: Temperatur Sensor 1

Descriptoren aller Charakteristiken eines Dienstes erfassen

const dumpService = async (service) => {
  const characteristics = await service.getCharacteristics();
  const result = {};
  for (const c of characteristics) {
    try {
      const descs = await c.getDescriptors();
      result[c.uuid] = descs.map((d) => d.uuid);
    } catch {
      result[c.uuid] = []; // Charakteristik ohne Descriptoren
    }
  }
  console.table(result);
  return result;
};

// Wichtig · Fallstricke

Kompatibilität: Web Bluetooth ist experimentell. Es wird nur in Chromium-basierten Browsern unterstützt (Chrome, Edge, Opera; unter Linux teilweise nur mit Flag). Firefox und Safari unterstützen es nicht. Prüfe vorab mit 'bluetooth' in navigator.
Die API funktioniert nur in sicheren Kontexten (HTTPS oder localhost). In iframes muss die Permissions Policy bluetooth das erlauben.
Findet der Browser keinen passenden Descriptor, lehnt er das Promise mit NotFoundError ab und liefert kein leeres Array. Fange diesen Fehler ab.
Ist das Gerät getrennt, schlägt der Aufruf mit NetworkError fehl. Überwache das Event gattserverdisconnected und baue die Verbindung bei Bedarf neu auf.
Einige Descriptoren stehen auf der GATT-Blocklist. Sie werden nicht zurückgegeben oder lösen einen SecurityError aus. Den Descriptor 0x2902 solltest du nicht selbst beschreiben. Nutze dafür startNotifications().
Führe GATT-Operationen nacheinander aus, nicht parallel. Viele Geräte und Plattformen melden sonst „GATT operation already in progress“.

Siehe auch

BluetoothRemoteGATTCharacteristic.getDescriptor() BluetoothRemoteGATTCharacteristic.readValue() BluetoothRemoteGATTCharacteristic.startNotifications() BluetoothRemoteGATTCharacteristic.stopNotifications() BluetoothRemoteGATTCharacteristic.writeValue()