BluetoothUUID.canonicalUUID() — Methode · JavaScript-Referenz

Signatur

BluetoothUUID.canonicalUUID(alias)

Beschreibung

Die statische Methode BluetoothUUID.canonicalUUID() gehört zur Web Bluetooth API. Sie nimmt einen kurzen UUID-Alias entgegen, wie ihn die Bluetooth SIG für Standarddienste, Charakteristiken und Deskriptoren vergibt (z. B. 0x180F für den Battery Service), und liefert die vollständige 128-Bit-UUID als Zeichenkette.

Die Umrechnung folgt der Bluetooth-Basis-UUID 00000000-0000-1000-8000-00805f9b34fb: Der Alias wird in die ersten 32 Bit eingesetzt. Aus 0x180F wird so "0000180f-0000-1000-8000-00805f9b34fb". Das Ergebnis besteht immer aus Kleinbuchstaben. Genau in diesem Format liefern auch Eigenschaften wie BluetoothRemoteGATTService.uuid ihre Werte.

Praktisch ist die Methode vor allem, wenn du UUIDs vergleichen, in Tabellen nachschlagen oder protokollieren willst. Werte, die ein Gerät zurückgibt, sind immer 128-Bit-Strings. Mit canonicalUUID() bringst du bekannte Kurz-Aliase in dasselbe Format und kannst sie dann einfach mit === vergleichen. Wenn du dagegen Namen wie "battery_service" auflösen willst, nimm besser BluetoothUUID.getService() oder die verwandten Methoden.

Parameter

Name	Typ	Default	Beschreibung
$alias Pflicht	number		Ein 16- oder 32-Bit-UUID-Alias als vorzeichenlose Ganzzahl, üblicherweise hexadezimal geschrieben (z. B. `0x2A19`). Erlaubt sind Werte von `0` bis `0xFFFFFFFF`.

Rückgabewert

Typ

string

Beschreibung

Die vollständige 128-Bit-UUID in Kleinbuchstaben im Format xxxxxxxx-0000-1000-8000-00805f9b34fb.

Beispiele

16-Bit-Alias des Battery Service umwandeln

const uuid = BluetoothUUID.canonicalUUID(0x180F);
console.log(uuid);

0000180f-0000-1000-8000-00805f9b34fb

32-Bit-Alias umwandeln

console.log(BluetoothUUID.canonicalUUID(0x12345678));

12345678-0000-1000-8000-00805f9b34fb

Dienste eines verbundenen Geräts mit bekannten Aliasen vergleichen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. einen Klick)
const verbinden = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: [0x180D] }],
    optionalServices: [0x180F]
  });
  const server = await device.gatt.connect();
  const services = await server.getPrimaryServices();

  const bekannt = {
    [BluetoothUUID.canonicalUUID(0x180D)]: 'Herzfrequenz',
    [BluetoothUUID.canonicalUUID(0x180F)]: 'Batterie'
  };

  for (const service of services) {
    console.log(service.uuid, '→', bekannt[service.uuid] ?? 'unbekannt');
  }
};

document.querySelector('#connect').addEventListener('click', verbinden);

0000180d-0000-1000-8000-00805f9b34fb → Herzfrequenz 0000180f-0000-1000-8000-00805f9b34fb → Batterie

Fallback, wenn die API fehlt

const canonicalUUID = (alias) =>
  globalThis.BluetoothUUID?.canonicalUUID?.(alias) ??
  `${(alias >>> 0).toString(16).padStart(8, '0')}-0000-1000-8000-00805f9b34fb`;

console.log(canonicalUUID(0x2A19));

00002a19-0000-1000-8000-00805f9b34fb

// Wichtig · Fallstricke

Kompatibilität: Die Web Bluetooth API ist experimentell. Sie wird nur von Chromium-Browsern unterstützt (Chrome, Edge, Opera), nicht von Firefox oder Safari und auch nicht in iOS-Browsern. Prüfe deshalb vorher mit 'BluetoothUUID' in globalThis, ob die Schnittstelle verfügbar ist.
Sicherer Kontext: Die API steht nur über HTTPS oder localhost zur Verfügung. Zum Umrechnen selbst ist keine Nutzeraktion nötig, für requestDevice() dagegen schon.
Zahl statt String übergeben: canonicalUUID("180f") wird nicht als Hexadezimalwert gelesen. Übergib den Alias als Zahlenliteral, also 0x180F. Zu große, negative oder ungültige Werte führen zu einem TypeError, weil die Spezifikation den Wertebereich erzwingt.
Groß-/Kleinschreibung: Das Ergebnis ist immer kleingeschrieben. Eigene UUID-Strings solltest du vor dem Vergleich mit toLowerCase() umwandeln.
Die Methode rechnet nur um. Sie prüft nicht, ob der Alias von der Bluetooth SIG tatsächlich vergeben wurde.

Siehe auch

BluetoothUUID BluetoothUUID.getService() BluetoothUUID.getCharacteristic() BluetoothUUID.getDescriptor() Bluetooth.requestDevice() BluetoothRemoteGATTService