Firmware & Flash

Five tools handle the end of the build pipeline — listing what firmware is available, downloading it, flashing it to a real device, capturing serial output from the device after flash, and (for JTAG debugging) fetching the unstripped application ELF.

firmware.list

Shows which builds have finished successfully and have firmware you can download.

Input:

{}

Optionally filter by a specific build:

{ "job_id": "0abf...e2" }

Returns:

{
  "builds": [
    {
      "task_id": "0abf...e2",
      "target": "esp32s3",
      "status": "succeeded",
      "build_type": "release"
    }
  ]
}

No side effects. Safe to call any time.

firmware.download

Gets the metadata you need to download a build’s firmware. The actual binary transfer happens over the firmware WebRTC DataChannel — this tool gives you the artifact information.

Input:

{
  "job_id": "0abf...e2"
}

Returns:

{
  "job_id": "0abf...e2",
  "status": "succeeded",
  "artifact_lines": [
    "build/flash_bundle.tar.gz",
    "build/bootloader.bin",
    "build/partition_table/partition-table.bin",
    "build/<project>.bin"
  ],
  "output_dir": "/tmp/firmware"
}

The build must have status succeeded. Calling this on a failed or running build returns an error.

Primary artifact is flash_bundle.tar.gz. Remote builds assemble a signed, self-describing flash bundle (manifest.json + files/ containing bootloader, partition table, and app segments) and return it to the client in the same session — there is no separate fetch step. This is what flash.run and the CLI espctl flash both consume. The individual .bin files are still in the listing for inspection, but you almost never pass them to the flasher directly.

elf.download

Downloads the unstripped application ELF for a previously-completed remote C ESP-IDF build. Used to drive openocd-esp32 + xtensa-esp32sX-elf-gdb for JTAG-level debugging — breakpoints, register inspection, RTOS thread view. The flash bundle (flash_bundle.tar.gz) only carries flashable segments; debug symbols live in the ELF, which is auto-persisted on the agent next to the bundle and fetched on demand.

Input:

{
  "build_id": "0abf...e2",
  "output_path": "/tmp/my_proj.elf",
  "control_url": "https://esphome.cloud"
}

Returns:

{
  "build_id": "0abf...e2",
  "path": "/tmp/my_proj.elf",
  "size_bytes": 11230544,
  "sha256": "f0a63ee2...",
  "next_steps": "Use this ELF with openocd-esp32 + xtensa-esp32sX-elf-gdb."
}

Requires MCP_AUTH_SECRET in the environment (used as a Bearer token for /mcp-session). Reuses the WebRTC firmware DataChannel and the same chunked transport (FirmwareMetadataEnvelope → N×FirmwareChunkEnvelope → FirmwareCompleteEnvelope) as flash_bundle.tar.gz delivery.

Rust no_std builds have no companion ELF on the agent. Builds submitted via espctl build --rust-elf use the ELF as the input — you already have it locally. elf.download returns an error for those build_ids.

Persistence is per-workspace. The agent stores ELFs under <ESPCTL_WORKSPACE_ROOT>/<build_id>/<app>.elf (server-side path). Workspaces are GC’d periodically; very old build_ids may no longer be retrievable.

flash.run

Flashes firmware to an ESP device connected to your computer’s USB port. Uses the pure-Rust espflash library directly — no Python esptool.py dependency. You do not need to pip install esptool, run a venv, or have Python in your PATH.

Input:

{
  "firmware_path": "/path/to/build/flash_bundle.tar.gz",
  "port": "/dev/ttyUSB0",
  "baud": 460800
}

Returns: Status of the flash operation (success or error with details).

When given a bundle, flash.run reads manifest.json, verifies every segment’s sha256, and writes all segments to flash in a single espflash session (critical — per-segment writes would reboot the chip between segments and hang). The chip reboots once at the end.

Policy: never install esptool.py. If flash.run or the CLI espctl flash fails, file a bug report at docs/espctl-flash-bugs-YYYY-MM-DD.md in the aegis repo following the pattern of docs/infra-bugs-2026-04-11.md. Do NOT work around the failure by installing Python esptool — that silently hides real bugs in the build-to-flash pipeline.

Local only. This tool runs on your computer, not on the build server. It only works in local/stdio MCP mode — not in the browser. For browser flashing, use the Flash tab in the MCP Console.

monitor.run

Captures serial output from a connected ESP device for a bounded duration. Used right after flash.run to verify a board boots and is running the firmware you just wrote — for example, watching for the 1 Hz heartbeat log line emitted by the wizard’s Phase-0 verification firmware.

Input:

{
  "port": "/dev/cu.usbmodem1101",
  "baud": 115200,
  "duration_sec": 30,
  "filter": "heartbeat",
  "reset_on_connect": true
}

Returns:

{
  "success": true,
  "port": "/dev/cu.usbmodem1101",
  "baud": 115200,
  "duration_ms": 30024,
  "bytes_read": 18432,
  "lines_captured": 32,
  "output": "I (123) heartbeat: tick 0\nI (1234) heartbeat: tick 1\n...",
  "truncated": false,
  "message": "Captured 18432 byte(s) over 30024 ms from /dev/cu.usbmodem1101 at 115200 baud."
}

The capture buffer is bounded at ~512 KB; if the device produces more than that within the window, truncated is true and the tail is dropped.

Local only. Like flash.run, this only works in local/stdio MCP mode — not in the browser. Browser monitoring uses Web Serial via the MCP Console — Monitor tab.

