BluetoothUUID.getCharacteristic() — Methode · JavaScript-Referenz

Signatur

BluetoothUUID.getCharacteristic(name)

Beschreibung

Die statische Methode BluetoothUUID.getCharacteristic() gehört zur Web Bluetooth API. Sie liefert zu einer von der Bluetooth SIG registrierten GATT-Charakteristik die vollständige 128-Bit-UUID in Kleinbuchstaben, z. B. "00002a37-0000-1000-8000-00805f9b34fb" für "heart_rate_measurement".

Als Argument sind drei Formen erlaubt:

ein registrierter Name in snake_case, z. B. "battery_level", der in der GATT-Namensliste der Bluetooth SIG steht,
ein 16- oder 32-Bit-Alias als Zahl, z. B. 0x2A19,
eine vollständige 128-Bit-UUID als String in Kleinbuchstaben. Sie wird unverändert zurückgegeben.

Die Methode ist nützlich, wenn man UUIDs einheitlich ablegen, vergleichen oder protokollieren will, etwa um die Ergebnisse von BluetoothRemoteGATTService.getCharacteristics() einer bekannten Charakteristik zuzuordnen. Methoden wie getCharacteristic() auf einem Service nehmen Namen und Aliase auch direkt an. Die ausdrückliche Umwandlung braucht man vor allem für Vergleiche und Nachschlagetabellen.

Für Services und Deskriptoren gibt es die passenden Methoden BluetoothUUID.getService() und BluetoothUUID.getDescriptor(). Aus einem beliebigen Alias ohne Namensprüfung erzeugt BluetoothUUID.canonicalUUID() eine UUID.

Parameter

Name	Typ	Default	Beschreibung
$name Pflicht	string \| number		Ein registrierter Charakteristik-Name (z. B. `"battery_level"`), ein 16-/32-Bit-Alias als Zahl (z. B. `0x2A19`) oder eine 128-Bit-UUID in Kleinbuchstaben.

Rückgabewert

Typ

string

Beschreibung

Die vollständige 128-Bit-UUID der Charakteristik als String in Kleinbuchstaben. Ist der Name unbekannt oder ungültig, wird ein TypeError ausgelöst.

Beispiele

Name und Alias in eine UUID umwandeln

const fromName = BluetoothUUID.getCharacteristic('battery_level');
const fromAlias = BluetoothUUID.getCharacteristic(0x2A19);

console.log(fromName);
console.log(fromName === fromAlias);

00002a19-0000-1000-8000-00805f9b34fb true

Charakteristiken eines Services bekannten Namen zuordnen

const known = new Map(
  ['heart_rate_measurement', 'body_sensor_location', 'heart_rate_control_point']
    .map((name) => [BluetoothUUID.getCharacteristic(name), name])
);

const listCharacteristics = 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 characteristics = await service.getCharacteristics();

  for (const c of characteristics) {
    console.log(c.uuid, '→', known.get(c.uuid) ?? 'unbekannt');
  }
};

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

00002a37-0000-1000-8000-00805f9b34fb → heart_rate_measurement 00002a38-0000-1000-8000-00805f9b34fb → body_sensor_location

Ungültige Namen sicher abfangen

const toCharacteristicUUID = (value) => {
  try {
    return BluetoothUUID.getCharacteristic(value);
  } catch (err) {
    console.warn(`Ungültige Charakteristik: ${value}`, err.name);
    return null;
  }
};

console.log(toCharacteristicUUID('Battery Level')); // falsches Format
console.log(toCharacteristicUUID('0x2a19'));        // String statt Zahl

Ungültige Charakteristik: Battery Level TypeError null Ungültige Charakteristik: 0x2a19 TypeError null

// Wichtig · Fallstricke

Kompatibilität: Die Web Bluetooth API ist experimentell und nur in Chromium-Browsern verfügbar (Chrome, Edge, Opera; unter Linux teils nur hinter einem Flag). Firefox und Safari unterstützen sie nicht. Vor der Nutzung mit 'BluetoothUUID' in window prüfen.
Sicherer Kontext: BluetoothUUID gibt es nur in sicheren Kontexten (HTTPS oder localhost).
Aliase als Zahl: Ein Alias muss als number übergeben werden. Der String "0x2a19" oder "2a19" löst einen TypeError aus.
Großbuchstaben: 128-Bit-UUIDs mit Großbuchstaben gelten als ungültig. Vorher toLowerCase() aufrufen.
Namensformat: Namen müssen exakt dem registrierten snake_case-Format entsprechen ("battery_level", nicht "Battery Level").
Manche Charakteristiken, etwa aus der GATT-Sperrliste, lassen sich zwar in UUIDs umwandeln, der Browser verweigert aber später den Zugriff darauf.

Siehe auch

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