BluetoothRemoteGATTDescriptor.value — Eigenschaft · JavaScript-Referenz

Signatur

BluetoothRemoteGATTDescriptor.value

Beschreibung

Die Eigenschaft value eines BluetoothRemoteGATTDescriptor enthält den zwischengespeicherten Wert des Deskriptors als DataView. Sie liest also nicht selbst vom Gerät, sondern gibt das Ergebnis des letzten erfolgreichen readValue()- oder writeValue()-Aufrufs zurück.

Deskriptoren beschreiben eine Characteristic genauer. Typische Beispiele sind die Characteristic User Description (0x2901), ein lesbarer Klartextname, oder die Client Characteristic Configuration (0x2902), mit der Benachrichtigungen ein- oder ausgeschaltet werden. Mit value kann man ohne erneuten Funkzugriff noch einmal auf den zuletzt bekannten Wert zugreifen, etwa beim Neuzeichnen einer Oberfläche.

Bevor ein Wert gelesen oder geschrieben wurde, ist value null. Weil die Daten als rohe Bytes ankommen, muss man sie mit DataView-Methoden wie getUint8() oder getUint16(offset, true) für Little Endian auswerten, oder bei Text mit TextDecoder.

Rückgabewert

Typ

DataView | null

Beschreibung

Eine DataView mit den Bytes des zuletzt gelesenen oder geschriebenen Deskriptorwerts oder null, solange noch kein Wert vorliegt.

Beispiele

Benutzerbeschreibung einer Characteristic lesen und aus dem Zwischenspeicher nutzen

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

button.addEventListener('click', 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 characteristic = await service.getCharacteristic('battery_level');
  const descriptor = await characteristic.getDescriptor('gatt.characteristic_user_description');

  console.log(descriptor.value); // vor dem Lesen: null

  await descriptor.readValue();
  // Wert liegt jetzt im Zwischenspeicher
  const text = new TextDecoder('utf-8').decode(descriptor.value);
  console.log(`Beschreibung: ${text}`);
});

null Beschreibung: Battery Level

Status der Benachrichtigungen (CCCD) auswerten

const pruefeBenachrichtigung = async (characteristic) => {
  const cccd = await characteristic.getDescriptor(
    'gatt.client_characteristic_configuration'
  );
  await cccd.readValue();

  // 16-Bit-Wert, Little Endian: Bit 0 = Notify, Bit 1 = Indicate
  const flags = cccd.value.getUint16(0, true);
  return {
    notify: Boolean(flags & 0x01),
    indicate: Boolean(flags & 0x02)
  };
};

// Nutzung, nachdem eine Characteristic ermittelt wurde:
// console.log(await pruefeBenachrichtigung(characteristic));

{ notify: true, indicate: false }

value nach writeValue() prüfen

const schreibeBeschreibung = async (descriptor, text) => {
  const bytes = new TextEncoder().encode(text);
  await descriptor.writeValue(bytes);

  // value spiegelt jetzt den geschriebenen Wert wider
  console.log(descriptor.value.byteLength);
  console.log(new TextDecoder().decode(descriptor.value));
};

// await schreibeBeschreibung(descriptor, 'Sensor A');

8 Sensor A

// Wichtig · Fallstricke

Zwischengespeicherter Wert: value baut keine Verbindung zum Gerät auf. Wenn sich der Wert auf dem Gerät ändert, ist value veraltet, bis man erneut readValue() aufruft.
Auf null prüfen: Solange nicht gelesen oder geschrieben wurde, ist value null. Ein direkter Aufruf wie descriptor.value.getUint8(0) löst dann einen TypeError aus. Daher besser descriptor.value?.getUint8(0) schreiben.
Byte-Reihenfolge: Mehrbyte-Werte nach der GATT-Spezifikation sind Little Endian. Deshalb bei getUint16() und getInt16() den zweiten Parameter auf true setzen.
Einschränkungen: Einige Deskriptoren, etwa HID-Report-bezogene, stehen auf der Sperrliste der Web Bluetooth API. Der Zugriff darauf wirft einen SecurityError. Die CCCD sollte man nicht direkt beschreiben, sondern startNotifications() verwenden.
Kompatibilität: Web Bluetooth ist experimentell. Es funktioniert nur in Chromium-basierten Browsern, nur in einer sicheren Umgebung (HTTPS), und requestDevice() braucht eine Benutzeraktion. Firefox und Safari unterstützen die API nicht. Vorher mit 'bluetooth' in navigator prüfen, ob sie verfügbar ist.

Siehe auch

BluetoothRemoteGATTDescriptor.uuid BluetoothRemoteGATTDescriptor.characteristic BluetoothRemoteGATTCharacteristic.value BluetoothRemoteGATTServer.device BluetoothRemoteGATTService.device