No panic decoder. This is a raw UTF-8-lossy byte dump. It does not have idf.py monitor’s ELF-aware backtrace decoding. For long interactive monitoring use the CLI espctl monitor instead.

CLI: espctl ports

Lists every serial port the OS exposes. USB ports include their VID:PID. Run this first to find your board.

espctl ports

No flags. An empty list prints No serial ports found.

Output

Human mode (table):

PORT                           TYPE            USB VID:PID
----------------------------------------------------------------------
/dev/cu.usbmodem1101           USB             303A:1001
/dev/cu.Bluetooth-Incoming-... Bluetooth       -

JSON (--json): an array of port objects. USB entries also carry vid, pid, vid_pid, manufacturer, product, serial_number.

# Filter to USB serial adapters
espctl --json ports | jq '.[] | select(.vid_pid != null)'

CLI: espctl probe

Opens the bootloader handshake against a real device and reports the chip type (with revision), MAC address, and flash size. Uses the same pure-Rust espflash connection as espctl flash — no Python esptool.py.

espctl probe --port <port>

Inputs

Output

Human mode:

Port:       /dev/cu.usbmodem1101
Chip:       ESP32-S3 (revision v0.2)
MAC:        7c:df:a1:00:11:22
Flash size: 8MB

JSON (--json):

{
  "port": "/dev/cu.usbmodem1101",
  "chip_type": "ESP32-S3 (revision v0.2)",
  "mac_address": "7c:df:a1:00:11:22",
  "flash_size": "8MB"
}

Failure modes

• Port not in the OS port list → exit 1 (with a hint to run espctl ports).
• Bootloader handshake fails → exit 1.

CLI: espctl flash

Flashes a bundle to a connected device. The MCP equivalent is flash.run — same engine, same single-session writeback.

espctl flash <bundle_path> --port <port> [--baud <rate>]

Flag matrix

Examples

# Default baud (460800)
espctl flash ./build/flash_bundle.tar.gz --port /dev/cu.usbmodem1101

# Faster — if your USB↔serial adapter and cable can keep up
espctl flash ./build/flash_bundle.tar.gz --port /dev/ttyUSB0 --baud 921600

The bundle form (produced by espctl build) carries manifest.json with sha256 checksums plus all segments (bootloader, partition table, app). The flasher writes them in one espflash session — per-segment writes would reboot the chip between segments and hang.

CLI: espctl monitor

Opens a serial monitor on a device and streams output to your terminal. Auto-reconnects on disconnect by default.

espctl monitor --port <port> [--baud <rate>] \
               [--no-reconnect] [--no-reset-on-connect]

Flag matrix

About --no-reset-on-connect

By default, monitor pulses RTS once on open so the chip boots into the application under the monitor. Use --no-reset-on-connect on boards without an auto-reset circuit, or when another tool has already reset the chip and you don’t want a second reset to interrupt boot.

Typical flow

Remote builds plus local flash and monitor:

espctl build . --target esp32s3
espctl flash ./build/flash_bundle.tar.gz --port /dev/cu.usbmodem*
espctl monitor --port /dev/cu.usbmodem*

The build step is remote by default — no --remote flag needed. The server URL comes from espctl login or defaults to https://esphome.cloud. Use --remote <url> to override, or --local for plan-only.

CLI: espctl elf

Downloads the unstripped application ELF for a previous remote build. The MCP equivalent is elf.download — same transport, same auth flow.

Opt-in at build time. The agent does NOT retain ELFs by default — a multi-MB write per job adds up fast. To make the ELF fetchable later, pass --elf to espctl build (the flag sets BuildRequest.persist_elf = true on the wire). Builds that ran without --elf have no ELF on the agent; espctl elf will return “no ELF retained” against them.

espctl elf --build-id <ID> [--remote <URL>] [--out <PATH>]

Flag matrix

Typical flow — JTAG debug via openocd-esp32

# 1. Build remotely **with --elf** so the agent keeps the ELF; note the
#    build_id printed in the output.
espctl build composite-device/firmware/my_proj --target esp32s3 \
    --remote https://esphome.cloud --elf
# build_id=4f3a2c...

# 2. Fetch the ELF (mirrors `espctl build --remote` auth precedence:
#    MCP_AUTH_SECRET env var → ~/.config/espctl/credentials.json).
espctl elf --build-id 4f3a2c --remote https://esphome.cloud --out my_proj.elf

# 3. Drive openocd-esp32 + GDB yourself — espctl stays out of the way.
openocd -f board/esp32s3-builtin.cfg -c 'gdb_port 3333'
xtensa-esp32s3-elf-gdb -ex 'target remote :3333' my_proj.elf

The openocd-esp32 board configs (board/esp32s3-builtin.cfg, board/esp32-wrover-kit-3.3v.cfg, etc.) work with any standard JTAG adapter — common rigs include the chip’s built-in USB-Serial/JTAG (S3/C3 and later) or external FTDI-based debuggers like the ESPLink V1.2, which exposes UART and JTAG on independent USB endpoints (so JTAG keeps working after DIS_USB_JTAG is burned).

Failure modes. espctl elf returns an error if: the build was made without --elf (agent skipped the ELF copy on purpose), the build_id is unknown to the agent, the build has been GC’d from the agent workspace, or the build was a Rust no_std build (no companion ELF — use the local ELF you already have).

See also

• Build Lifecycle — how to start a build that produces firmware.
• Logs & Artifacts — reading build output and manifest files.
• MCP Console — Flash tab — browser-based flashing.