BluetoothDevice — Schnittstelle · JavaScript-Referenz

Signatur

interface BluetoothDevice extends EventTarget

Beschreibung

Ein BluetoothDevice steht für ein Bluetooth-Low-Energy-Gerät (BLE), das der Nutzer der Webseite freigegeben hat. Man erzeugt es nicht selbst. Man bekommt es, wenn navigator.bluetooth.requestDevice() erfolgreich ist. Diese Methode öffnet einen Auswahldialog des Browsers. Alternativ liefert navigator.bluetooth.getDevices() die Geräte, die schon früher freigegeben wurden.

Wichtige Eigenschaften und Methoden:

id: eine eindeutige, feste Kennung (string). Sie ist nicht die MAC-Adresse, sondern wird für jeden Ursprung (Origin) eigens erzeugt.
name: der angezeigte Gerätename (string | undefined).
gatt: ein BluetoothRemoteGATTServer, über den man die Verbindung aufbaut (connect()) und auf Services und Characteristics zugreift.
watchAdvertisements() / forget(): startet das Empfangen von Advertisement-Paketen bzw. entzieht die Freigabe für das Gerät.
Events: gattserverdisconnected (Verbindung getrennt), advertisementreceived, außerdem Events von Characteristics und Services, die bis zum Gerät weitergereicht werden (Bubbling).

Typische Einsatzfälle sind Fitness-Sensoren (z. B. Herzfrequenz), Mikrocontroller, smarte Lampen oder Messgeräte, die man direkt aus dem Browser steuert oder ausliest, ohne eine native App zu installieren.

Parameter

Name	Typ	Default	Beschreibung
$id Pflicht	string		Nur lesbar. Eindeutige Kennung des Geräts, fest pro Ursprung (Origin).
$name	string \| undefined		Nur lesbar. Menschenlesbarer Name des Geräts, falls bekannt.
$gatt	BluetoothRemoteGATTServer \| null		Nur lesbar. Verweis auf den GATT-Server des Geräts. `null`, wenn kein Zugriff erlaubt ist.
$watchingAdvertisements	boolean	false	Nur lesbar. Gibt an, ob gerade Advertisements empfangen werden (Flag nötig).
$ongattserverdisconnected	function \| null	null	Event-Handler, der aufgerufen wird, wenn die GATT-Verbindung abbricht.

Rückgabewert

Typ

BluetoothDevice

Beschreibung

Eine Instanz bekommt man vom Promise, das navigator.bluetooth.requestDevice() zurückgibt, oder als Element des Arrays von getDevices().

Beispiele

Gerät anfordern und Akkustand auslesen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
document.querySelector('#verbinden').addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: ['battery_service'] }]
    });
    console.log(`Gerät: ${device.name ?? 'unbekannt'} (${device.id})`);

    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 (err) {
    console.error('Bluetooth-Fehler:', err.name, err.message);
  }
});

Gerät: Mi Band 4 (Xk2f9...==) Akkustand: 87 %

Verbindungsabbruch erkennen und neu verbinden

const connectWithRetry = async (device, attempts = 3) => {
  for (let i = 1; i <= attempts; i++) {
    try {
      await device.gatt.connect();
      console.log('Verbunden mit', device.name);
      return;
    } catch {
      console.warn(`Versuch ${i} fehlgeschlagen`);
      await new Promise((r) => setTimeout(r, 1000 * i));
    }
  }
  throw new Error('Verbindung nicht möglich');
};

const onDisconnected = (event) => {
  const device = event.target;
  console.log(`${device.name} getrennt – verbinde neu …`);
  connectWithRetry(device);
};

const device = await navigator.bluetooth.requestDevice({ acceptAllDevices: true });
device.addEventListener('gattserverdisconnected', onDisconnected);
await connectWithRetry(device);

// Später: Listener entfernen und bewusst trennen
device.removeEventListener('gattserverdisconnected', onDisconnected);
device.gatt.disconnect();

Verbunden mit Heart Rate Sensor

Bereits freigegebene Geräte wiederverwenden und vergessen

if ('getDevices' in navigator.bluetooth) {
  const devices = await navigator.bluetooth.getDevices();
  for (const device of devices) {
    console.log('Bekannt:', device.name, device.id);
  }
  // Freigabe für das erste Gerät zurückziehen
  if (devices.length > 0) {
    await devices[0].forget();
    console.log('Freigabe entfernt');
  }
}

Bekannt: LED-Controller Xk2f9...== Freigabe entfernt

// Wichtig · Fallstricke

Browser-Unterstützung: Die Web Bluetooth API ist experimentell. Sie läuft nur in Chromium-Browsern (Chrome, Edge, Opera) auf Desktop und Android. Firefox und Safari unterstützen sie nicht, auch nicht auf iOS. Prüfe deshalb immer vorher mit 'bluetooth' in navigator. Zusätzlich lohnt sich await navigator.bluetooth.getAvailability().

Sicherer Kontext: Die API gibt es nur über HTTPS oder localhost. requestDevice() braucht eine Nutzeraktion (transient user activation), sonst gibt es einen SecurityError.
Services vorher angeben: Du kannst nur auf Services zugreifen, die in filters oder optionalServices stehen. Sonst gibt es einen SecurityError, obwohl die Verbindung steht.
Die id ist keine MAC-Adresse. Aus Datenschutzgründen gilt sie nur für den jeweiligen Ursprung (Origin) und eignet sich nicht, um Geräte über Ursprünge hinweg zu erkennen.
getDevices(), watchAdvertisements() und forget() sind teils nur hinter dem Flag chrome://flags/#enable-web-bluetooth-new-permissions-backend oder ab neueren Chrome-Versionen verfügbar.
Nur Bluetooth Low Energy (GATT) wird unterstützt, klassisches Bluetooth (z. B. Audio, SPP) nicht. Dafür gibt es teilweise die Web Serial API.
Verbindungen können jederzeit abbrechen, etwa wenn das Gerät außer Reichweite ist oder in den Energiesparmodus geht. Reagiere deshalb immer auf gattserverdisconnected.
Die Blockliste des Browsers sperrt bestimmte UUIDs, z. B. für HID-Geräte oder Firmware-Updates.

Siehe auch

Bluetooth BluetoothUUID GPUDevice USBDevice GPUTextureView