BluetoothRemoteGATTCharacteristic.uuid — Eigenschaft · JavaScript-Referenz

Signatur

BluetoothRemoteGATTCharacteristic.uuid

Beschreibung

Die Eigenschaft uuid eines BluetoothRemoteGATTCharacteristic-Objekts gibt an, um welche Charakteristik es sich handelt. Standardisierte Charakteristiken der Bluetooth SIG haben 16-Bit-Kurzkennungen wie 0x2A37 (Heart Rate Measurement). Diese werden in die Basis-UUID 0000xxxx-0000-1000-8000-00805f9b34fb eingesetzt. Herstellerspezifische Charakteristiken haben eigene 128-Bit-UUIDs.

Sinnvoll ist die Eigenschaft vor allem, wenn du mit service.getCharacteristics() alle Charakteristiken eines Dienstes abrufst und danach entscheiden musst, wie ein Wert gelesen oder dargestellt wird. Auch beim Protokollieren und Debuggen und bei der Zuordnung in einer gemeinsamen Ereignisbehandlung für characteristicvaluechanged hilft sie.

Der Wert ist immer die kanonische, kleingeschriebene 128-Bit-Form mit Bindestrichen. Wenn du ihn mit Kurzkennungen oder Namen vergleichen willst, wandelst du diese vorher mit BluetoothUUID.getCharacteristic() oder BluetoothUUID.canonicalUUID() in dieselbe Form um.

Rückgabewert

Typ

string

Beschreibung

Die 128-Bit-UUID der Charakteristik in kanonischer, kleingeschriebener Schreibweise (36 Zeichen mit Bindestrichen). Die Eigenschaft ist schreibgeschützt.

Beispiele

UUID der Herzfrequenz-Charakteristik ausgeben

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
document.querySelector('#verbinden').addEventListener('click', 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 characteristic = await service.getCharacteristic('heart_rate_measurement');

  console.log(characteristic.uuid);
});

00002a37-0000-1000-8000-00805f9b34fb

Alle Charakteristiken eines Dienstes auflisten

const listeCharakteristiken = async (service) => {
  const characteristics = await service.getCharacteristics();
  for (const c of characteristics) {
    const rechte = Object.entries({
      lesen: c.properties.read,
      schreiben: c.properties.write,
      benachrichtigen: c.properties.notify
    }).filter(([, v]) => v).map(([k]) => k).join(', ');
    console.log(`${c.uuid} → ${rechte || 'keine'}`);
  }
};

00002a37-0000-1000-8000-00805f9b34fb → benachrichtigen 00002a38-0000-1000-8000-00805f9b34fb → lesen

Gemeinsamer Event-Handler mit UUID-Zuordnung

const HR_MEASUREMENT = BluetoothUUID.getCharacteristic('heart_rate_measurement');
const BATTERY_LEVEL = BluetoothUUID.getCharacteristic('battery_level');

const onValueChanged = (event) => {
  const { uuid, value } = event.target;
  switch (uuid) {
    case HR_MEASUREMENT: {
      const flags = value.getUint8(0);
      const bpm = flags & 0x1 ? value.getUint16(1, true) : value.getUint8(1);
      console.log(`Puls: ${bpm} bpm`);
      break;
    }
    case BATTERY_LEVEL:
      console.log(`Akku: ${value.getUint8(0)} %`);
      break;
    default:
      console.log('Unbekannte Charakteristik:', uuid);
  }
};

// characteristic.addEventListener('characteristicvaluechanged', onValueChanged);
// await characteristic.startNotifications();

Puls: 72 bpm

// Wichtig · Fallstricke

Vergleiche immer in kanonischer Form: c.uuid === 0x2a37 oder c.uuid === '2A37' ergibt false. Wandle Vergleichswerte zuerst mit BluetoothUUID.canonicalUUID(0x2a37) oder BluetoothUUID.getCharacteristic('heart_rate_measurement') um.
Herstellerspezifische UUIDs in Großbuchstaben aus Datenblättern solltest du vor dem Vergleich mit toLowerCase() normalisieren.
Die UUID sagt nur aus, welche Charakteristik vorliegt. Welche Operationen erlaubt sind, steht in characteristic.properties.
Charakteristiken auf der Sperrliste (GATT Blocklist) werden gar nicht erst geliefert. Nicht vorher angemeldete Dienste musst du in optionalServices angeben.
Kompatibilität: Web Bluetooth ist experimentell. Es läuft nur in Chromium-Browsern (Chrome, Edge, Opera), nicht in Firefox und Safari/iOS. Nötig sind ein sicherer Kontext (HTTPS) und eine Nutzeraktion für requestDevice().

Siehe auch

BluetoothRemoteGATTCharacteristic.value BluetoothRemoteGATTCharacteristic.service BluetoothRemoteGATTCharacteristic.properties BluetoothRemoteGATTDescriptor.uuid BluetoothRemoteGATTService.uuid