SerialPort.connected — Eigenschaft · JavaScript-Referenz

Signatur

SerialPort.connected

Beschreibung

Die schreibgeschützte Eigenschaft connected des SerialPort-Interfaces aus der Web Serial API gibt true zurück, wenn der Port logisch mit dem Gerät verbunden ist, sonst false. Die Eigenschaft sagt nur, ob das Gerät erreichbar ist. Ob der Port mit open() geöffnet wurde, spielt dafür keine Rolle.

Wie der Wert zu verstehen ist, hängt von der Art der Verbindung ab:

Kabelgebundene Ports (USB-Seriell-Adapter, eingebaute serielle Schnittstellen): Der Port ist verbunden, solange das Gerät am System angeschlossen ist. Wird es abgezogen, ist connected false.
Drahtlose Ports (Bluetooth RFCOMM): Ein gekoppeltes Gerät kann vom Betriebssystem bekannt sein, aber trotzdem außer Reichweite oder ausgeschaltet sein. Dann liefert navigator.serial.getPorts() den Port zwar, connected ist aber false.

Nützlich ist die Eigenschaft vor allem, wenn eine Anwendung früher freigegebene Ports mit getPorts() wiederherstellt. Mit connected kann sie prüfen, ob sich ein Öffnen überhaupt lohnt. Außerdem hilft die Eigenschaft, eine Statusanzeige zu aktualisieren. Wenn sich der Zustand ändert, werden die Events connect und disconnect ausgelöst, und zwar sowohl am SerialPort selbst als auch an navigator.serial.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Port logisch mit dem Gerät verbunden ist, sonst false.

Beispiele

Gespeicherte Ports prüfen und nur verbundene öffnen

// Ports, die der Nutzer früher freigegeben hat
const ports = await navigator.serial.getPorts();

for (const port of ports) {
  const { usbVendorId, bluetoothServiceClassId } = port.getInfo();
  console.log('Port', usbVendorId ?? bluetoothServiceClassId, 'verbunden:', port.connected);

  if (port.connected) {
    await port.open({ baudRate: 115200 });
    console.log('Port geöffnet');
    break;
  }
}

Port 9025 verbunden: true Port geöffnet

Statusanzeige über connect-/disconnect-Events aktualisieren

const statusEl = document.querySelector('#status');

const renderStatus = (port) => {
  statusEl.textContent = port.connected ? 'Gerät verbunden' : 'Gerät getrennt';
};

const button = document.querySelector('#choose');
button.addEventListener('click', async () => {
  // requestPort() braucht eine Nutzeraktion
  const port = await navigator.serial.requestPort();
  renderStatus(port);

  port.addEventListener('connect', () => renderStatus(port));
  port.addEventListener('disconnect', () => renderStatus(port));
});

Bluetooth-Port: warten, bis das Gerät in Reichweite ist

const waitForConnection = (port) =>
  port.connected
    ? Promise.resolve()
    : new Promise((resolve) =>
        port.addEventListener('connect', resolve, { once: true })
      );

const [port] = await navigator.serial.getPorts();
if (port) {
  console.log('Verbunden?', port.connected);
  await waitForConnection(port);
  await port.open({ baudRate: 9600 });
  console.log('Bereit zum Senden');
}

Verbunden? false Bereit zum Senden

// Wichtig · Fallstricke

Nicht dasselbe wie „geöffnet“: connected === true heißt nicht, dass port.readable oder port.writable verfügbar sind. Dafür muss der Port erst mit open() geöffnet werden. Umgekehrt ist ein geöffneter Port nach einer Trennung nicht mehr nutzbar, und laufende Lese- oder Schreibvorgänge schlagen fehl.
Nur ein Momentwert: Der Wert kann sich jederzeit ändern, zum Beispiel wenn das Kabel abgezogen wird oder das Bluetooth-Gerät außer Reichweite gerät. Statt die Eigenschaft regelmäßig abzufragen, sollte man auf die Events connect und disconnect reagieren.
Kompatibilität: Die Web Serial API ist experimentell und funktioniert nur in Chromium-basierten Desktop-Browsern. Firefox und Safari unterstützen sie nicht. Die Eigenschaft connected kam erst nach der eigentlichen API hinzu, ältere Chromium-Versionen liefern daher undefined. Prüfe sie deshalb mit 'connected' in SerialPort.prototype.
Nur sicherer Kontext: Die API gibt es nur unter HTTPS oder localhost. Außerdem kann eine Permissions Policy (serial) sie sperren, zum Beispiel in iframes.

Siehe auch

SerialPort SerialPort.open() SerialPort.getInfo() Serial.getPorts() Serial.requestPort()