BluetoothUUID — Schnittstelle · JavaScript-Referenz

Signatur

interface BluetoothUUID

Beschreibung

Die Schnittstelle BluetoothUUID gehört zur Web Bluetooth API. Sie ist ein reiner Namensraum mit statischen Methoden: Es gibt keinen Konstruktor, und man erzeugt keine Instanzen. Mit diesen Methoden wandelt man die von der Bluetooth SIG registrierten Namen (z. B. "heart_rate") oder kurze numerische Aliase (z. B. 0x180D) in die vollständige, kleingeschriebene 128-Bit-UUID um, etwa "0000180d-0000-1000-8000-00805f9b34fb".

Zur Verfügung stehen folgende statische Methoden:

BluetoothUUID.getService(name) – liefert die UUID eines GATT-Service.
BluetoothUUID.getCharacteristic(name) – liefert die UUID einer GATT-Characteristic.
BluetoothUUID.getDescriptor(name) – liefert die UUID eines GATT-Descriptors.
BluetoothUUID.canonicalUUID(alias) – baut aus einem 16- oder 32-Bit-Alias die vollständige UUID auf Basis der Bluetooth-Basis-UUID 0000xxxx-0000-1000-8000-00805f9b34fb.

Praktisch ist BluetoothUUID vor allem, wenn man UUIDs vergleichen, protokollieren oder normalisieren möchte. Methoden wie navigator.bluetooth.requestDevice() oder BluetoothRemoteGATTServer.getPrimaryService() akzeptieren zwar ebenfalls Namen und Aliase direkt, die Eigenschaft uuid der zurückgegebenen Objekte enthält aber stets die ausgeschriebene 128-Bit-Form. Wer diese mit bekannten Werten vergleichen will, nutzt BluetoothUUID zur Normalisierung.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string \| number		Für `getService()`, `getCharacteristic()` und `getDescriptor()`: ein registrierter GATT-Name (z. B. `"battery_service"`), ein 16/32-Bit-Alias als Zahl oder bereits eine gültige 128-Bit-UUID in Kleinbuchstaben.
$alias Pflicht	number		Für `canonicalUUID()`: ein 16- oder 32-Bit-Alias, z. B. `0x180F`.

Rückgabewert

Typ

string

Beschreibung

Alle statischen Methoden liefern die vollständige 128-Bit-UUID als kleingeschriebenen String im Format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Beispiele

Namen und Aliase in UUIDs umwandeln

// Keine Instanz nötig – alle Methoden sind statisch
console.log(BluetoothUUID.getService('heart_rate'));
console.log(BluetoothUUID.getCharacteristic('heart_rate_measurement'));
console.log(BluetoothUUID.getDescriptor('gatt.client_characteristic_configuration'));
console.log(BluetoothUUID.canonicalUUID(0x180F));

0000180d-0000-1000-8000-00805f9b34fb 00002a37-0000-1000-8000-00805f9b34fb 00002902-0000-1000-8000-00805f9b34fb 0000180f-0000-1000-8000-00805f9b34fb

Gefundene Services mit bekannten UUIDs vergleichen

const connectAndListServices = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['battery_service'] }],
    optionalServices: ['device_information']
  });
  const server = await device.gatt.connect();
  const services = await server.getPrimaryServices();

  const batteryUUID = BluetoothUUID.getService('battery_service');
  for (const service of services) {
    const label = service.uuid === batteryUUID ? 'Akku-Service' : 'anderer Service';
    console.log(`${service.uuid} → ${label}`);
  }
};

// Muss durch eine Nutzergeste ausgelöst werden
document.querySelector('#connect').addEventListener('click', connectAndListServices);

0000180f-0000-1000-8000-00805f9b34fb → Akku-Service 0000180a-0000-1000-8000-00805f9b34fb → anderer Service

Unbekannte Namen sicher abfangen

const toServiceUUID = (value) => {
  try {
    return BluetoothUUID.getService(value);
  } catch (err) {
    console.warn(`Ungültiger Service-Name: ${value} (${err.name})`);
    return null;
  }
};

console.log(toServiceUUID('battery_service'));
console.log(toServiceUUID('gibt_es_nicht'));

0000180f-0000-1000-8000-00805f9b34fb Ungültiger Service-Name: gibt_es_nicht (TypeError) null

// Wichtig · Fallstricke

Browser-Unterstützung: Web Bluetooth und damit BluetoothUUID gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera). Firefox und Safari unterstützen die API nicht. Vorher mit 'BluetoothUUID' in window bzw. 'bluetooth' in navigator prüfen.
Die API steht nur in einem sicheren Kontext (HTTPS oder localhost) zur Verfügung und kann per Permissions-Policy (bluetooth) gesperrt sein.
new BluetoothUUID() ist nicht möglich. Alle Methoden sind statisch.
Unbekannte Namen oder falsch formatierte UUIDs (z. B. in Großbuchstaben) lösen einen TypeError aus. Namen müssen exakt der GATT-Schreibweise entsprechen, etwa \"battery_service\" und nicht \"Battery Service\".
canonicalUUID() prüft nicht, ob ein Alias tatsächlich registriert ist. Die Methode setzt den Wert nur in die Basis-UUID ein.
Beim Vergleich von UUIDs immer die kleingeschriebene 128-Bit-Form verwenden, denn die Eigenschaften uuid von Services und Characteristics liefern genau dieses Format.

Siehe auch

Bluetooth BluetoothDevice GPUTexture AudioTrack Blob