BluetoothRemoteGATTService.getCharacteristic() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTService.prototype.getCharacteristic(characteristic)

Beschreibung

Die Methode getCharacteristic() gehört zu einem BluetoothRemoteGATTService, also zu einem primären Dienst eines verbundenen Bluetooth-Low-Energy-Geräts. Sie sucht innerhalb dieses Dienstes nach der ersten Charakteristik mit der angegebenen UUID und liefert sie als BluetoothRemoteGATTCharacteristic zurück. Über dieses Objekt kann man anschließend Werte lesen (readValue()), schreiben (writeValueWithResponse()) oder Benachrichtigungen abonnieren (startNotifications()).

Die Charakteristik kann als volle 128-Bit-UUID ("00002a37-0000-1000-8000-00805f9b34fb"), als 16- bzw. 32-Bit-Alias (0x2A37) oder als standardisierter GATT-Name ("heart_rate_measurement") angegeben werden. Intern wird der Wert mit BluetoothUUID.getCharacteristic() normalisiert.

Typischer Ablauf: Gerät per navigator.bluetooth.requestDevice() auswählen, mit device.gatt.connect() verbinden, den Dienst über server.getPrimaryService() holen und dann mit getCharacteristic() die gewünschte Charakteristik abrufen. Werden mehrere Charakteristiken mit derselben UUID benötigt, nutzt man stattdessen getCharacteristics().

Parameter

Name	Typ	Default	Beschreibung
$characteristic Pflicht	string \| number		UUID der gesuchten Charakteristik: volle 128-Bit-UUID als String, 16-/32-Bit-Alias als Zahl (z. B. `0x2A19`) oder ein registrierter GATT-Name wie `"battery_level"`.

Rückgabewert

Typ

Promise<BluetoothRemoteGATTCharacteristic>

Beschreibung

Ein Promise, das mit der ersten passenden Charakteristik erfüllt wird. Es wird z. B. mit NotFoundError abgelehnt, wenn keine passende Charakteristik existiert, mit NetworkError, wenn das Gerät nicht (mehr) verbunden ist, mit SecurityError bei gesperrten UUIDs (Blocklist) und mit TypeError bei ungültiger UUID.

Beispiele

Akkustand eines BLE-Geräts auslesen

const button = document.querySelector('#connect');

button.addEventListener('click', async () => {
  try {
    // Benutzergeste erforderlich!
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['battery_service'] }]
    });
    const server = await device.gatt.connect();
    const service = await server.getPrimaryService('battery_service');
    const characteristic = await service.getCharacteristic('battery_level');

    const value = await characteristic.readValue();
    console.log(`Akkustand: ${value.getUint8(0)} %`);
  } catch (error) {
    console.error('Bluetooth-Fehler:', error.name, error.message);
  }
});

Akkustand: 87 %

Herzfrequenz per Benachrichtigung empfangen (16-Bit-Alias)

const startHeartRate = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: [0x180D] }]
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService(0x180D);
  // 0x2A37 = heart_rate_measurement
  const hrm = await service.getCharacteristic(0x2A37);

  hrm.addEventListener('characteristicvaluechanged', (event) => {
    const data = event.target.value;
    const flags = data.getUint8(0);
    // Bit 0 gibt an, ob der Wert 8 oder 16 Bit breit ist
    const bpm = flags & 0x01 ? data.getUint16(1, true) : data.getUint8(1);
    console.log(`Puls: ${bpm} bpm`);
  });

  await hrm.startNotifications();
};

document.querySelector('#hr').addEventListener('click', startHeartRate);

Puls: 72 bpm Puls: 74 bpm

Fehlende Charakteristik sauber behandeln

const getOptionalCharacteristic = async (service, uuid) => {
  try {
    return await service.getCharacteristic(uuid);
  } catch (error) {
    if (error.name === 'NotFoundError') {
      console.warn(`Charakteristik ${uuid} wird nicht unterstützt.`);
      return null;
    }
    throw error; // z. B. NetworkError nach Verbindungsabbruch
  }
};

// Nutzung innerhalb eines Klick-Handlers nach connect():
// const fw = await getOptionalCharacteristic(service, 'firmware_revision_string');

Charakteristik firmware_revision_string wird nicht unterstützt.

// Wichtig · Fallstricke

Kompatibilität: Die Web Bluetooth API ist experimentell und nur in Chromium-Browsern (Chrome, Edge, Opera) verfügbar – auf Linux teils nur hinter einem Flag. Firefox und Safari (inkl. iOS) unterstützen sie nicht. Vorher mit 'bluetooth' in navigator prüfen.
Sicherer Kontext: Nur über HTTPS (bzw. localhost) nutzbar; requestDevice() braucht eine Benutzergeste. In iframes ist die Permissions-Policy bluetooth erforderlich.
Dienst muss freigegeben sein: Der übergeordnete Dienst muss in filters oder optionalServices von requestDevice() angegeben sein, sonst schlägt schon getPrimaryService() mit SecurityError fehl.
Blocklist: Bestimmte sicherheitskritische UUIDs sind gesperrt und führen zu SecurityError.
Verbindungsabbrüche: Nach gattserverdisconnected sind zuvor erhaltene Charakteristik-Objekte ungültig; nach erneutem connect() Dienst und Charakteristik neu abrufen.
Namen wie "battery_level" müssen exakt den registrierten GATT-Bezeichnern entsprechen (Kleinbuchstaben, Unterstriche); Tippfehler ergeben einen TypeError.

Siehe auch

BluetoothRemoteGATTService.getCharacteristics() BluetoothRemoteGATTServer.getPrimaryService() BluetoothRemoteGATTServer.getPrimaryServices() BluetoothUUID.getCharacteristic() BluetoothRemoteGATTServer.connect()