BluetoothRemoteGATTServer.getPrimaryService() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTServer.prototype.getPrimaryService(bluetoothServiceUUID)

Beschreibung

Mit getPrimaryService() greifst du auf einen bestimmten primären GATT-Service eines Bluetooth-Low-Energy-Geräts zu, z. B. auf den Batterie-Service ('battery_service') oder den Herzfrequenz-Service ('heart_rate'). Der zurückgegebene BluetoothRemoteGATTService ist der Einstiegspunkt, um danach mit getCharacteristic() Werte zu lesen, zu schreiben oder Benachrichtigungen zu abonnieren.

Die Methode kann nur aufgerufen werden, wenn der GATT-Server verbunden ist, also nach device.gatt.connect(). Außerdem muss die Service-UUID beim Aufruf von navigator.bluetooth.requestDevice() entweder in einem filters-Eintrag unter services oder in optionalServices angegeben worden sein. Sonst lehnt der Browser den Zugriff mit einem SecurityError ab.

Als UUID akzeptiert die Methode einen vollständigen 128-Bit-UUID-String (Kleinbuchstaben), einen 16- oder 32-Bit-Alias als Zahl (z. B. 0x180F) oder einen standardisierten GATT-Namen wie 'battery_service'. Bietet das Gerät den Service mehrfach an, wird nur die erste Instanz zurückgegeben. Alle Instanzen erhältst du mit getPrimaryServices().

Parameter

Name	Typ	Default	Beschreibung
$bluetoothServiceUUID Pflicht	string \| number		UUID des gewünschten Services: 128-Bit-UUID-String (z. B. `'0000180f-0000-1000-8000-00805f9b34fb'`), 16-/32-Bit-Alias als Zahl (z. B. `0x180F`) oder ein registrierter Name (z. B. `'battery_service'`). Zahlen werden intern über `BluetoothUUID.getService()` umgewandelt.

Rückgabewert

Typ

Promise<BluetoothRemoteGATTService>

Beschreibung

Ein Promise, das mit dem ersten passenden primären BluetoothRemoteGATTService erfüllt wird. Es wird abgelehnt mit NotFoundError (Service nicht vorhanden), NetworkError (Server nicht verbunden), SecurityError (UUID nicht freigegeben oder auf der Sperrliste) oder TypeError (ungültige UUID).

Beispiele

Batteriestand eines BLE-Geräts auslesen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
const button = document.querySelector('#connect');

button.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 value = await characteristic.readValue();
    console.log(`Batterie: ${value.getUint8(0)} %`);
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Batterie: 87 %

Herzfrequenz per Benachrichtigung empfangen (optionalServices)

const startHeartRate = async () => {
  const device = await navigator.bluetooth.requestDevice({
    acceptAllDevices: true,
    optionalServices: ['heart_rate'] // ohne Freigabe: SecurityError
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('heart_rate');
  const hr = await service.getCharacteristic('heart_rate_measurement');

  hr.addEventListener('characteristicvaluechanged', (event) => {
    const data = event.target.value;
    const flags = data.getUint8(0);
    // Bit 0: Wert als 16 Bit statt 8 Bit
    const bpm = flags & 0x1 ? data.getUint16(1, true) : data.getUint8(1);
    console.log(`Puls: ${bpm} bpm`);
  });
  await hr.startNotifications();
};

document.querySelector('#hr').addEventListener('click', startHeartRate);

Puls: 72 bpm Puls: 74 bpm

Eigener 128-Bit-Service mit Fehlerbehandlung

const SERVICE_UUID = '6e400001-b5a3-f393-e0a9-e50e24dcca9e'; // Nordic UART

const getUartService = async (device) => {
  const server = device.gatt.connected
    ? device.gatt
    : await device.gatt.connect();
  try {
    return await server.getPrimaryService(SERVICE_UUID);
  } catch (err) {
    if (err.name === 'NotFoundError') {
      console.warn('Gerät bietet den UART-Service nicht an.');
      return null;
    }
    throw err;
  }
};

Gerät bietet den UART-Service nicht an.

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Web Bluetooth API ist experimentell und nur in Chromium-Browsern verfügbar (Chrome, Edge, Opera; unter Linux teils nur mit Flag). Firefox und Safari unterstützen sie nicht. Prüfe das vorher mit 'bluetooth' in navigator.
Nur in sicherem Kontext: Die API funktioniert nur über HTTPS oder localhost. requestDevice() braucht eine Nutzeraktion. In Cross-Origin-iframes ist sie nur mit Permissions-Policy bluetooth erlaubt.
Service-Freigabe: Jede UUID, die du später abfragst, muss bei requestDevice() in filters[].services oder optionalServices stehen. Sonst gibt es einen SecurityError. Manche Services (z. B. HID) stehen auf einer Sperrliste und sind nie zugänglich.
Verbindung: Ohne aktive Verbindung schlägt der Aufruf mit NetworkError fehl. Verbindungen können jederzeit abbrechen. Behandle deshalb das Event gattserverdisconnected und hole den Service nach dem erneuten Verbinden neu, denn alte Service-Objekte werden ungültig.
Eigene 128-Bit-UUIDs müssen in Kleinbuchstaben angegeben werden, sonst gibt es einen TypeError.

Siehe auch

BluetoothRemoteGATTServer.getPrimaryServices() BluetoothRemoteGATTServer.disconnect() BluetoothRemoteGATTServer.connect() BluetoothRemoteGATTService.getCharacteristic() BluetoothRemoteGATTService.getCharacteristics()