BluetoothRemoteGATTDescriptor.uuid — Eigenschaft · JavaScript-Referenz

Signatur

BluetoothRemoteGATTDescriptor.uuid

Beschreibung

Die Eigenschaft uuid eines BluetoothRemoteGATTDescriptor-Objekts gibt an, um welchen Deskriptor es sich handelt. Deskriptoren hängen an einem Merkmal (BluetoothRemoteGATTCharacteristic) und liefern Zusatzinformationen dazu, zum Beispiel eine lesbare Beschreibung (Characteristic User Description, 0x2901), die Konfiguration von Benachrichtigungen (Client Characteristic Configuration, 0x2902) oder das Darstellungsformat (0x2904).

Der Wert ist immer ein vollständiger 128-Bit-UUID-String in Kleinbuchstaben, etwa "00002901-0000-1000-8000-00805f9b34fb". Das gilt auch dann, wenn der Deskriptor über einen Kurznamen wie "gatt.characteristic_user_description" oder eine 16-Bit-Zahl wie 0x2901 abgefragt wurde.

Brauchen wirst du die Eigenschaft vor allem, wenn du mit getDescriptors() alle Deskriptoren eines Merkmals auflistest und dann einzelne anhand ihrer UUID erkennen oder filtern willst. Zum Vergleichen solltest du bekannte Kennungen mit BluetoothUUID.getDescriptor() in die kanonische Form umwandeln, statt Strings von Hand zu schreiben.

Rückgabewert

Typ

string

Beschreibung

Die UUID des Deskriptors als kleingeschriebener 128-Bit-String im Format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Beispiele

UUID eines bestimmten Deskriptors auslesen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
const button = document.querySelector('#verbinden');

button.addEventListener('click', async () => {
  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 descriptor = await characteristic.getDescriptor(
    'gatt.client_characteristic_configuration'
  );
  console.log(descriptor.uuid);
});

00002902-0000-1000-8000-00805f9b34fb

Alle Deskriptoren eines Merkmals auflisten

const listDescriptors = async (characteristic) => {
  const descriptors = await characteristic.getDescriptors();
  for (const d of descriptors) {
    console.log(`Deskriptor: ${d.uuid}`);
  }
};

Deskriptor: 00002901-0000-1000-8000-00805f9b34fb Deskriptor: 00002902-0000-1000-8000-00805f9b34fb

Benutzerbeschreibung per UUID-Vergleich finden und lesen

const readUserDescription = async (characteristic) => {
  const target = BluetoothUUID.getDescriptor('gatt.characteristic_user_description');
  const descriptors = await characteristic.getDescriptors();
  const userDesc = descriptors.find((d) => d.uuid === target);
  if (!userDesc) return null;

  const value = await userDesc.readValue();
  return new TextDecoder('utf-8').decode(value);
};

// Aufruf: console.log(await readUserDescription(characteristic));

Batteriestand

// Wichtig · Fallstricke

Browser-Kompatibilität: Web Bluetooth ist experimentell und steht nur in Chromium-basierten Browsern (Chrome, Edge, Opera) auf Desktop und Android zur Verfügung. Firefox und Safari unterstützen die API nicht. Prüfe vorher mit 'bluetooth' in navigator, ob sie verfügbar ist.
Die API funktioniert nur in einem sicheren Kontext (HTTPS oder localhost). requestDevice() muss durch eine Nutzeraktion ausgelöst werden.
Vorsicht beim Vergleichen: uuid ist immer die lange Form in Kleinbuchstaben. Ein Vergleich wie d.uuid === '0x2901' oder d.uuid === 0x2901 ergibt nie true. Wandle die Vergleichswerte deshalb mit BluetoothUUID.getDescriptor() oder BluetoothUUID.canonicalUUID() um.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird ignoriert, im Strict Mode löst sie einen TypeError aus.
Manche Deskriptoren stehen auf der Sperrliste von Web Bluetooth (die Blocklist). Sie werden nicht zurückgegeben, oder beim Lesen oder Schreiben wird ein SecurityError ausgelöst.

Siehe auch

BluetoothRemoteGATTDescriptor.value BluetoothRemoteGATTService.uuid BluetoothRemoteGATTDescriptor.characteristic BluetoothRemoteGATTCharacteristic.uuid BluetoothRemoteGATTServer.device