Events

AbstractSerialDevice<T> emits the following typed events. All are prefixed with serial: to avoid collisions with DOM events.

Event reference

serial:connecting

Fired immediately when connect() is called, before the port picker appears.

device.on("serial:connecting", () => {
  connectButton.disabled = true;
});

Payload: none

---

serial:connected

Fired after the port is open and handshake() returns true.

device.on("serial:connected", () => {
  console.log("Ready to communicate!");
});

Payload: none

---

serial:disconnected

Fired after the port closes, for any reason (manual disconnect, error, device unplugged). If autoReconnect is enabled, a reconnect attempt follows.

device.on("serial:disconnected", () => {
  console.log("Connection lost.");
});

Payload: none

---

serial:data

Fired every time the parser emits a complete message.

device.on("serial:data", (value) => {
  // `value` is typed as T (e.g. string when using delimiter())
  console.log("Received:", value);
});

Payload: T — the parsed value

---

serial:sent

Fired after bytes are written to the port.

device.on("serial:sent", (bytes) => {
  console.log("Sent:", bytes);
});

Payload: Uint8Array — the exact bytes written

---

serial:error

Fired when an unrecoverable error occurs (port error, write failure, etc.).

device.on("serial:error", (error) => {
  console.error("Serial error:", error.message);
});

Payload: Error

---

serial:need-permission

Fired when the user denies port access or no authorized ports are available. This is the right place to re-enable your "Connect" button.

device.on("serial:need-permission", () => {
  connectButton.disabled = false;
});

Payload: none

---

serial:timeout

Fired when a queued command does not complete within commandTimeout ms.

device.on("serial:timeout", (command) => {
  console.warn("Command timed out:", command);
});

Payload: Uint8Array — the bytes of the command that timed out

---

serial:queue-empty

Fired when the last command in the queue finishes and the queue becomes idle.

device.on("serial:queue-empty", () => {
  console.log("All commands sent.");
});

Payload: none

---

serial:reconnecting

Fired at the start of each auto-reconnect attempt.

device.on("serial:reconnecting", () => {
  statusLabel.textContent = "Reconnecting...";
});

Payload: none

---

TypeScript: full event map

import type { SerialEventMap } from "webserial-core";

// SerialEventMap<T> is:
interface SerialEventMap<T> {
  "serial:connecting": () => void;
  "serial:connected": () => void;
  "serial:disconnected": () => void;
  "serial:data": (value: T) => void;
  "serial:sent": (data: Uint8Array) => void;
  "serial:error": (error: Error) => void;
  "serial:need-permission": () => void;
  "serial:timeout": (command: Uint8Array) => void;
  "serial:queue-empty": () => void;
  "serial:reconnecting": () => void;
}