BluetoothRemoteGATTCharacteristic.writeValue() — Methode · JavaScript-Referenz

Signatur

BluetoothRemoteGATTCharacteristic.prototype.writeValue(value)

Beschreibung

writeValue() überträgt Binärdaten an eine Characteristic eines verbundenen Bluetooth-Low-Energy-Geräts, etwa um eine LED zu schalten, einen Sollwert zu setzen oder einen Befehl an ein Steuergerät zu senden. Die Methode gehört zur Web Bluetooth API und gibt ein Promise zurück, das nach Abschluss des Schreibvorgangs erfüllt wird.

Die Methode ist veraltet, weil sie nicht festlegt, ob der Schreibvorgang mit oder ohne Bestätigung durch das Gerät erfolgt. Der Browser entscheidet das anhand der Eigenschaften der Characteristic selbst (bei Chrome in der Regel „mit Bestätigung“, wenn properties.write gesetzt ist, sonst „ohne Bestätigung“). Für vorhersagbares Verhalten sollten Sie deshalb gezielt writeValueWithResponse() (zuverlässig, langsamer) oder writeValueWithoutResponse() (schnell, ohne Zustellgarantie) verwenden.

Der übergebene Wert muss ein BufferSource sein, also ein ArrayBuffer, ein TypedArray (z. B. Uint8Array) oder eine DataView. Zeichenketten müssen vorher z. B. mit TextEncoder kodiert werden. Die Daten dürfen höchstens 512 Byte lang sein.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	ArrayBuffer\|TypedArray\|DataView		Die zu schreibenden Bytes (`BufferSource`). Maximal 512 Byte; der Inhalt wird beim Aufruf kopiert.

Rückgabewert

Typ

Promise<void>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Schreibvorgang abgeschlossen ist. Es wird abgelehnt, z. B. mit InvalidModificationError (Wert zu lang), NotSupportedError (Characteristic nicht beschreibbar), NetworkError (Gerät getrennt), SecurityError (Characteristic steht auf der Sperrliste) oder InvalidStateError.

Beispiele

LED eines BLE-Geräts einschalten (Legacy-Code)

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

button.addEventListener('click', async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['19b10000-e8f2-537e-4f6c-d104768a1214'] }]
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('19b10000-e8f2-537e-4f6c-d104768a1214');
  const characteristic = await service.getCharacteristic('19b10001-e8f2-537e-4f6c-d104768a1214');

  // Veraltet: Schreibmodus wird vom Browser gewählt
  await characteristic.writeValue(Uint8Array.of(1));
  console.log('LED eingeschaltet');
});

LED eingeschaltet

Migration auf die expliziten Nachfolger-Methoden

const writeCompat = async (characteristic, data) => {
  const { properties } = characteristic;

  if (properties.write && 'writeValueWithResponse' in characteristic) {
    // Mit Bestätigung durch das Gerät
    return characteristic.writeValueWithResponse(data);
  }
  if (properties.writeWithoutResponse && 'writeValueWithoutResponse' in characteristic) {
    // Schnell, aber ohne Zustellgarantie
    return characteristic.writeValueWithoutResponse(data);
  }
  // Rückfall für ältere Browser
  return characteristic.writeValue(data);
};

// Aufruf, z. B. mit einer zuvor ermittelten Characteristic:
// await writeCompat(characteristic, Uint8Array.of(0x01, 0xff));

Text und Zahlen korrekt kodieren

const setDeviceName = async (characteristic, name) => {
  const bytes = new TextEncoder().encode(name);
  if (bytes.byteLength > 512) {
    throw new RangeError('Wert zu lang (max. 512 Byte)');
  }
  await characteristic.writeValue(bytes);
};

const setTemperature = async (characteristic, celsius) => {
  // 16-Bit-Wert in Little Endian, wie bei BLE üblich
  const view = new DataView(new ArrayBuffer(2));
  view.setInt16(0, Math.round(celsius * 100), true);
  await characteristic.writeValue(view);
};

// Wichtig · Fallstricke

Veraltet: Neuer Code sollte writeValueWithResponse() bzw. writeValueWithoutResponse() verwenden. writeValue() funktioniert in Chromium weiterhin, das Schreibverhalten ist aber nicht explizit festgelegt.
Browser-Unterstützung: Web Bluetooth gibt es nur in Chromium-basierten Browsern (Chrome, Edge, Opera, teils Android). Firefox und Safari unterstützen die API nicht. Prüfen Sie das vorab mit 'bluetooth' in navigator.
Nur in sicheren Kontexten (HTTPS oder localhost) verfügbar; requestDevice() braucht eine Nutzeraktion. In iframes muss die Permissions Policy bluetooth erlaubt sein.
GATT-Operationen laufen nacheinander. Starten Sie mehrere Schreibvorgänge gleichzeitig, kann das NetworkError: GATT operation already in progress auslösen. Warten Sie deshalb jeden Aufruf mit await ab oder reihen Sie die Aufrufe hintereinander ein.
Strings nicht direkt übergeben – immer vorher in ein Uint8Array kodieren. Achten Sie bei Mehrbyte-Werten auf die Byte-Reihenfolge (Endianness).

Siehe auch

BluetoothRemoteGATTCharacteristic.writeValueWithResponse() BluetoothRemoteGATTCharacteristic.writeValueWithoutResponse() BluetoothRemoteGATTCharacteristic.readValue() BluetoothRemoteGATTCharacteristic.startNotifications() BluetoothRemoteGATTCharacteristic Bluetooth.requestDevice() BluetoothRemoteGATTDescriptor.writeValue()