espcdcflash

espcdcflash is an opiniated WebSerial flasher for ESP32-S3 firmware in the browser.
It is designed for USB CDC flashing flows with a small, stateless API: isSupported(), inspect(input?), and flash(input, options?).

Requirements

• Chromium browser with WebSerial support (Chrome/Edge).
• Secure context (https:// or http://localhost).
• ESP32-S3 target and compatible firmware image(s).

Install

npm install espcdcflash

import { flash, inspect, isSupported } from "espcdcflash";

Quick Start (minimal)

import { flash } from "espcdcflash";

// No port passed: flash() will open the web serial picker.
// Plain file input defaults to memory offset 0x10000.
const report = await flash(file);

if (!report.ok) {
  console.error(report.error);
} else {
  console.log("Flash successful.");
}

Passing a plain firmware file (File/Uint8Array) to flash assumes the app start address 0x10000.
Use an Image object ({ file, address }) to set a different address.

Optional explicit browser/context guard:

import { isSupported } from "espcdcflash";

if (!isSupported()) {
  throw new Error("WebSerial is unavailable in this browser/context.");
}

Preflight Validation with inspect

Use inspect to validate one or more firmware inputs before flashing.

import { inspect } from "espcdcflash";

const report = await inspect(file);

if (!report.ok) {
  console.error(report.error);
}

for (const item of report.items) {
  console.log(item.index, item.ok, item.address, item.chipId, item.error);
}

Notes:

• inspect() with no argument returns a non-OK report.
• inspect is preflight sanity checking, not a guarantee for all target-specific runtime conditions.

Progressive Usage Examples

A) File input (defaults to memory offset 0x10000)

const report = await flash(file);

B) Explicit single image object

const report = await flash({
  file,
  address: 0x10000,
});

C) Multiple images

const report = await flash([
  { file: bootloaderBin, address: 0x0000 },
  { file: partitionsBin, address: 0x8000 },
  { file: appBin, address: 0x10000 },
]);

For image arrays, ranges must not overlap. Range checks use 4-byte padded image size (same as flash write behavior).

// Valid adjacency (no overlap): first image length 33 -> padded to 36 bytes.
await flash([
  { file: first33Bytes, address: 0x10000 }, // [0x10000, 0x10024)
  { file: second, address: 0x10024 },       // starts exactly at previous end
]);

// Invalid overlap:
await flash([
  { file: first33Bytes, address: 0x10000 }, // [0x10000, 0x10024)
  { file: second, address: 0x10020 },       // overlaps previous range
]);

D) Full options with events

const report = await flash(file, {
  port, // optional
  baud: 115200,
  touch1200: true,
  onEvent: (event) => {
    if (event.type === "message") {
      console.log("[message]", event.message);
      return;
    }
    if (event.type === "progress") {
      console.log("[progress]", event.progress.stage, event.progress.percent, event.progress.message);
      return;
    }
    console.log("[report]", event.report);
  },
});

E) Cancellation with AbortController

const abort = new AbortController();

const run = flash(file, {
  signal: abort.signal,
});

// Later:
abort.abort();

const report = await run;
console.log(report);

Full API Reference

export type Stage =
  | "touch"
  | "rebind"
  | "connect"
  | "write"
  | "reset"
  | "done"
  | "error";

export type Firmware = File | Uint8Array;

export interface Image {
  file: Firmware;
  address?: number;
}

export type Input = Firmware | Image | Image[];

export interface Progress {
  stage: Stage;
  percent: number;
  message: string;
}

export interface Report {
  ok: boolean;
  error?: string;
}

export interface InspectItem {
  index: number;
  ok: boolean;
  size: number;
  address: number;
  chipId?: number;
  error?: string;
}

export interface InspectReport {
  ok: boolean;
  items: InspectItem[];
  error?: string;
}

export type Event =
  | { type: "message"; message: string }
  | { type: "progress"; progress: Progress }
  | { type: "report"; report: Report };

export interface Options {
  port?: SerialPort;
  baud?: number;
  touch1200?: boolean;
  signal?: AbortSignal;
  onEvent?: (event: Event) => void;
}

