BluetoothUUID.getService() — Methode · JavaScript-Referenz

Signatur

BluetoothUUID.getService(name)

Beschreibung

Die statische Methode BluetoothUUID.getService() übersetzt einen Bluetooth-GATT-Dienst in seine vollständige, kleingeschriebene 128-Bit-UUID (z. B. "0000180f-0000-1000-8000-00805f9b34fb"). Als Eingabe akzeptiert sie entweder einen von der Bluetooth SIG registrierten Namen wie "battery_service" oder "heart_rate", einen 16- bzw. 32-Bit-Alias als Zahl (z. B. 0x180F) oder eine bereits gültige 128-Bit-UUID-Zeichenkette.

Nützlich ist die Methode vor allem, wenn du Dienst-UUIDs normalisieren willst: etwa um die Rückgabe von BluetoothRemoteGATTService.uuid (immer eine volle 128-Bit-UUID) mit einem lesbaren Namen zu vergleichen, oder um Konfigurationen mit gemischten Schreibweisen zu vereinheitlichen. Intern verwenden navigator.bluetooth.requestDevice() und BluetoothRemoteGATTServer.getPrimaryService() genau diese Auflösung, weshalb du dort ebenfalls Namen oder Aliase übergeben darfst.

Die Umwandlung numerischer Aliase erfolgt über die Bluetooth-Basis-UUID 0000xxxx-0000-1000-8000-00805f9b34fb. Unbekannte Namen oder ungültige Zeichenketten führen zu einem TypeError. Die Methode arbeitet synchron und benötigt weder Nutzergeste noch Gerätezugriff.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string \| number		Registrierter Dienstname (z. B. `"battery_service"`), ein 16- oder 32-Bit-Alias als Ganzzahl (z. B. `0x180D`) oder eine gültige, kleingeschriebene 128-Bit-UUID-Zeichenkette.

Rückgabewert

Typ

string

Beschreibung

Die vollständige 128-Bit-UUID des Dienstes in Kleinbuchstaben, z. B. "0000180d-0000-1000-8000-00805f9b34fb". Bei ungültiger Eingabe wird ein TypeError geworfen.

Beispiele

Namen und Aliase in UUIDs umwandeln

// Registrierter Name
console.log(BluetoothUUID.getService('battery_service'));
// 16-Bit-Alias als Zahl
console.log(BluetoothUUID.getService(0x180D));
// Volle UUID bleibt unverändert
console.log(BluetoothUUID.getService('0000180a-0000-1000-8000-00805f9b34fb'));

0000180f-0000-1000-8000-00805f9b34fb 0000180d-0000-1000-8000-00805f9b34fb 0000180a-0000-1000-8000-00805f9b34fb

Gefundene Dienste eines Geräts benennen

const bekannteDienste = ['battery_service', 'heart_rate', 'device_information'];
const uuidZuName = new Map(
  bekannteDienste.map((n) => [BluetoothUUID.getService(n), n])
);

const button = document.querySelector('#verbinden');
button.addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      acceptAllDevices: true,
      optionalServices: bekannteDienste
    });
    const server = await device.gatt.connect();
    const services = await server.getPrimaryServices();
    for (const s of services) {
      console.log(s.uuid, '→', uuidZuName.get(s.uuid) ?? 'unbekannt');
    }
  } catch (err) {
    console.error('Bluetooth-Fehler:', err);
  }
});

0000180f-0000-1000-8000-00805f9b34fb → battery_service

Ungültige Eingaben abfangen

const sicherAufloesen = (eingabe) => {
  try {
    return BluetoothUUID.getService(eingabe);
  } catch (err) {
    console.warn(`Ungültiger Dienst: ${eingabe} (${err.name})`);
    return null;
  }
};

console.log(sicherAufloesen('heart_rate'));
console.log(sicherAufloesen('Battery_Service'));

0000180d-0000-1000-8000-00805f9b34fb Ungültiger Dienst: Battery_Service (TypeError) null

// Wichtig · Fallstricke

Browser-Unterstützung: Die Web Bluetooth API ist experimentell und nur in Chromium-Browsern (Chrome, Edge, Opera) verfügbar – nicht in Firefox und Safari (inkl. iOS). Prüfe vorab mit 'bluetooth' in navigator bzw. typeof BluetoothUUID !== 'undefined'.
Sicherer Kontext: BluetoothUUID ist nur in sicheren Kontexten (HTTPS oder localhost) vorhanden.
Groß-/Kleinschreibung: Namen müssen exakt der registrierten Schreibweise entsprechen ("heart_rate", nicht "Heart Rate"); UUID-Zeichenketten müssen kleingeschrieben sein, sonst gibt es einen TypeError.
Zahl vs. Zeichenkette: Ein Alias wie "180d" als Zeichenkette ist ungültig – übergib ihn als Zahl (0x180D).
Die Methode gilt nur für Dienste. Für Charakteristiken bzw. Deskriptoren verwende BluetoothUUID.getCharacteristic() bzw. BluetoothUUID.getDescriptor(), da sich die Namensräume unterscheiden.

Siehe auch

BluetoothUUID BluetoothUUID.getCharacteristic() BluetoothUUID.getDescriptor() BluetoothUUID.canonicalUUID() BluetoothRemoteGATTServer.getPrimaryService() Bluetooth.requestDevice() TrustedHTML.toString()