BluetoothRemoteGATTDescriptor.characteristic — Eigenschaft · JavaScript-Referenz

Signatur

BluetoothRemoteGATTDescriptor.characteristic

Beschreibung

Die Eigenschaft characteristic eines BluetoothRemoteGATTDescriptor verweist zurück auf die GATT-Charakteristik, zu der der Deskriptor gehört. In der GATT-Hierarchie (Gerät → Server → Dienst → Charakteristik → Deskriptor) kommt man darüber eine Ebene nach oben.

Nützlich ist das vor allem, wenn ein Deskriptor-Objekt an eine Hilfsfunktion übergeben wird und dort Kontext gebraucht wird, etwa die UUID der Charakteristik, ihre Eigenschaften (properties) oder der Weg weiter hinauf über characteristic.service bis zum Gerät. So muss man die Charakteristik nicht zusätzlich als Parameter mitgeben.

Der Wert wird beim Anlegen des Deskriptors festgelegt und ändert sich danach nicht. Die Eigenschaft ist schreibgeschützt; eine Zuweisung wird still ignoriert (im Strict Mode gibt es einen TypeError).

Rückgabewert

Typ

BluetoothRemoteGATTCharacteristic

Beschreibung

Die GATT-Charakteristik, zu der der Deskriptor gehört. Es ist dasselbe Objekt, über dessen getDescriptor() bzw. getDescriptors() der Deskriptor abgerufen wurde.

Beispiele

Vom Deskriptor zur Charakteristik zurück

// Muss aus einer Nutzeraktion heraus laufen, z. B. einem Klick
const button = document.querySelector('#verbinden');

button.addEventListener('click', 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 characteristic = await service.getCharacteristic('heart_rate_measurement');

  // Client Characteristic Configuration Descriptor (0x2902)
  const descriptor = await characteristic.getDescriptor(
    'gatt.client_characteristic_configuration'
  );

  console.log(descriptor.characteristic === characteristic);
  console.log(descriptor.characteristic.uuid);
});

true 00002a37-0000-1000-8000-00805f9b34fb

Hilfsfunktion mit Kontext-Ausgabe für alle Deskriptoren

// Gibt einen Deskriptor samt Charakteristik, Dienst und Gerät aus
const beschreibeDeskriptor = async (descriptor) => {
  const char = descriptor.characteristic;
  const service = char.service;
  const device = service.device;

  const value = await descriptor.readValue();
  const bytes = [...new Uint8Array(value.buffer)]
    .map((b) => b.toString(16).padStart(2, '0'))
    .join(' ');

  console.log(
    `${device.name} › Dienst ${service.uuid} › ` +
    `Charakteristik ${char.uuid} › Deskriptor ${descriptor.uuid}: ${bytes}`
  );
};

// Verwendung, z. B. für alle Deskriptoren einer Charakteristik:
// const descriptors = await characteristic.getDescriptors();
// for (const d of descriptors) await beschreibeDeskriptor(d);

Polar H10 › Dienst 0000180d-... › Charakteristik 00002a37-... › Deskriptor 00002902-...: 00 00

Vor dem Schreiben prüfen, ob Benachrichtigungen möglich sind

const aktiviereNotifyUeberDeskriptor = async (descriptor) => {
  const { properties } = descriptor.characteristic;

  if (!properties.notify) {
    console.warn('Charakteristik unterstützt keine Benachrichtigungen.');
    return;
  }
  // Besser ist startNotifications(); das hier nur zur Veranschaulichung
  await descriptor.characteristic.startNotifications();
  console.log('Benachrichtigungen aktiv für', descriptor.characteristic.uuid);
};

Benachrichtigungen aktiv für 00002a37-0000-1000-8000-00805f9b34fb

// Wichtig · Fallstricke

Browser-Unterstützung: Web Bluetooth ist experimentell. Es gibt die API nur in Chromium-Browsern (Chrome, Edge, Opera) auf Desktop und Android, nicht in Firefox und nicht in Safari/iOS. Prüfe vorher mit 'bluetooth' in navigator.
Sicherer Kontext: Funktioniert nur über HTTPS (oder localhost). requestDevice() muss durch eine Nutzeraktion ausgelöst werden. In iframes braucht es die Permissions Policy bluetooth.
Die Eigenschaft liest nichts vom Gerät; sie liefert nur die lokal bereits vorhandene Objekt-Referenz zurück. Nach einer Trennung (gattserverdisconnected) gibt es die Referenz zwar weiterhin, aber Operationen wie readValue() schlagen mit NetworkError fehl, bis man neu verbindet und die Objekte neu abruft.
Den Deskriptor 0x2902 (Client Characteristic Configuration) darf man per writeValue() nicht direkt beschreiben, weil er auf der Sperrliste steht. Benachrichtigungen schaltet man stattdessen mit characteristic.startNotifications() ein.

Siehe auch

BluetoothRemoteGATTDescriptor BluetoothRemoteGATTCharacteristic BluetoothRemoteGATTDescriptor.uuid BluetoothRemoteGATTDescriptor.prototype.readValue() BluetoothRemoteGATTCharacteristic.prototype.getDescriptor() BluetoothRemoteGATTCharacteristic.service BluetoothRemoteGATTDescriptor.value