Navigator.bluetooth — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.bluetooth

Beschreibung

Über navigator.bluetooth erreicht man die Web Bluetooth API. Damit kann eine Webseite mit Bluetooth-Low-Energy-Geräten (BLE) sprechen, etwa mit Herzfrequenzsensoren, Fitness-Trackern, smarten Glühbirnen oder Mikrocontrollern wie ESP32 und micro:bit. Die Eigenschaft gibt ein Bluetooth-Objekt zurück. Es erbt von EventTarget und stellt unter anderem requestDevice(), getAvailability() und (je nach Browser) getDevices() bereit.

Der typische Ablauf sieht so aus: Mit navigator.bluetooth.requestDevice() öffnet sich ein Auswahldialog des Browsers. Danach verbindet man sich über device.gatt.connect() mit dem GATT-Server des Geräts, holt einen Primary Service und dessen Characteristics und kann dann Werte lesen, schreiben oder Benachrichtigungen abonnieren (startNotifications()).

Die API gibt es nur in einem sicheren Kontext (HTTPS oder localhost). requestDevice() muss außerdem durch eine Benutzeraktion ausgelöst werden, zum Beispiel einen Klick. Weil sie nicht in allen Browsern vorhanden ist, sollte man vor der Nutzung immer mit 'bluetooth' in navigator prüfen, ob sie unterstützt wird.

Rückgabewert

Typ

Bluetooth | undefined

Beschreibung

Ein Bluetooth-Objekt für das aktuelle Dokument. In Browsern ohne Unterstützung oder außerhalb eines sicheren Kontexts gibt es die Eigenschaft nicht, der Zugriff liefert dann undefined.

Beispiele

Unterstützung und Verfügbarkeit prüfen

const pruefeBluetooth = async () => {
  if (!('bluetooth' in navigator)) {
    console.log('Web Bluetooth wird nicht unterstützt.');
    return false;
  }
  // Gibt es einen Bluetooth-Adapter?
  const verfuegbar = await navigator.bluetooth.getAvailability();
  console.log(verfuegbar ? 'Bluetooth verfügbar' : 'Kein Bluetooth-Adapter');
  return verfuegbar;
};

pruefeBluetooth();

Bluetooth verfügbar

Akkustand eines BLE-Geräts lesen (nach Klick)

document.querySelector('#verbinden').addEventListener('click', async () => {
  try {
    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 wert = await characteristic.readValue();
    console.log(`${device.name}: Akku ${wert.getUint8(0)} %`);
  } catch (err) {
    console.error('Fehler:', err.name, err.message);
  }
});

Mi Band 4: Akku 87 %

Herzfrequenz per Benachrichtigung empfangen

const startePuls = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['heart_rate'] }]
  });
  device.addEventListener('gattserverdisconnected', () =>
    console.log('Verbindung getrennt')
  );
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('heart_rate');
  const ch = await service.getCharacteristic('heart_rate_measurement');
  ch.addEventListener('characteristicvaluechanged', (e) => {
    const daten = e.target.value;
    const flags = daten.getUint8(0);
    // Bit 0 gibt an, ob der Wert 8 oder 16 Bit breit ist
    const puls = flags & 0x1 ? daten.getUint16(1, true) : daten.getUint8(1);
    console.log(`Puls: ${puls} bpm`);
  });
  await ch.startNotifications();
};

document.querySelector('#puls').addEventListener('click', startePuls);

Puls: 72 bpm Puls: 74 bpm

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell. Unterstützt wird sie nur von Chromium-basierten Browsern (Chrome, Edge, Opera) auf Desktop und Android. Firefox und Safari (auch alle Browser unter iOS) bieten sie nicht an. Unter Linux ist sie teilweise nur über ein Flag aktivierbar.
Nur sicherer Kontext: Über HTTP (außer localhost) ist navigator.bluetooth undefined.
Benutzeraktion nötig: Ruft man requestDevice() ohne vorherige Benutzeraktion auf, etwa direkt beim Laden der Seite, wird das Promise mit einem SecurityError abgelehnt. Schließt der Nutzer den Auswahldialog, entsteht ein NotFoundError.
Filter angeben: requestDevice() braucht entweder filters oder acceptAllDevices: true. Services, die nicht im Filter stehen, müssen zusätzlich in optionalServices angegeben werden. Sonst schlägt der Zugriff mit einem SecurityError fehl.
Einschränkungen: In iframes ist die API nur mit der Permissions Policy bluetooth erlaubt. Bestimmte UUIDs (etwa für HID-Geräte) sind aus Sicherheitsgründen gesperrt. Unterstützt wird nur BLE, klassisches Bluetooth (z. B. Audio) nicht.
Die Verbindung kann jederzeit abbrechen. Deshalb sollte man gattserverdisconnected behandeln und bei Bedarf neu verbinden.

Siehe auch

Bluetooth Navigator Navigator.usb Navigator.platform Navigator.buildID