BluetoothRemoteGATTService.getCharacteristics() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTService.prototype.getCharacteristics(characteristic)

Beschreibung

getCharacteristics() fragt bei einem verbundenen Bluetooth-Low-Energy-Gerät (BLE) alle Characteristics eines primären oder eingebundenen GATT-Dienstes ab. Ohne Argument liefert die Methode alle Characteristics des Dienstes, auf die die Seite zugreifen darf. Übergibt man eine UUID, werden nur die Characteristics mit genau dieser UUID zurückgegeben. Das ist wichtig, weil ein Dienst mehrere Characteristics mit derselben UUID haben kann.

Man nutzt die Methode vor allem, um unbekannte Geräte zu erkunden (Discovery) oder wenn mehrere Instanzen derselben Characteristic existieren. Wenn du genau eine bekannte Characteristic brauchst, ist getCharacteristic() einfacher: Sie liefert nur das erste Ergebnis.

Die UUID kann als vollständige 128-Bit-UUID in Kleinbuchstaben angegeben werden, als 16- oder 32-Bit-Alias (Zahl, z. B. 0x2a37) oder als standardisierter Name aus der GATT-Registry (z. B. 'heart_rate_measurement'). Intern wird sie über BluetoothUUID.getCharacteristic() aufgelöst.

Die GATT-Verbindung muss bestehen (device.gatt.connected === true). Außerdem muss der Dienst bei navigator.bluetooth.requestDevice() in filters oder optionalServices angegeben worden sein, sonst ist der Zugriff gesperrt.

Parameter

Name	Typ	Default	Beschreibung
$characteristic	string \| number		Optionale Characteristic-UUID: eine 128-Bit-UUID als String, ein 16-/32-Bit-Alias als Zahl oder ein GATT-Name wie `'battery_level'`. Ohne Angabe werden alle Characteristics geliefert.

Rückgabewert

Typ

Promise<BluetoothRemoteGATTCharacteristic[]>

Beschreibung

Ein Promise, das mit einem Array von BluetoothRemoteGATTCharacteristic-Objekten erfüllt wird. Wird keine passende Characteristic gefunden, wird es mit einem NotFoundError abgelehnt, nicht mit einem leeren Array.

Beispiele

Alle Characteristics eines Dienstes auflisten

const exploreService = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['battery_service'] }]
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('battery_service');

  const characteristics = await service.getCharacteristics();
  for (const c of characteristics) {
    console.log(c.uuid, {
      read: c.properties.read,
      notify: c.properties.notify,
      write: c.properties.write
    });
  }
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#scan').addEventListener('click', exploreService);

00002a19-0000-1000-8000-00805f9b34fb { read: true, notify: true, write: false }

Nach UUID filtern und alle Werte lesen

const readAllBatteryLevels = async (service) => {
  // Ein Dienst kann dieselbe Characteristic mehrfach enthalten
  const levels = await service.getCharacteristics('battery_level');
  const values = await Promise.all(
    levels.map(async (c) => (await c.readValue()).getUint8(0))
  );
  console.log('Akkustände:', values.map((v) => `${v} %`).join(', '));
  return values;
};

Akkustände: 87 %, 54 %

NotFoundError sauber abfangen

const findWritable = async (service) => {
  try {
    const all = await service.getCharacteristics();
    return all.filter((c) => c.properties.write || c.properties.writeWithoutResponse);
  } catch (err) {
    if (err.name === 'NotFoundError') {
      console.warn('Dienst enthält keine zugänglichen Characteristics.');
      return [];
    }
    if (err.name === 'NetworkError') {
      console.error('GATT-Verbindung getrennt – bitte neu verbinden.');
    }
    throw err;
  }
};

Dienst enthält keine zugänglichen Characteristics.

// Wichtig · Fallstricke

Kompatibilität: Web Bluetooth ist experimentell und läuft nur in Chromium-Browsern (Chrome, Edge, Opera) auf Desktop und Android. Firefox und Safari (auch iOS) unterstützen die API nicht. Prüfe die Unterstützung vorher mit 'bluetooth' in navigator.
Nur sicherer Kontext: Die API funktioniert nur über HTTPS oder localhost. In Cross-Origin-iframes braucht sie die Permissions Policy bluetooth.
Kein leeres Array: Gibt es keine Treffer, wird das Promise mit NotFoundError abgelehnt. Umschließe den Aufruf deshalb immer mit try/catch.
Gesperrte UUIDs: Characteristics auf der GATT-Blocklist fehlen im Ergebnis. Wird eine gesperrte UUID direkt abgefragt, folgt ein SecurityError.
Verbindungsabbruch: Ist das Gerät getrennt, schlägt der Aufruf mit NetworkError fehl. Die Objekte aus einer früheren Verbindung werden nach dem erneuten Verbinden ungültig und müssen neu abgefragt werden.
UUID-Format: 128-Bit-UUIDs müssen kleingeschrieben sein, sonst wird ein TypeError geworfen.

Siehe auch

BluetoothRemoteGATTService.getCharacteristic() BluetoothRemoteGATTCharacteristic BluetoothRemoteGATTService BluetoothRemoteGATTServer.getPrimaryService() Bluetooth.requestDevice() BluetoothUUID BluetoothRemoteGATTServer.getPrimaryServices()