BluetoothRemoteGATTCharacteristic.stopNotifications() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTCharacteristic.prototype.stopNotifications()

Beschreibung

stopNotifications() ist das Gegenstück zu startNotifications(). Die Methode setzt den Client Characteristic Configuration Descriptor (CCCD) des Bluetooth-Low-Energy-Geräts zurück. Danach schickt das Gerät keine Wertänderungen mehr, und das Event characteristicvaluechanged wird für diese Characteristic nicht mehr ausgelöst.

Das zurückgegebene Promise erfüllt sich mit derselben BluetoothRemoteGATTCharacteristic-Instanz, sobald keine aktive Benachrichtigung mehr besteht. Deshalb kannst du den Aufruf gut verketten, zum Beispiel um anschließend Event-Listener zu entfernen oder die GATT-Verbindung zu trennen.

Typische Anwendungsfälle sind das Beenden einer Live-Messung (Herzfrequenz, Sensorwerte), das Aufräumen, wenn eine Komponente oder Seite verlassen wird, und das Energiesparen beim Peripheriegerät: Jede aktive Notification hält das Funkmodul des Geräts beschäftigt.

Rückgabewert

Typ

Promise<BluetoothRemoteGATTCharacteristic>

Beschreibung

Ein Promise, das sich mit derselben Characteristic-Instanz erfüllt, sobald die Benachrichtigungen beendet sind. Es wird abgelehnt, z. B. mit NetworkError, wenn das Gerät nicht verbunden ist, mit InvalidStateError oder mit NotSupportedError, wenn die Characteristic weder notify noch indicate unterstützt.

Beispiele

Herzfrequenz-Messung starten und wieder stoppen

const handleHeartRate = (event) => {
  const value = event.target.value; // DataView
  const flags = value.getUint8(0);
  const bpm = flags & 0x1 ? value.getUint16(1, true) : value.getUint8(1);
  console.log(`Puls: ${bpm} bpm`);
};

let characteristic;

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

  characteristic.addEventListener('characteristicvaluechanged', handleHeartRate);
  await characteristic.startNotifications();
  console.log('Benachrichtigungen aktiv');
});

document.querySelector('#stop').addEventListener('click', async () => {
  if (!characteristic) return;
  await characteristic.stopNotifications();
  characteristic.removeEventListener('characteristicvaluechanged', handleHeartRate);
  console.log('Benachrichtigungen beendet');
});

Benachrichtigungen aktiv Puls: 72 bpm Puls: 74 bpm Benachrichtigungen beendet

Sauberes Aufräumen mit Fehlerbehandlung und Trennen der Verbindung

const cleanup = async (characteristic, handler) => {
  const device = characteristic.service.device;
  try {
    if (device.gatt.connected) {
      const c = await characteristic.stopNotifications();
      console.log('Gestoppt für UUID:', c.uuid);
    }
  } catch (err) {
    console.warn('stopNotifications fehlgeschlagen:', err.name, err.message);
  } finally {
    characteristic.removeEventListener('characteristicvaluechanged', handler);
    if (device.gatt.connected) device.gatt.disconnect();
  }
};

// z. B. beim Verlassen der Seite
window.addEventListener('pagehide', () => cleanup(characteristic, handleHeartRate));

Gestoppt für UUID: 00002a37-0000-1000-8000-00805f9b34fb

Messung nach fester Dauer automatisch beenden

const recordFor = async (characteristic, ms) => {
  const samples = [];
  const onValue = (e) => samples.push(e.target.value.getUint8(1));

  characteristic.addEventListener('characteristicvaluechanged', onValue);
  await characteristic.startNotifications();

  await new Promise((resolve) => setTimeout(resolve, ms));

  await characteristic.stopNotifications();
  characteristic.removeEventListener('characteristicvaluechanged', onValue);
  return samples;
};

const werte = await recordFor(characteristic, 5000);
console.log(`${werte.length} Messwerte`, werte);

5 Messwerte [71, 72, 72, 73, 74]

// Wichtig · Fallstricke

Browser-Kompatibilität: Web Bluetooth ist experimentell. Es wird nur in Chromium-Browsern (Chrome, Edge, Opera) unterstützt. Firefox und Safari bieten die API nicht an. Auf Linux kann ein Flag nötig sein. Prüfe die Unterstützung vorher mit 'bluetooth' in navigator.
Sicherer Kontext: Die API steht nur über HTTPS oder localhost zur Verfügung. In Cross-Origin-iframes ist sie außerdem nur mit passender Permissions Policy (bluetooth) nutzbar.
Listener nicht vergessen: stopNotifications() entfernt keine Event-Listener. Rufe zusätzlich removeEventListener() auf. Sonst reagieren die alten Handler doppelt, wenn du später erneut startNotifications() aufrufst.
Verbindung prüfen: Ist das Gerät bereits getrennt (device.gatt.connected === false), wird das Promise mit NetworkError abgelehnt. Beim Trennen der Verbindung enden die Benachrichtigungen ohnehin.
Nachzügler: Wertänderungen, die schon unterwegs waren, können noch kurz nach dem Aufruf eintreffen, bevor sich das Promise erfüllt.
Mehrere GATT-Operationen gleichzeitig können zu NetworkError: GATT operation already in progress führen. Führe die Aufrufe deshalb nacheinander mit await aus.

Siehe auch

BluetoothRemoteGATTCharacteristic.startNotifications() BluetoothRemoteGATTCharacteristic BluetoothRemoteGATTCharacteristic.readValue() BluetoothRemoteGATTServer.disconnect() Bluetooth.requestDevice()