SerialPort.setSignals() — Methode · JavaScript-Referenz

Signatur

SerialPort.prototype.setSignals(options)

Beschreibung

Mit setSignals() steuerst du die Hardware-Steuerleitungen einer seriellen Schnittstelle, die über die Web Serial API geöffnet wurde. Du kannst damit Data Terminal Ready (dataTerminalReady, DTR), Request To Send (requestToSend, RTS) und den Break-Zustand (break) einzeln ein- oder ausschalten.

Gebraucht wird das vor allem bei Mikrocontrollern und Entwicklungsboards. Viele Arduino- und ESP32-Boards lassen sich über DTR/RTS zurücksetzen oder in den Bootloader schalten. Außerdem kann Software damit selbst eine Flusskontrolle umsetzen oder ein Break-Signal senden, etwa bei LIN- oder DMX-Protokollen.

Du musst nur die Signale angeben, die du ändern willst. Nicht angegebene Signale behalten ihren aktuellen Zustand. Der Port muss vorher mit open() geöffnet worden sein. Den Zustand der Eingangsleitungen (CTS, DSR, DCD, RI) liest du mit getSignals() aus.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Objekt mit den Signalen, die gesetzt werden sollen. Alle Felder sind optional; nicht angegebene Signale bleiben unverändert.
$options.dataTerminalReady	boolean		`true` setzt die DTR-Leitung aktiv, `false` setzt sie inaktiv.
$options.requestToSend	boolean		`true` setzt die RTS-Leitung aktiv, `false` setzt sie inaktiv.
$options.break	boolean		`true` startet einen Break-Zustand (die Sendeleitung bleibt dauerhaft auf Low), `false` beendet ihn.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Signale gesetzt sind. Es wird mit einer DOMException abgelehnt, zum Beispiel mit InvalidStateError, wenn der Port nicht geöffnet ist, oder mit NetworkError, wenn die Signale nicht gesetzt werden konnten.

Beispiele

Arduino per DTR zurücksetzen

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const resetButton = document.querySelector('#reset');
resetButton.addEventListener('click', async () => {
  // Muss durch eine Nutzeraktion ausgelöst werden
  const port = await navigator.serial.requestPort();
  await port.open({ baudRate: 115200 });

  // DTR kurz deaktivieren und wieder aktivieren: löst den Reset aus
  await port.setSignals({ dataTerminalReady: false });
  await sleep(100);
  await port.setSignals({ dataTerminalReady: true });
  console.log('Board zurückgesetzt');
});

Board zurückgesetzt

ESP32 in den Bootloader-Modus versetzen

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

// Erwartet einen bereits geöffneten Port
const enterBootloader = async (port) => {
  // Übliche Beschaltung: DTR -> GPIO0, RTS -> EN (invertiert)
  await port.setSignals({ dataTerminalReady: false, requestToSend: true }); // EN low = Reset
  await sleep(100);
  await port.setSignals({ dataTerminalReady: true, requestToSend: false }); // GPIO0 low, EN high
  await sleep(50);
  await port.setSignals({ dataTerminalReady: false }); // GPIO0 wieder freigeben
  console.log('Bootloader aktiv');
};

Bootloader aktiv

Break-Signal senden und Fehler abfangen

const sendBreak = async (port, durationMs = 50) => {
  try {
    await port.setSignals({ break: true });
    await new Promise((r) => setTimeout(r, durationMs));
    await port.setSignals({ break: false });
    console.log(`Break für ${durationMs} ms gesendet`);
  } catch (err) {
    // z. B. InvalidStateError, wenn der Port nicht geöffnet ist
    console.error(`${err.name}: ${err.message}`);
  }
};

const [port] = await navigator.serial.getPorts();
if (port) {
  await port.open({ baudRate: 9600 });
  await sendBreak(port);
}

Break für 50 ms gesendet

// Wichtig · Fallstricke

Browser-Unterstützung: Die Web Serial API gibt es nur in Chromium-Browsern auf dem Desktop (Chrome und Edge ab Version 89, Opera). Firefox und Safari unterstützen sie nicht, Chrome für Android nur eingeschränkt. Prüfe die Unterstützung vorher mit 'serial' in navigator.
Die API funktioniert nur in einem sicheren Kontext (HTTPS oder localhost). Sie kann außerdem über die Permissions Policy serial gesperrt sein, zum Beispiel in iframes.
Rufst du setSignals() vor open() oder nach close() auf, wird das Promise mit InvalidStateError abgelehnt.
Ob ein Signal am Stecker als High oder Low ankommt, hängt vom USB-Seriell-Wandler ab. Viele Chips (z. B. FTDI, CH340, CP210x) arbeiten mit invertierter Logik. Prüfe deshalb immer den Schaltplan deines Boards.
Manche Betriebssysteme oder Treiber setzen DTR/RTS schon beim Öffnen des Ports automatisch. Das kann ein Board ungewollt zurücksetzen.
Wie lange ein Break dauert, bestimmst du selbst mit einem Timer. Die tatsächliche Dauer ist daher nicht exakt.
Rufe die Methode mit await auf, damit die Signalwechsel in der richtigen Reihenfolge ankommen. Bei Reset-Abläufen ist das Timing entscheidend.

Siehe auch

SerialPort SerialPort.getSignals() SerialPort.open() SerialPort.close() Serial.requestPort() Serial.getPorts() CSSPrimitiveValue.setStringValue()