Serial: requestPort() Methode

Wenn der Benutzer eine Website zum ersten Mal besucht, hat die Seite keine Berechtigung, auf serielle Geräte zuzugreifen. Eine Seite muss zuerst requestPort() aufrufen, um den Benutzer aufzufordern, das Gerät auszuwählen, das die Seite steuern darf.

Diese Methode muss über eine transiente Aktivierung aufgerufen werden. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.

options Optional

Ein Objekt mit den folgenden Eigenschaften:

filters Optional

Eine Liste von Objekten, die Vendor-, Produkt- oder Bluetooth-Dienstklassen-IDs enthalten und verwendet werden, um die spezifischen Gerätetypen zu filtern, die dem Benutzer zur Auswahl für eine Verbindung zur Verfügung gestellt werden. Wenn keine Filter angegeben sind, wird dem Benutzer eine Liste aller verfügbaren Geräte angezeigt. Filter können die folgenden Werte enthalten:

bluetoothServiceClassId Optional

Eine nicht signierte lange Ganzzahl oder ein String, der eine Bluetooth-Dienstklassen-ID darstellt. Dies kann eine 16- oder 32-Bit-UUID-Alias, jede gültige UUID oder ein gültiger Name aus einem GATT zugewiesenen Diensteschlüssel sein.

usbVendorId Optional

Eine nicht signierte kurze Ganzzahl, die einen USB-Gerätehersteller identifiziert. Das USB Implementers Forum weist IDs spezifischen Anbietern zu.

usbProductId Optional

Eine nicht signierte kurze Ganzzahl, die ein USB-Gerät identifiziert. Jeder Hersteller weist IDs seinen Produkten zu.

allowedBluetoothServiceClassIds Optional

Eine Liste von nicht signierten langen Ganzzahlen und/oder Strings, die Bluetooth-Dienstklassen-IDs darstellen. Bluetooth-Ports mit benutzerdefinierten Dienstklassen-IDs sind von der Liste der dem Benutzer präsentierten Ports ausgeschlossen, es sei denn, die Dienstklassen-ID ist in dieser Liste enthalten. Dies gilt unabhängig davon, ob Sie die Liste filtern oder nicht.

Ein Promise, das mit einer Instanz von SerialPort aufgelöst wird.

SecurityError DOMException

Das zurückgegebene Promise wird mit diesem Fehler in einer der folgenden Situationen abgelehnt:

• Eine serial Berechtigungsrichtlinie blockiert die Verwendung dieser Funktion.
• Eine Benutzerberechtigungsanfrage wurde abgelehnt.

NotFoundError DOMException

Das zurückgegebene Promise wird mit dieser Ausnahme abgelehnt, wenn der Benutzer beim Auffordern keinen Port auswählt.

Dieses Beispiel fordert den Benutzer auf, ein Gerät über requestPort() auszuwählen, wenn ein <button> gedrückt wird. Es enthält keinen Filter, was bedeutet, dass die Auswahlliste alle verfügbaren Geräte enthält:

<button id="connect">Connect</button>

const connectBtn = document.getElementById("connect");
connectBtn.addEventListener("click", () => {
  try {
    const port = await navigator.serial.requestPort();
    // Connect to port or add it to the list of available ports
  } catch (e) {
    // The user didn't select a device
  }
});

In diesem Fall wird ein Filter an requestPort() übergeben, der eine USB Vendor ID enthält, um die Anzahl der dem Benutzer angezeigten Geräte auf USB-Geräte eines bestimmten Herstellers zu beschränken.

connectBtn.addEventListener("click", () => {
  const usbVendorId = 0xabcd;
  try {
    const port = await navigator.serial.requestPort({ filters: [{ usbVendorId }] });
    // Connect to port or add it to the list of available ports
  } catch (e) {
    // The user didn't select a device
  }
});

Obwohl die meisten Geräte SPP-basierte Kommunikation über das standardisierte Bluetooth Classic Serial Port Profile bereitstellen, verwenden einige benutzerdefinierte radiofrequenzbasierte Kommunikationsdienste (RFCOMM). Diese Geräte haben eine Dienstklassen-ID, die nicht in den Standard-Bluetooth-UUID-Bereich fällt.

Sie müssen die allowedBluetoothServiceClassIds-Liste an requestPort() übergeben, um auf diese benutzerdefinierten RFCOMM-basierten Dienste zuzugreifen:

const myBluetoothServiceUuid = "01234567-89ab-cdef-0123-456789abcdef";

// Prompt user to select any serial port
// Access to the custom Bluetooth RFCOMM service above will be allowed
const port = await navigator.serial.requestPort({
  allowedBluetoothServiceClassIds: [myBluetoothServiceUuid],
});

Sie können auch den bluetoothServiceClassId Filter-Schlüssel verwenden, wenn Sie requestPort() aufrufen, um den Benutzer mit einer gefilterten Liste von Bluetooth-Serien-Ports, die durch Dienstklassen-IDs identifiziert werden, aufzufordern:

const myBluetoothServiceUuid = "01234567-89ab-cdef-0123-456789abcdef";

// Prompt the user to select Bluetooth serial ports with
// the custom Bluetooth RFCOMM service above.
const port = await navigator.serial.requestPort({
  allowedBluetoothServiceClassIds: [myBluetoothServiceUuid],
  filters: [{ bluetoothServiceClassId: myBluetoothServiceUuid }],
});