Signatur
Beschreibung
Über BluetoothDevice.gatt erreicht man den GATT-Server (Generic Attribute Profile) eines Bluetooth-Low-Energy-Geräts. Er ist der Einstiegspunkt für jede Datenübertragung: Mit gatt.connect() baust du die Verbindung auf, mit getPrimaryService() greifst du auf Dienste zu und über deren Charakteristiken liest oder schreibst du Werte, oder du abonnierst Benachrichtigungen.
Ein BluetoothDevice bekommst du normalerweise über navigator.bluetooth.requestDevice(). Diese Methode darf nur nach einer Nutzeraktion (z. B. einem Klick) aufgerufen werden. Die Eigenschaft gatt gibt immer dasselbe Serverobjekt zurück. Ob gerade eine Verbindung besteht, zeigt gatt.connected.
Die Eigenschaft ist null, wenn die Seite keinen GATT-Zugriff auf das Gerät hat, etwa weil das Gerät kein GATT unterstützt oder die Berechtigung fehlt. Prüfe den Wert deshalb vor der Nutzung. Auf Dienste kannst du nur zugreifen, wenn du sie bei requestDevice() in filters oder optionalServices angegeben hast.
Rückgabewert
null, wenn kein GATT-Zugriff möglich ist.Beispiele
Gerät auswählen und mit dem GATT-Server verbinden
const button = document.querySelector('#connect');
button.addEventListener('click', async () => {
try {
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: ['battery_service'] }]
});
if (!device.gatt) {
console.warn('Kein GATT-Zugriff auf dieses Gerät.');
return;
}
const server = await device.gatt.connect();
console.log(`Verbunden mit ${device.name}:`, server.connected);
} catch (err) {
console.error('Verbindung fehlgeschlagen:', err.name, err.message);
}
});Batteriestand über den GATT-Server lesen
const readBatteryLevel = async (device) => {
const server = device.gatt.connected
? device.gatt
: await device.gatt.connect();
const service = await server.getPrimaryService('battery_service');
const characteristic = await service.getCharacteristic('battery_level');
const value = await characteristic.readValue(); // DataView
return value.getUint8(0);
};
document.querySelector('#battery').addEventListener('click', async () => {
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: ['battery_service'] }]
});
const level = await readBatteryLevel(device);
console.log(`Batterie: ${level} %`);
});Verbindungsabbruch erkennen und sauber trennen
const setupDevice = async (device) => {
device.addEventListener('gattserverdisconnected', () => {
console.log(`${device.name} wurde getrennt.`);
});
await device.gatt.connect();
console.log('Verbunden:', device.gatt.connected);
// Später, z. B. beim Verlassen der Ansicht:
device.gatt.disconnect();
console.log('Verbunden:', device.gatt.connected);
};// Wichtig · Fallstricke
- Browserunterstützung: Die Web Bluetooth API gibt es nur in Chromium-Browsern (Chrome, Edge, Opera) unter Windows, macOS, ChromeOS und Android. Unter Linux muss sie teilweise erst über ein Flag aktiviert werden. Firefox und Safari unterstützen sie nicht. Prüfe vorher mit
'bluetooth' in navigator, ob sie verfügbar ist. - Nur in sicherem Kontext: Die API funktioniert nur über HTTPS oder
localhost.requestDevice()braucht eine Nutzeraktion. In iframes muss sie per Permissions Policy (bluetooth) freigegeben sein. null-Wert:gattkannnullsein. Ein ungeprüfter Aufruf vondevice.gatt.connect()wirft dann einenTypeError.- Dienste freigeben: Dienste, die nicht in
filtersoderoptionalServicesstehen, lösen beigetPrimaryService()einenSecurityErroraus. Bestimmte Dienste stehen außerdem auf einer Sperrliste (Blocklist). - Instabile Verbindungen: BLE-Verbindungen brechen oft ab, zum Beispiel wegen Reichweite oder Energiesparmodus. Reagiere auf das Ereignis
gattserverdisconnectedund verbinde bei Bedarf neu. Vorher geholte Dienst- und Charakteristik-Objekte sind nach einer Trennung ungültig.