Serial.getPorts() — Methode · JavaScript-Referenz

Signatur

Serial.prototype.getPorts()

Beschreibung

Mit navigator.serial.getPorts() fragen Sie die seriellen Schnittstellen ab, auf die der Ursprung (Origin) Ihrer Seite bereits zugreifen darf. Anders als bei requestPort() erscheint dabei kein Auswahldialog. Die Methode liefert nur Ports, die der Benutzer früher über requestPort() freigegeben hat und die noch angeschlossen sind oder dauerhaft verfügbar bleiben (z. B. fest verbaute Schnittstellen).

Typischer Einsatz: Nach dem Neuladen der Seite stellen Sie automatisch die Verbindung zu einem bekannten Gerät wieder her, etwa einem Arduino, einem 3D-Drucker oder einem Barcode-Scanner. Der Benutzer muss das Gerät dann nicht erneut auswählen. Über SerialPort.getInfo() erkennen Sie das richtige Gerät anhand von usbVendorId und usbProductId.

Die Methode ist asynchron und hat keine Parameter. Ein leeres Array bedeutet: Es gibt noch keine Berechtigung oder kein berechtigtes Gerät ist angeschlossen. In diesem Fall müssen Sie auf requestPort() zurückgreifen. Das setzt eine Benutzeraktion voraus, zum Beispiel einen Klick.

Rückgabewert

Typ

Promise<SerialPort[]>

Beschreibung

Ein Promise, das mit einem Array von SerialPort-Objekten aufgelöst wird. Das Array ist leer, wenn keine berechtigten Ports verfügbar sind. Die Ports sind noch nicht geöffnet, dafür rufen Sie port.open() auf.

Beispiele

Bereits freigegebene Ports auflisten

const listPorts = async () => {
  if (!('serial' in navigator)) {
    console.log('Web Serial API wird nicht unterstützt.');
    return;
  }
  const ports = await navigator.serial.getPorts();
  console.log(`Berechtigte Ports: ${ports.length}`);
  ports.forEach((port, i) => {
    const { usbVendorId, usbProductId } = port.getInfo();
    console.log(`#${i}: Vendor ${usbVendorId?.toString(16)}, Produkt ${usbProductId?.toString(16)}`);
  });
};

listPorts();

Berechtigte Ports: 1 #0: Vendor 2341, Produkt 43

Automatisch zu einem bekannten Arduino verbinden, sonst Dialog anbieten

const ARDUINO_VENDOR = 0x2341;

const findArduino = async () => {
  const ports = await navigator.serial.getPorts();
  return ports.find((p) => p.getInfo().usbVendorId === ARDUINO_VENDOR);
};

const connect = async (port) => {
  await port.open({ baudRate: 9600 });
  console.log('Verbunden mit Arduino');
  return port;
};

// Beim Laden: ohne Dialog wiederverbinden
const init = async () => {
  const port = await findArduino();
  if (port) {
    await connect(port);
  } else {
    console.log('Kein berechtigter Port – bitte „Verbinden“ klicken.');
  }
};

// requestPort() braucht eine Benutzeraktion
document.querySelector('#connect').addEventListener('click', async () => {
  const port = await navigator.serial.requestPort({
    filters: [{ usbVendorId: ARDUINO_VENDOR }]
  });
  await connect(port);
});

init();

Verbunden mit Arduino

Port-Liste bei An- und Abstecken aktualisieren

const renderPorts = async () => {
  const ports = await navigator.serial.getPorts();
  const list = document.querySelector('#ports');
  list.replaceChildren(...ports.map((port) => {
    const li = document.createElement('li');
    const { usbVendorId = '–', usbProductId = '–' } = port.getInfo();
    li.textContent = `VID ${usbVendorId} / PID ${usbProductId}`;
    return li;
  }));
};

navigator.serial.addEventListener('connect', renderPorts);
navigator.serial.addEventListener('disconnect', renderPorts);
renderPorts();

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Methode ist nur in Chromium-basierten Desktop-Browsern verfügbar (ab Chrome/Edge 89). Firefox, Safari und die meisten mobilen Browser unterstützen sie nicht. Prüfen Sie die Unterstützung vorher mit 'serial' in navigator.
Nur in sicheren Kontexten: Die Seite muss über HTTPS oder localhost laufen. Außerdem kann die Permissions-Policy serial den Zugriff sperren, zum Beispiel in iframes ohne allow="serial". Dann wird das Promise mit einem SecurityError abgelehnt.
Die Methode liefert keine neuen Geräte. Ein leeres Array ist der Normalfall beim ersten Besuch. Neue Ports erhalten Sie nur über requestPort() mit einer Benutzeraktion.
Die zurückgegebenen Ports sind geschlossen. Rufen Sie vor dem Lesen oder Schreiben open() auf. Ein Port, der schon geöffnet ist, löst bei erneutem open() einen InvalidStateError aus.
Berechtigungen können verfallen, etwa wenn der Benutzer sie in den Website-Einstellungen widerruft oder mit SerialPort.forget() entfernt werden. Verlassen Sie sich daher nicht darauf, dass ein Port dauerhaft in der Liste bleibt.
Ob die Methode in Web Workern verfügbar ist, hängt von der Browserversion ab.

Siehe auch

Serial SerialPort SerialPort.open() SerialPort.forget() Serial.requestPort()