Signatur
Beschreibung
Die statische Methode BluetoothUUID.getDescriptor() gehört zur Web Bluetooth API. Sie liefert zu einem Deskriptor die vollständige, kleingeschriebene 128-Bit-UUID (z. B. "00002902-0000-1000-8000-00805f9b34fb"). Als Eingabe dient entweder ein registrierter Name aus der Bluetooth-SIG-GATT-Liste (etwa "gatt.client_characteristic_configuration"), ein 16- bzw. 32-Bit-Alias als Zahl (etwa 0x2902) oder eine bereits gültige 128-Bit-UUID.
Deskriptoren sind Metadaten einer GATT-Characteristic, zum Beispiel eine lesbare Beschreibung (Characteristic User Description, 0x2901) oder die Konfiguration für Benachrichtigungen (Client Characteristic Configuration, 0x2902). Mit getDescriptor() legt man diese Kennungen einheitlich fest, etwa um Deskriptor-UUIDs zu vergleichen, sie zu protokollieren oder als Schlüssel in einer Zuordnungstabelle zu verwenden.
Die Umwandlung passiert rein lokal und synchron, eine Verbindung zu einem Gerät ist dafür nicht nötig. Numerische Aliase werden in die Bluetooth-Basis-UUID 0000xxxx-0000-1000-8000-00805f9b34fb eingesetzt. Unbekannte Namen oder ungültige Zeichenketten lösen einen TypeError aus.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $name Pflicht | string | number | Ein registrierter Deskriptor-Name (z. B. "gatt.characteristic_user_description"), ein 16- oder 32-Bit-Alias als Ganzzahl (z. B. 0x2901) oder eine gültige, kleingeschriebene 128-Bit-UUID. |
Rückgabewert
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.Beispiele
Namen und Aliase in UUIDs umwandeln
// Registrierter Name
console.log(BluetoothUUID.getDescriptor('gatt.client_characteristic_configuration'));
// 16-Bit-Alias als Zahl
console.log(BluetoothUUID.getDescriptor(0x2901));
// Eine gültige 128-Bit-UUID kommt unverändert zurück
console.log(BluetoothUUID.getDescriptor('00002904-0000-1000-8000-00805f9b34fb'));Benutzerbeschreibung einer Characteristic lesen
const USER_DESCRIPTION = BluetoothUUID.getDescriptor('gatt.characteristic_user_description');
const readDescription = async () => {
// requestDevice muss durch eine Nutzeraktion (z. B. Klick) ausgelöst werden
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');
const descriptors = await characteristic.getDescriptors();
const desc = descriptors.find((d) => d.uuid === USER_DESCRIPTION);
if (desc) {
const value = await desc.readValue();
console.log('Beschreibung:', new TextDecoder().decode(value));
} else {
console.log('Keine Benutzerbeschreibung vorhanden');
}
};
document.querySelector('#connect').addEventListener('click', readDescription);Ungültige Eingaben abfangen
const toDescriptorUUID = (input) => {
try {
return BluetoothUUID.getDescriptor(input);
} catch (err) {
console.warn(`Unbekannter Deskriptor "${input}":`, err.name);
return null;
}
};
console.log(toDescriptorUUID('gatt.valid_range'));
console.log(toDescriptorUUID('mein_deskriptor'));// Wichtig · Fallstricke
- Browserunterstützung: Die Web Bluetooth API ist experimentell und steht nur in Chromium-basierten Browsern bereit (Chrome, Edge, Opera, teilweise mit Einschränkungen je nach Betriebssystem). Firefox und Safari unterstützen sie nicht. Vor der Nutzung sollte man prüfen, ob sie vorhanden ist:
'BluetoothUUID' in window. - Sicherer Kontext: Die API gibt es nur über HTTPS bzw.
localhost. Außerdem kann sie perPermissions-Policy: bluetoothgesperrt sein. - TypeError: Unbekannte Namen, großgeschriebene oder falsch formatierte UUID-Zeichenketten lösen einen
TypeErroraus. Ein 16-Bit-Alias als Zeichenkette wie\"0x2902\"ist ungültig, es muss eine Zahl übergeben werden. - Namen sind nicht austauschbar: Ein Characteristic-Name wie
\"battery_level\"funktioniert hier nicht. Für Characteristics gibt esBluetoothUUID.getCharacteristic(), für ServicesBluetoothUUID.getService(). BluetoothRemoteGATTCharacteristic.getDescriptor()nimmt Namen und Aliase auch direkt an. Eine vorherige Umwandlung braucht man vor allem zum Vergleichen mitdescriptor.uuid.- Den Deskriptor
0x2902(Client Characteristic Configuration) schreibt Chrome aus Sicherheitsgründen nicht direkt. Benachrichtigungen schaltet man stattdessen überstartNotifications()ein.