BluetoothRemoteGATTCharacteristic.writeValueWithResponse() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTCharacteristic.prototype.writeValueWithResponse(value)

Beschreibung

writeValueWithResponse() schreibt die Bytes aus einem ArrayBuffer, einem TypedArray oder einer DataView in eine entfernte GATT-Characteristic. Dabei wird ein ATT-Write Request gesendet: Das Peripheriegerät muss den Schreibvorgang ausdrücklich bestätigen. Das zurückgegebene Promise wird erst erfüllt, wenn diese Bestätigung eingetroffen ist.

Nutze die Methode immer dann, wenn du sicher sein musst, dass die Daten angekommen sind und verarbeitet wurden, z. B. bei Konfigurationswerten, Steuerbefehlen (Motor an/aus, LED-Farbe) oder Firmware-Parametern. Für schnelle Datenströme, bei denen einzelne Pakete verloren gehen dürfen, ist writeValueWithoutResponse() schneller, weil keine Bestätigung abgewartet wird.

Voraussetzung ist, dass die Characteristic die Eigenschaft properties.write besitzt. Die Methode ersetzt das veraltete writeValue(), dessen Schreibmodus vom Browser gewählt wurde und damit nicht vorhersagbar war.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	ArrayBuffer \| TypedArray \| DataView		Die zu schreibenden Bytes. Der Inhalt wird beim Aufruf kopiert; spätere Änderungen am Puffer wirken sich nicht mehr auf den Schreibvorgang aus. Maximal 512 Bytes.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald das Gerät den Schreibvorgang bestätigt hat. Bei Fehlern wird es mit einer DOMException abgelehnt (z. B. NetworkError, NotSupportedError, InvalidModificationError, SecurityError).

Beispiele

Befehl an ein Gerät senden (nach Klick)

// Web Bluetooth benötigt eine Nutzergeste und HTTPS
const SERVICE = 0xffe0;
const CHAR = 0xffe1;

document.querySelector('#connect').addEventListener('click', async () => {
  try {
    const device = await navigator.bluetooth.requestDevice({
      filters: [{ services: [SERVICE] }]
    });
    const server = await device.gatt.connect();
    const service = await server.getPrimaryService(SERVICE);
    const characteristic = await service.getCharacteristic(CHAR);

    // Befehl 0x01 = LED einschalten
    await characteristic.writeValueWithResponse(Uint8Array.of(0x01));
    console.log('Befehl bestätigt');
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

Befehl bestätigt

RGB-Farbe schreiben und Schreibfähigkeit prüfen

const setColor = async (characteristic, r, g, b) => {
  if (!characteristic.properties.write) {
    throw new Error('Characteristic unterstützt kein Write mit Response');
  }
  const data = new Uint8Array([r, g, b]);
  await characteristic.writeValueWithResponse(data);
  console.log(`Farbe gesetzt: rgb(${r}, ${g}, ${b})`);
};

// Aufruf, z. B. nach erfolgreicher Verbindung:
// await setColor(characteristic, 255, 128, 0);

Farbe gesetzt: rgb(255, 128, 0)

Mehrbyte-Wert mit DataView (Little Endian)

const setInterval16 = async (characteristic, ms) => {
  const buffer = new ArrayBuffer(2);
  new DataView(buffer).setUint16(0, ms, true); // Little Endian, wie in BLE üblich
  await characteristic.writeValueWithResponse(buffer);
};

// Schreibvorgänge nacheinander ausführen – nicht parallel!
const applyConfig = async (characteristic, values) => {
  for (const ms of values) {
    await setInterval16(characteristic, ms);
    console.log(`Intervall ${ms} ms übernommen`);
  }
};

Intervall 100 ms übernommen Intervall 250 ms übernommen

// Wichtig · Fallstricke

Browser-Unterstützung: Web Bluetooth ist experimentell und nur in Chromium-Browsern verfügbar (Chrome, Edge, Opera; unter Linux teils hinter einem Flag). Firefox und Safari unterstützen die API nicht. Prüfe vorher mit 'bluetooth' in navigator.
Sicherer Kontext: Funktioniert nur über HTTPS bzw. localhost. requestDevice() braucht zusätzlich eine Nutzergeste.
Keine parallelen Operationen: Startest du einen weiteren GATT-Vorgang, bevor der vorige abgeschlossen ist, wird er oft mit NetworkError: GATT operation already in progress abgelehnt. Deshalb Schreibvorgänge mit await nacheinander ausführen oder in eine Warteschlange stellen.
Größenlimit: Mehr als 512 Bytes führen zu InvalidModificationError. Viele Geräte akzeptieren wegen der MTU in der Praxis noch weniger (oft 20 Bytes).
Unterstützt die Characteristic nur writeWithoutResponse, wird das Promise mit NotSupportedError abgelehnt. In diesem Fall writeValueWithoutResponse() verwenden.
Characteristics auf der Sperrliste (Blocklist) von Web Bluetooth lösen einen SecurityError aus.
Bricht die Verbindung ab, wird das Promise mit NetworkError abgelehnt. Auf das Ereignis gattserverdisconnected reagieren und bei Bedarf neu verbinden.

Siehe auch

BluetoothRemoteGATTCharacteristic BluetoothRemoteGATTCharacteristic.writeValueWithoutResponse() BluetoothRemoteGATTCharacteristic.writeValue() BluetoothRemoteGATTCharacteristic.readValue() BluetoothRemoteGATTCharacteristic.startNotifications() Bluetooth.requestDevice() DataView