export function isSupported(): boolean;
export function inspect(input?: Input): Promise<InspectReport>;
export function flash(input: Input, options?: Options): Promise<Report>;

Options & Behavior

| Option | Type | Default | Behavior | |---|---|---|---| | port | SerialPort | none | If omitted, flash() opens the WebSerial chooser. | | baud | number | 115200 | Positive integer UART baud used for flashing transport. | | touch1200 | boolean | true | Runs 1200-baud touch reset flow before connect. | | signal | AbortSignal | none | Cooperative cancellation for the current run. | | onEvent | (event: Event) => void | none | Receives message/progress/report events during a run. |

Address precedence:

1. image.address (per item in Input)
2. default 0x10000 (app start address assumption for plain file input)

For image arrays:

• Ranges must not overlap.
• Collision checks use padded size (size rounded up to 4-byte alignment).

Event Flow

Typical successful stage progression:

touch -> rebind -> connect -> write -> reset -> done

On failure, stage error is emitted.

Notes:

• Progress percentages are stage-oriented UX signals, not exact end-to-end byte percentages.
• event.type === "report" is terminal and mirrors the returned Report from flash().

Error Handling Guide

Common failure categories:

• Unsupported browser/context (no WebSerial or not secure context).
• Permission denied / chooser canceled.
• Serial busy or restarting.
• Sync/connect timeout.
• Invalid firmware image (bad magic/header/chip ID mismatch).

Recommended handling pattern:

const report = await flash(file, { onEvent: console.log });

if (!report.ok) {
  // Treat this as the source of truth for run outcome.
  console.error(report.error);
}

UI Integration: File Picker + Serial Port Selection

Manual port selection flow

<input id="firmware" type="file" accept=".bin,application/octet-stream" />
<button id="select-port">Select Port</button>
<button id="flash" disabled>Flash</button>
<p id="status">Idle</p>

<script type="module">
  import { flash, isSupported } from "espcdcflash";

  const fileInput = document.getElementById("firmware");
  const portBtn = document.getElementById("select-port");
  const flashBtn = document.getElementById("flash");
  const status = document.getElementById("status");

  let file = null;
  let port = null;
  let busy = false;

  function updateUi() {
    flashBtn.disabled = busy || !file || !port;
    portBtn.disabled = busy || !isSupported();
  }

  fileInput.addEventListener("change", () => {
    file = fileInput.files?.[0] ?? null;
    updateUi();
  });

  portBtn.addEventListener("click", async () => {
    try {
      if (!isSupported()) throw new Error("WebSerial unavailable.");
      port = await navigator.serial.requestPort({});
      status.textContent = "Port selected.";
      updateUi();
    } catch (error) {
      status.textContent = error instanceof Error ? error.message : String(error);
    }
  });

  flashBtn.addEventListener("click", async () => {
    if (!file || !port || busy) return;
    busy = true;
    updateUi();
    status.textContent = "Flashing...";

    try {
      const report = await flash(file, {
        port,
        onEvent: (event) => {
          if (event.type === "progress") status.textContent = event.progress.message;
        },
      });
      status.textContent = report.ok ? "Done." : `Failed: ${report.error ?? "Unknown error"}`;
    } finally {
      busy = false;
      updateUi();
    }
  });

  updateUi();
</script>

Auto chooser flow (no manual port selection)

const report = await flash(file, {
  onEvent: (event) => {
    if (event.type === "progress") {
      console.log(event.progress.message);
    }
  },
});

// If no port was provided, flash() prompts for one.
console.log(report);

Limitations / Non-goals

• ESP32-S3 only.
• WebSerial only (Chromium secure context required).
• Browser runtime only (not Node.js).
• inspect validates firmware format/chip targeting, but is not a full target safety proof.

Attribution

espcdcflash is a focused/narrower alternative to generic flashing stacks and aims to mimic practical esptool.py flashing behavior for USB CDC usage.
Vendored stub data: src/stub/esp32s3.stub.json (from esptool-js, Apache-2.0).
See THIRD_PARTY_NOTICES.md and LICENSE.md.