BluetoothCharacteristicProperties.broadcast — Eigenschaft · JavaScript-Referenz

Signatur

BluetoothCharacteristicProperties.broadcast

Beschreibung

Die Eigenschaft broadcast gehört zum Interface BluetoothCharacteristicProperties der Web-Bluetooth-API. Sie gibt an, ob der Wert einer Characteristic gesendet werden darf, während das Gerät seine Anwesenheit ankündigt (Advertising). Gesteuert wird das über den Server Characteristic Configuration Descriptor (SCCD, UUID 0x2903). Der Wert entspricht dem Broadcast-Bit (0x01) im Properties-Feld der Characteristic-Deklaration, wie es in der Bluetooth-Core-Spezifikation festgelegt ist.

Man erreicht die Eigenschaft über BluetoothRemoteGATTCharacteristic.properties. Sie ist rein informativ: Eine Web-Anwendung kann damit prüfen, was eine Characteristic kann. Einen Broadcast kann sie damit aber nicht direkt auslösen. Dafür müsste der SCCD-Descriptor beschrieben werden, und das erlaubt der Browser häufig nicht.

Typische Anwendungsfälle sind Diagnose- und Explorer-Werkzeuge, die alle Fähigkeiten eines BLE-Geräts anzeigen, sowie eine Fallunterscheidung, bevor mit einer Characteristic gearbeitet wird. In der Praxis ist broadcast bei den meisten Geräten false. Wichtiger sind meist read, write und notify.

Beispiele

Broadcast-Fähigkeit einer Characteristic prüfen

// Muss durch eine Nutzeraktion ausgelöst werden (z. B. Klick)
document.querySelector('#verbinden').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');

  console.log('Broadcast möglich:', characteristic.properties.broadcast);
});

Broadcast möglich: false

Alle Properties einer Characteristic auflisten

const beschreibeProperties = (characteristic) => {
  const p = characteristic.properties;
  const namen = [
    'broadcast', 'read', 'writeWithoutResponse', 'write',
    'notify', 'indicate', 'authenticatedSignedWrites',
    'reliableWrite', 'writableAuxiliaries'
  ];
  return namen.filter((name) => p[name]);
};

// Nutzung nach erfolgreicher Verbindung:
// console.log(beschreibeProperties(characteristic));

["read", "notify"]

Explorer: Broadcast-fähige Characteristics eines Services finden

const findeBroadcastCharacteristics = async (service) => {
  const characteristics = await service.getCharacteristics();
  return characteristics
    .filter((c) => c.properties.broadcast)
    .map((c) => c.uuid);
};

// const uuids = await findeBroadcastCharacteristics(service);
// console.log(uuids.length ? uuids : 'Keine Broadcast-Characteristics');

Keine Broadcast-Characteristics

// Wichtig · Fallstricke

Experimentell: Web Bluetooth wird nur von Chromium-Browsern unterstützt (Chrome, Edge, Opera), aber nicht von Firefox und Safari (auch nicht unter iOS). Vor der Nutzung mit 'bluetooth' in navigator prüfen, ob die API vorhanden ist.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung. requestDevice() braucht außerdem eine Nutzeraktion, zum Beispiel einen Klick.
Nur lesbar: Wenn man broadcast einen Wert zuweist, passiert nichts (im strikten Modus wird ein TypeError ausgelöst). Um Broadcasts zu aktivieren, muss der SCCD-Descriptor (0x2903) beschrieben werden. Das Gerät und der Browser müssen das zulassen.
Den Wert legt die Firmware des Geräts fest. true bedeutet nur, dass Broadcasts unterstützt werden, nicht dass sie gerade aktiv sind.
Nur Services, die in filters oder optionalServices angegeben sind, sind zugänglich. Andernfalls wirft getPrimaryService() einen SecurityError.

Siehe auch

BluetoothCharacteristicProperties.read BluetoothCharacteristicProperties.indicate BluetoothCharacteristicProperties.notify BluetoothCharacteristicProperties.write BluetoothCharacteristicProperties.reliableWrite