BluetoothRemoteGATTDescriptor.writeValue() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTDescriptor.prototype.writeValue(value)

Beschreibung

writeValue() gehört zur Web Bluetooth API. Die Methode schreibt Binärdaten in einen Deskriptor einer GATT-Characteristic auf einem verbundenen Bluetooth-Low-Energy-Gerät. Deskriptoren sind Metadaten einer Characteristic, z. B. die Client Characteristic Configuration (0x2902) oder die Characteristic User Description (0x2901).

Nach einem erfolgreichen Schreibvorgang löst das Promise mit undefined auf, und die Eigenschaft value des Deskriptors enthält danach ein DataView mit den geschriebenen Bytes. Die Daten werden vor dem Senden kopiert. Spätere Änderungen am übergebenen Puffer wirken sich also nicht mehr auf den Schreibvorgang aus.

Brauchbar ist die Methode vor allem bei herstellerspezifischen Deskriptoren oder um einen Benutzer-Beschreibungstext zu setzen. Für Benachrichtigungen (Notifications/Indications) sollte man dagegen BluetoothRemoteGATTCharacteristic.startNotifications() verwenden. Diese Methode schreibt den CCCD-Deskriptor intern selbst, und direktes Schreiben auf 0x2902 blockiert der Browser.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	ArrayBuffer \| TypedArray \| DataView		Die zu schreibenden Bytes. Laut Spezifikation höchstens 512 Byte. Bei längeren Daten wird das Promise mit `InvalidModificationError` abgelehnt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das nach erfolgreichem Schreiben mit undefined auflöst. Abgelehnt wird es z. B. mit NetworkError (keine Verbindung), SecurityError (Deskriptor auf der Sperrliste), NotSupportedError (Schreiben nicht erlaubt) oder InvalidModificationError (Wert zu lang).

Beispiele

Benutzer-Beschreibung (0x2901) einer Characteristic setzen

const connectAndDescribe = async () => {
  // Muss durch eine Benutzeraktion ausgelöst werden (z. B. Klick)
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['environmental_sensing'] }]
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('environmental_sensing');
  const characteristic = await service.getCharacteristic('temperature');
  const descriptor = await characteristic.getDescriptor('gatt.characteristic_user_description');

  const bytes = new TextEncoder().encode('Wohnzimmer');
  await descriptor.writeValue(bytes);
  console.log('Beschreibung geschrieben:', new TextDecoder().decode(descriptor.value));
};

document.querySelector('#connect').addEventListener('click', connectAndDescribe);

Beschreibung geschrieben: Wohnzimmer

Herstellerspezifischen Deskriptor mit DataView beschreiben

const writeConfig = async (descriptor, intervalMs) => {
  // 16-Bit-Intervall, Little Endian, wie im BLE-Standard üblich
  const view = new DataView(new ArrayBuffer(2));
  view.setUint16(0, intervalMs, true);
  await descriptor.writeValue(view);
  console.log('Neuer Wert:', descriptor.value.getUint16(0, true));
};

// descriptor stammt aus characteristic.getDescriptor('0000abcd-0000-1000-8000-00805f9b34fb')
// await writeConfig(descriptor, 500);

Neuer Wert: 500

Fehlerbehandlung beim Schreiben

const safeWrite = async (descriptor, data) => {
  try {
    await descriptor.writeValue(data);
    return true;
  } catch (err) {
    if (err.name === 'NetworkError') {
      console.warn('Gerät nicht verbunden – neu verbinden …');
      await descriptor.characteristic.service.device.gatt.connect();
      await descriptor.writeValue(data);
      return true;
    }
    console.error(`Schreiben fehlgeschlagen: ${err.name} – ${err.message}`);
    return false;
  }
};

// Wichtig · Fallstricke

Kompatibilität: Web Bluetooth ist experimentell und steht nur in Chromium-basierten Browsern zur Verfügung (Chrome, Edge, Opera, teils Android). Firefox und Safari unterstützen die API nicht. Vor der Nutzung sollte man auf 'bluetooth' in navigator prüfen.
Sicherer Kontext: Die Methode funktioniert nur über HTTPS bzw. localhost. Außerdem muss requestDevice() durch eine Benutzeraktion ausgelöst werden. In iframes ist zusätzlich die Permissions Policy bluetooth nötig.
Sperrliste: Bestimmte Deskriptoren, z. B. die Client Characteristic Configuration 0x2902, sind für das Schreiben gesperrt und führen zu einem SecurityError. Für Benachrichtigungen nutzt man startNotifications().
Größenlimit: Werte über 512 Byte werden mit InvalidModificationError abgelehnt.
Parallele Vorgänge: Viele Geräte und Implementierungen erlauben nur einen GATT-Vorgang zur selben Zeit. Gleichzeitige Aufrufe können mit „GATT operation already in progress" scheitern. Schreibvorgänge deshalb nacheinander mit await ausführen.

Siehe auch

BluetoothRemoteGATTDescriptor.readValue() BluetoothRemoteGATTCharacteristic.writeValue() BluetoothRemoteGATTCharacteristic.readValue() BluetoothRemoteGATTServer.connect() BluetoothRemoteGATTServer.disconnect()