Web Serial API

Konzepte und Verwendung

Die Web Serial API ermglicht die Verbindung zu Gerten, die ber ein serielles Protokoll kommunizieren. Dazu gehren USB- und Bluetooth-Gerte, die ber USB oder Bluetooth verbunden sind, aber einen virtuellen seriellen Port dem Betriebssystem zur Verfgung stellen (ber USB CDC-ACM oder Bluetooth SPP).

Beachten Sie, dass diese sich unterscheiden von Gerten, die ber die WebUSB API angesprochen werden die rohen Zugriff auf USB-Gerte ermglicht, die nicht von einem OS-Treiber beansprucht werden oder Eingabegerten, die die USB HID-Klasse verwenden und ber die WebHID API zugnglich sind.

Beispiele fr serielle Gerte sind 3D-Drucker, ESP32-Gerte und Mikrocontroller wie das BBC micro:bit board.

Schnittstellen

Serial

Bietet Attribute und Methoden zum Finden und Anschlieen von seriellen Anschlssen von einer Webseite aus.

SerialPort

Bietet Zugriff auf einen seriellen Anschluss auf dem Host-Gert.

Erweiterungen zu anderen Schnittstellen

Navigator.serial Schreibgeschtzt

Gibt ein Serial-Objekt zurck, das den Einstiegspunkt des Hauptthreads in die Web Serial API darstellt.

WorkerNavigator.serial Schreibgeschtzt

Gibt ein Serial-Objekt zurck, das den Einstiegspunkt des Arbeitsthreads in die Web Serial API darstellt.

HTTP-Header

Permissions-Policy serial Direktive

Kontrolliert, ob das aktuelle Dokument die Web Serial API verwenden darf, um mit seriellen Gerten zu kommunizieren, die entweder direkt ber einen seriellen Port verbunden sind oder ber USB- oder Bluetooth-Gerte, die einen seriellen Port emulieren.

Beispiele

Die folgenden Beispiele demonstrieren einige der Funktionalitten, die von der Web Serial API bereitgestellt werden.

Verfgbare Ports prfen

Das folgende Beispiel zeigt, wie man verfgbare Ports prft und dem Benutzer ermglicht, die Berechtigung zur Nutzung zustzlicher Ports zu erteilen.

Die connect- und disconnect-Ereignisse erlauben es Websites, zu reagieren, wenn ein Gert an das System angeschlossen oder davon getrennt wird. Die Methode getPorts() wird dann aufgerufen, um verbundene Ports anzuzeigen, auf die die Website bereits Zugriff hat.

Wenn die Website auf keinen der angeschlossenen Ports zugreifen kann, muss sie warten, bis sie ber eine Benutzeraktivierung verfgt, um fortzufahren. In diesem Beispiel verwenden wir einen click-Ereignishandler auf einem Button fr diese Aufgabe. Ein Filter wird an requestPort() mit einer USB-Hersteller-ID bergeben, um die Menge der dem Benutzer angezeigten Gerte auf nur solche USB-Gerte eines bestimmten Herstellers zu beschrnken.

navigator.serial.addEventListener("connect", (e) => {
  // Connect to `e.target` or add it to a list of available ports.
});

navigator.serial.addEventListener("disconnect", (e) => {
  // Remove `e.target` from the list of available ports.
});

navigator.serial.getPorts().then((ports) => {
  // Initialize the list of available ports with `ports` on page load.
});

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

Daten von einem Port lesen

Das folgende Beispiel zeigt, wie Daten von einem Port gelesen werden. Die uere Schleife behandelt nicht-fatale Fehler, indem sie einen neuen Leser erstellt, bis ein fataler Fehler auftritt und SerialPort.readable null wird.

while (port.readable) {
  const reader = port.readable.getReader();
  try {
    while (true) {
      const { value, done } = await reader.read();
      if (done) {
        // |reader| has been canceled.
        break;
      }
      // Do something with |value|...
    }
  } catch (error) {
    // Handle |error|...
  } finally {
    reader.releaseLock();
  }
}

Spezifikationen

Browser-Kompatibilitt

Siehe auch

• Lesen und Schreiben an einem seriellen Port
• Erste Schritte mit der Web Serial API