BluetoothRemoteGATTCharacteristic.getDescriptor() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTCharacteristic.prototype.getDescriptor(descriptor)

Beschreibung

Mit getDescriptor() fragst du bei einer GATT-Characteristic eines verbundenen Bluetooth-Low-Energy-Geräts einen bestimmten Descriptor ab. Descriptoren liefern Metadaten zu einer Characteristic, etwa eine lesbare Beschreibung (Characteristic User Description, 0x2901), das Werteformat (0x2904) oder die Konfiguration für Benachrichtigungen (Client Characteristic Configuration, 0x2902).

Als Argument gibst du eine UUID an, entweder als vollständigen 128-Bit-String, als 16-/32-Bit-Alias (Zahl) oder als standardisierten Namen wie 'gatt.characteristic_user_description'. Das Promise wird mit dem ersten passenden Descriptor erfüllt. Gibt es mehrere Descriptoren mit derselben UUID, nimmst du getDescriptors(uuid).

Den Descriptor liest du danach mit readValue() aus, das ein DataView liefert, oder beschreibst ihn mit writeValue(). Voraussetzung ist ein verbundener GATT-Server (device.gatt.connected === true). Außerdem muss der zugehörige Service bei navigator.bluetooth.requestDevice() in filters oder optionalServices angegeben worden sein.

Parameter

Name	Typ	Default	Beschreibung
$descriptor Pflicht	string \| number		Die UUID des gesuchten Descriptors: ein vollständiger 128-Bit-UUID-String (Kleinbuchstaben), ein 16-/32-Bit-Alias als Zahl (z. B. `0x2901`) oder ein registrierter Name wie `'gatt.characteristic_user_description'`. Siehe `BluetoothUUID.getDescriptor()`.

Rückgabewert

Typ

Promise<BluetoothRemoteGATTDescriptor>

Beschreibung

Ein Promise, das mit dem ersten passenden BluetoothRemoteGATTDescriptor erfüllt wird. Es wird mit einem DOMException abgelehnt, wenn der Descriptor nicht existiert (NotFoundError), die Verbindung getrennt ist (NetworkError) oder die UUID gesperrt ist (SecurityError).

Beispiele

Benutzerbeschreibung einer Characteristic auslesen

const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['battery_service'] }]
    });
    const server = await device.gatt.connect();
    const service = await server.getPrimaryService('battery_service');
    const characteristic = await service.getCharacteristic('battery_level');

    // Descriptor 0x2901: Characteristic User Description
    const descriptor = await characteristic.getDescriptor('gatt.characteristic_user_description');
    const value = await descriptor.readValue();
    const text = new TextDecoder('utf-8').decode(value);
    console.log(`Beschreibung: ${text}`);
  } catch (error) {
    console.error(`${error.name}: ${error.message}`);
  }
});

Beschreibung: Battery Level

Benachrichtigungs-Konfiguration (CCCD) prüfen

const checkNotifications = async (characteristic) => {
  // 0x2902: Client Characteristic Configuration
  const cccd = await characteristic.getDescriptor(0x2902);
  const value = await cccd.readValue();
  const flags = value.getUint16(0, true); // Little Endian
  console.log(`Notifications aktiv: ${Boolean(flags & 0x1)}`);
  console.log(`Indications aktiv: ${Boolean(flags & 0x2)}`);
};

// Nutzung, nachdem startNotifications() aufgerufen wurde:
await characteristic.startNotifications();
await checkNotifications(characteristic);

Notifications aktiv: true Indications aktiv: false

Fehlenden Descriptor sauber abfangen

const getUserDescription = async (characteristic) => {
  try {
    const descriptor = await characteristic.getDescriptor(0x2901);
    const data = await descriptor.readValue();
    return new TextDecoder().decode(data);
  } catch (error) {
    if (error.name === 'NotFoundError') {
      return '(keine Beschreibung vorhanden)';
    }
    throw error;
  }
};

console.log(await getUserDescription(characteristic));

(keine Beschreibung vorhanden)

// Wichtig · Fallstricke

Browser-Unterstützung: Die Web Bluetooth API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera; auf Android, ChromeOS, macOS und Windows). Firefox und Safari unterstützen sie nicht. Prüfe vorher mit 'bluetooth' in navigator, ob die API da ist.
Sicherer Kontext: Die API funktioniert nur über HTTPS oder localhost. requestDevice() braucht zusätzlich eine Nutzeraktion, zum Beispiel einen Klick.
Blockliste: Bestimmte Descriptoren sind gesperrt. Beim Lesen oder Schreiben kommt dann ein SecurityError. Die CCCD (0x2902) lässt sich zwar lesen, aber nicht direkt beschreiben. Nutze dafür startNotifications() bzw. stopNotifications().
UUID-Format: 128-Bit-UUIDs müssen in Kleinbuchstaben angegeben werden, sonst wirft die Methode einen TypeError.
Verbindungsverlust: Trennt sich das Gerät, werden offene Promises mit NetworkError abgelehnt. Reagiere auf das Event gattserverdisconnected.
Das Promise liefert nur den ersten Treffer. Für alle Descriptoren einer UUID oder der ganzen Characteristic nimmst du getDescriptors().

Siehe auch

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