BluetoothRemoteGATTCharacteristic — Schnittstelle · JavaScript-Referenz

Signatur

interface BluetoothRemoteGATTCharacteristic extends EventTarget

Beschreibung

Das Interface BluetoothRemoteGATTCharacteristic der Web Bluetooth API steht für eine GATT-Charakteristik. Das ist das eigentliche Datenelement eines Dienstes (BluetoothRemoteGATTService) auf einem Bluetooth-Low-Energy-Gerät, zum Beispiel der Akkustand, die Herzfrequenz oder ein Steuerbefehl für eine Lampe. Zu jeder Charakteristik gehören eine UUID, ein Wert und Eigenschaften, die festlegen, ob der Wert gelesen, geschrieben oder per Benachrichtigung übertragen werden kann.

Eine Instanz erzeugt man nicht selbst. Man bekommt sie über service.getCharacteristic(uuid) oder service.getCharacteristics(), nachdem man mit navigator.bluetooth.requestDevice() ein Gerät gewählt und per device.gatt.connect() verbunden hat.

Eigenschaften:

service: der BluetoothRemoteGATTService, zu dem die Charakteristik gehört (nur lesbar).
uuid: die UUID der Charakteristik als String, z. B. "00002a19-0000-1000-8000-00805f9b34fb" für den Akkustand.
properties: ein BluetoothCharacteristicProperties-Objekt mit Wahrheitswerten wie read, write, writeWithoutResponse, notify und indicate.
value: der zuletzt gelesene oder gemeldete Wert als DataView, bis zum ersten Lesen null.

Methoden:

readValue(): liest den Wert und gibt Promise<DataView> zurück.
writeValueWithResponse(value) / writeValueWithoutResponse(value): schreiben einen BufferSource, mit oder ohne Bestätigung vom Gerät.
writeValue(value): veraltet, gleiche Wirkung wie ein Schreiben, bei dem der Browser die Art wählt.
startNotifications() / stopNotifications(): schalten Benachrichtigungen ein oder aus. Neue Werte kommen als Event characteristicvaluechanged.
getDescriptor(uuid) / getDescriptors([uuid]): liefern die Deskriptoren (BluetoothRemoteGATTDescriptor) der Charakteristik.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	ArrayBuffer \| TypedArray \| DataView		Wird von `writeValueWithResponse()`, `writeValueWithoutResponse()` und `writeValue()` gebraucht: die Bytes, die geschrieben werden (`BufferSource`). Höchstens 512 Byte.
$descriptor	string \| number		Wird von `getDescriptor()` und `getDescriptors()` gebraucht: UUID des Deskriptors als 128-Bit-String, 16-Bit-Kurzform (z. B. `0x2902`) oder bekannter Name wie `"gatt.client_characteristic_configuration"`.

Rückgabewert

Typ

BluetoothRemoteGATTCharacteristic

Beschreibung

Man bekommt die Instanz aus BluetoothRemoteGATTService.getCharacteristic() (Promise<BluetoothRemoteGATTCharacteristic>) oder aus getCharacteristics() (Promise<BluetoothRemoteGATTCharacteristic[]>).

Beispiele

Charakteristik holen und Akkustand lesen

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

button.addEventListener('click', async () => {
  try {
    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');

    console.log('UUID:', characteristic.uuid);
    console.log('Lesbar:', characteristic.properties.read);

    const dataView = await characteristic.readValue();
    console.log(`Akkustand: ${dataView.getUint8(0)} %`);
  } catch (err) {
    console.error('Bluetooth-Fehler:', err.name, err.message);
  }
});

UUID: 00002a19-0000-1000-8000-00805f9b34fb Lesbar: true Akkustand: 87 %

Herzfrequenz per Benachrichtigung empfangen

const startHeartRate = 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 hr = await service.getCharacteristic('heart_rate_measurement');

  const onChange = (event) => {
    const value = event.target.value; // DataView
    const flags = value.getUint8(0);
    // Bit 0 gibt an, ob der Wert 8 oder 16 Bit lang ist
    const bpm = flags & 0x01 ? value.getUint16(1, true) : value.getUint8(1);
    console.log(`Puls: ${bpm} bpm`);
  };

  hr.addEventListener('characteristicvaluechanged', onChange);
  await hr.startNotifications();

  // Stoppen: Benachrichtigungen abschalten und Listener entfernen
  return async () => {
    await hr.stopNotifications();
    hr.removeEventListener('characteristicvaluechanged', onChange);
  };
};

document.querySelector('#start').addEventListener('click', async () => {
  const stop = await startHeartRate();
  setTimeout(stop, 30_000); // nach 30 Sekunden stoppen
});

Puls: 72 bpm Puls: 74 bpm …

Steuerbefehl mit Bestätigung schreiben

// Beispiel: eigener LED-Dienst mit einer 128-Bit-UUID
const LED_SERVICE = '19b10000-e8f2-537e-4f6c-d104768a1214';
const LED_CHAR = '19b10001-e8f2-537e-4f6c-d104768a1214';

const setLed = async (characteristic, on) => {
  const data = Uint8Array.of(on ? 1 : 0);
  if (characteristic.properties.write) {
    await characteristic.writeValueWithResponse(data);
  } else if (characteristic.properties.writeWithoutResponse) {
    await characteristic.writeValueWithoutResponse(data);
  } else {
    throw new Error('Charakteristik ist nicht beschreibbar');
  }
  console.log(`LED ${on ? 'an' : 'aus'}`);
};

document.querySelector('#led').addEventListener('click', async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: [LED_SERVICE] }]
  });
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService(LED_SERVICE);
  const led = await service.getCharacteristic(LED_CHAR);
  await setLed(led, true);
});

LED an

Siehe auch

BluetoothRemoteGATTDescriptor BluetoothRemoteGATTServer BluetoothRemoteGATTService BluetoothCharacteristicProperties BluetoothDevice