Signatur
interface BluetoothRemoteGATTService extends EventTarget
Beschreibung
BluetoothRemoteGATTService gehört zur Web Bluetooth API und steht für einen einzelnen Dienst (Service) auf dem GATT-Server eines Bluetooth-Low-Energy-Geräts, zum Beispiel Batteriestand (battery_service) oder Herzfrequenz (heart_rate). Du erzeugst solche Objekte nie selbst. Du bekommst sie über BluetoothRemoteGATTServer.getPrimaryService() oder getPrimaryServices(), sobald die Verbindung zum Gerät steht.
Wichtige Eigenschaften (alle schreibgeschützt):
device: das zugehörigeBluetoothDevice.uuid: die UUID des Dienstes als 128-Bit-Zeichenkette, z. B."0000180f-0000-1000-8000-00805f9b34fb".isPrimary:truebei einem primären Dienst,falsebei einem sekundären.
Wichtige Methoden (alle liefern ein Promise):
getCharacteristic(characteristic): gibt eine einzelneBluetoothRemoteGATTCharacteristiczurück.getCharacteristics([characteristic]): gibt alle Characteristics zurück, optional nach UUID gefiltert.getIncludedService(service)/getIncludedServices([service]): geben Dienste zurück, die in diesen Dienst eingebunden sind. In Chromium ist das bisher nicht umgesetzt.
Das Interface erbt von EventTarget. Laut Spezifikation feuert es die Events serviceadded, servicechanged und serviceremoved, in der Praxis unterstützen Browser sie aber kaum. Den typischen Ablauf findest du in den Beispielen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $characteristic | string | number | Parameter von getCharacteristic() und getCharacteristics(): der Name einer Characteristic nach BluetoothUUID (z. B. "battery_level"), eine 16-Bit-Kurz-UUID als Zahl (z. B. 0x2A19) oder eine vollständige 128-Bit-UUID als Zeichenkette. Bei getCharacteristic() ist er Pflicht. |
|
| $service | string | number | Parameter von getIncludedService() und getIncludedServices(): UUID oder Name des eingebundenen Dienstes. |
Rückgabewert
Typ
BluetoothRemoteGATTService
Beschreibung
Das Objekt entsteht nur durch
getPrimaryService() bzw. getPrimaryServices() (dann als Array). Die Methoden liefern Promise<BluetoothRemoteGATTCharacteristic>, Promise<BluetoothRemoteGATTCharacteristic[]> bzw. Promise<BluetoothRemoteGATTService[]>.Beispiele
Batteriestand auslesen
// Muss durch eine Nutzeraktion (z. B. einen Klick) ausgelöst werden
const leseBatterie = async () => {
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: ['battery_service'] }]
});
const server = await device.gatt.connect();
// BluetoothRemoteGATTService holen
const service = await server.getPrimaryService('battery_service');
console.log('Dienst:', service.uuid, 'primär:', service.isPrimary);
const characteristic = await service.getCharacteristic('battery_level');
const value = await characteristic.readValue();
console.log(`Batterie: ${value.getUint8(0)} %`);
};
document.querySelector('#btn').addEventListener('click', leseBatterie);Dienst: 0000180f-0000-1000-8000-00805f9b34fb primär: true
Batterie: 87 %
Alle Characteristics eines Dienstes auflisten
const listeCharacteristics = async (server) => {
const service = await server.getPrimaryService('heart_rate');
const characteristics = await service.getCharacteristics();
for (const c of characteristics) {
const props = Object.entries({
read: c.properties.read,
write: c.properties.write,
notify: c.properties.notify
})
.filter(([, aktiv]) => aktiv)
.map(([name]) => name);
console.log(c.uuid, props.join(', '));
}
};00002a37-0000-1000-8000-00805f9b34fb notify
00002a38-0000-1000-8000-00805f9b34fb read
Herzfrequenz-Benachrichtigungen abonnieren
const starteHerzfrequenz = async () => {
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: ['heart_rate'] }]
});
const server = await device.gatt.connect();
const service = await server.getPrimaryService('heart_rate');
const messung = await service.getCharacteristic(0x2A37);
messung.addEventListener('characteristicvaluechanged', (event) => {
const data = event.target.value;
const flags = data.getUint8(0);
// Bit 0: Wert ist 16 Bit statt 8 Bit lang
const bpm = flags & 0x1 ? data.getUint16(1, true) : data.getUint8(1);
console.log(`Puls: ${bpm} bpm`);
});
await messung.startNotifications();
// Verbindungsabbruch behandeln
device.addEventListener('gattserverdisconnected', () => {
console.log('Verbindung getrennt');
});
};Puls: 72 bpm
Puls: 74 bpm
Fehlerbehandlung bei fehlendem Dienst
const holeDienst = async (server, uuid) => {
try {
return await server.getPrimaryService(uuid);
} catch (err) {
if (err.name === 'NotFoundError') {
console.warn(`Dienst ${uuid} nicht vorhanden`);
} else if (err.name === 'SecurityError') {
console.warn('Dienst nicht in optionalServices angegeben oder gesperrt');
} else if (err.name === 'NetworkError') {
console.warn('Gerät nicht mehr verbunden');
}
return null;
}
};Dienst 0000fff0-0000-1000-8000-00805f9b34fb nicht vorhanden
// Wichtig · Fallstricke
- Browser-Unterstützung: Die API ist experimentell. Sie läuft nur in Chromium-Browsern (Chrome, Edge, Opera, Chrome für Android). Firefox und Safari unterstützen sie nicht, unter Linux ist sie teils nur per Flag nutzbar. Prüfe sie vorher mit
'bluetooth' in navigator. - Sichere Umgebung: Die API funktioniert nur über HTTPS bzw.
localhost.requestDevice()braucht eine Nutzeraktion, etwa einen Klick. - optionalServices: Du erreichst nur Dienste, die in
filtersoderoptionalServicesvonrequestDevice()stehen. Fehlt ein Dienst dort, gibt es einenSecurityError. - Sperrliste: Manche UUIDs, etwa für Firmware-Updates oder HID, blockiert der Browser aus Sicherheitsgründen. Der Zugriff darauf endet ebenfalls mit einem
SecurityError. - Verbindung: Das Service-Objekt wird nach einer Trennung ungültig. Weitere Aufrufe werfen einen
NetworkError. Hol nach dem erneuten Verbinden (device.gatt.connect()) den Dienst noch einmal. getIncludedService(s)()und die Service-Events sind in Chromium bisher nicht umgesetzt.- Die UUIDs in
uuidsind immer klein geschriebene 128-Bit-Zeichenketten. Zum Vergleichen kannst du mitBluetoothUUID.getService()normalisieren.