Bluetooth — Schnittstelle · JavaScript-Referenz

Signatur

interface Bluetooth extends EventTarget

Beschreibung

Das Interface Bluetooth ist der zentrale Zugang zur Web Bluetooth API. Eine Instanz legst du nicht selbst an. Der Browser stellt sie als navigator.bluetooth bereit, und zwar nur in einem sicheren Kontext (HTTPS oder localhost). Damit kann eine Webanwendung direkt mit Bluetooth-Low-Energy-Geräten (BLE) sprechen, etwa mit Pulsmessern, Sensoren, Smart-Home-Geräten oder Mikrocontrollern wie ESP32 und micro:bit.

Die wichtigsten Mitglieder sind:

getAvailability(): Liefert ein Promise<boolean>, das angibt, ob das System überhaupt einen Bluetooth-Adapter hat.
requestDevice(options): Öffnet den Geräteauswahl-Dialog des Browsers und liefert ein BluetoothDevice. Du darfst die Methode nur nach einer Nutzeraktion aufrufen, etwa einem Klick.
getDevices(): Liefert Geräte, für die die Seite schon eine Berechtigung hat. In Chrome ist das teils noch hinter einem Flag.
Event availabilitychanged bzw. die Eigenschaft onavailabilitychanged: Wird ausgelöst, wenn ein Adapter hinzukommt, entfernt oder ein- bzw. ausgeschaltet wird.
referringDevice: Das Gerät, das die Seite geöffnet hat (z. B. über Physical Web). Wird kaum genutzt.

Der typische Ablauf sieht so aus: Verfügbarkeit prüfen, per requestDevice() mit Filtern nach Diensten oder Namen ein Gerät wählen lassen, danach über device.gatt.connect() den GATT-Server verbinden und Dienste und Merkmale (Characteristics) lesen, schreiben oder abonnieren.

Parameter

Name	Typ	Default	Beschreibung
$options.filters	Array<BluetoothLEScanFilter>		Parameter von `requestDevice()`. Liste von Filtern mit `services`, `name`, `namePrefix`, `manufacturerData` oder `serviceData`. Ein Gerät wird angezeigt, sobald es auf einen Filter passt.
$options.exclusionFilters	Array<BluetoothLEScanFilter>		Filter für Geräte, die trotz passender `filters` ausgeblendet werden sollen.
$options.optionalServices	Array<string\|number>	[]	Weitere Dienst-UUIDs oder -Namen, auf die du nach dem Verbinden zugreifen willst. Ohne diesen Eintrag ist der Zugriff auf nicht gefilterte Dienste gesperrt.
$options.optionalManufacturerData	Array<number>	[]	Hersteller-Codes, deren Advertisement-Daten verfügbar sein sollen.
$options.acceptAllDevices	boolean	false	Zeigt alle Geräte in der Nähe. Darf nicht zusammen mit `filters` verwendet werden. Du brauchst dann `optionalServices`.

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;
  }
  const verfuegbar = await navigator.bluetooth.getAvailability();
  console.log(verfuegbar ? 'Bluetooth verfügbar' : 'Kein Bluetooth-Adapter');
  return verfuegbar;
};

pruefeBluetooth();

Bluetooth verfügbar

Pulsmesser per Klick verbinden und Herzfrequenz abonnieren

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

button.addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['heart_rate'] }],
      optionalServices: ['battery_service']
    });
    console.log('Gewählt:', device.name);

    const server = await device.gatt.connect();
    const service = await server.getPrimaryService('heart_rate');
    const messung = await service.getCharacteristic('heart_rate_measurement');

    messung.addEventListener('characteristicvaluechanged', (event) => {
      const wert = event.target.value;
      const flags = wert.getUint8(0);
      const puls = flags & 0x1 ? wert.getUint16(1, true) : wert.getUint8(1);
      console.log(`Puls: ${puls} bpm`);
    });
    await messung.startNotifications();
  } catch (err) {
    // NotFoundError, wenn der Nutzer den Dialog abbricht
    console.error(`${err.name}: ${err.message}`);
  }
});

Gewählt: Polar H10 Puls: 72 bpm Puls: 74 bpm

Auf Änderungen der Verfügbarkeit reagieren

const beiAenderung = (event) => {
  console.log('Bluetooth jetzt:', event.value ? 'an' : 'aus');
};

navigator.bluetooth.addEventListener('availabilitychanged', beiAenderung);

// Später wieder abmelden:
// navigator.bluetooth.removeEventListener('availabilitychanged', beiAenderung);

// Alternative über die on-Eigenschaft:
navigator.bluetooth.onavailabilitychanged = beiAenderung;

Bluetooth jetzt: aus

Bereits erlaubte Geräte ohne Dialog erneut verbinden

const wiederVerbinden = async () => {
  if (!navigator.bluetooth.getDevices) return [];
  const geraete = await navigator.bluetooth.getDevices();
  for (const device of geraete) {
    console.log('Bekannt:', device.name, device.id);
  }
  return geraete;
};

wiederVerbinden();

Bekannt: ESP32-Sensor 3f2a...==

// Wichtig · Fallstricke

Browser-Unterstützung: Die API ist experimentell. Sie gibt es nur in Chromium-Browsern (Chrome, Edge, Opera) auf Windows, macOS, ChromeOS, Android und teils Linux. Firefox und Safari (auch auf iOS) unterstützen sie nicht. Prüfe deshalb immer vorher mit 'bluetooth' in navigator.
Nutzeraktion nötig: requestDevice() wirft einen SecurityError, wenn du es ohne Nutzeraktion aufrufst, etwa direkt beim Laden der Seite.
Nur sicherer Kontext: Die API ist nur über HTTPS oder localhost verfügbar. In iframes brauchst du zusätzlich die Permissions-Policy bluetooth.
getAvailability() ist nur ein Hinweis: true heißt nicht, dass Bluetooth eingeschaltet ist oder die Seite eine Berechtigung hat. Manche Browser liefern aus Datenschutzgründen immer true.
Dienste freigeben: Auf Dienste, die weder in filters noch in optionalServices stehen, hast du keinen Zugriff. Du bekommst dann einen SecurityError. Manche UUIDs sperrt Chrome grundsätzlich (Blocklist), z. B. für HID-Geräte.
Abbruch durch den Nutzer: Schließt der Nutzer den Dialog, wird das Promise mit NotFoundError abgelehnt. Fange diesen Fall ab.
Die API unterstützt nur BLE, kein klassisches Bluetooth (BR/EDR). getDevices() ist in einigen Chrome-Versionen noch hinter einem Flag.

Siehe auch

BluetoothUUID Blob BlobEvent BluetoothDevice Client