v0.1.1

Quick start

Install the tools, create an esp-hal project and run it on a board, with what each step prints.

This page takes you from an installed espx binary to a board printing its boot log. If you have not built espx yet, start with Installation. You need one ESP32 dev board on a USB data cable. The examples use an ESP32-C6, the default chip.

Install the tools

espx setup

setup reads the tool manifest, downloads each tool it lacks, then adds rust-src and the RISC-V targets:

=> reading the tools manifest
=> downloading espflash 4.5.0 (…)
ok espflash 4.5.0
=> downloading cargo-espflash 4.5.0 (…)
ok cargo-espflash 4.5.0
=> downloading esp-generate 1.3.0 (…)
ok esp-generate 1.3.0
=> adding the rust-src component (rustup component add rust-src)
ok rust-src
=> adding Rust targets (rustup target add riscv32imac-unknown-none-elf riscv32imc-unknown-none-elf)
ok riscv32imac-unknown-none-elf, riscv32imc-unknown-none-elf
ok ready for esp32c2, esp32c3, esp32c5, esp32c6, esp32c61, esp32h2 (tools in /home/you/.espx/bin)

Lines starting with => are progress on stderr. Lines starting with ok are results on stdout. Run it again and each tool and target says already installed instead.

Create a project

espx new blinky

espx runs esp-generate --headless for the ESP32-C6 with the log option, then writes a README and an AGENTS.md:

=> creating blinky for the ESP32-C6 with esp-generate
…esp-generate's own output…
ok created /home/you/blinky
ok wrote AGENTS.md: the espx loop, the board's pins and the esp-hal version for coding agents
ok next: cd blinky && espx run

For another chip, pass --chip esp32c3 or any id from espx chips. For a known dev board, pass --board xiao-esp32c6 and espx picks its chip and records its pins. Projects covers the options.

Plug in the board and look for it

espx devices

devices lists the serial ports with a dev board on them, with the USB interface (native USB, or a CP210x, CH34x, FTDI or PL2303 bridge) and any name you gave the board. With exactly one board attached, every command finds it on its own.

Build, flash and watch

cd blinky
espx run

espx builds with cargo build --release, prints the image size against the app partition, then hands the terminal to cargo espflash flash --release --monitor:

=> image 64 KB of a 3.9 MB app partition (1%), 12 KB of static RAM
=> building, flashing and monitoring blinky for the ESP32-C6 on /dev/cu.usbmodem101 (Ctrl+R resets, Ctrl+C exits)

espflash writes the bootloader, partition table and app, resets the board and shows its serial output. After the ROM banner and the second-stage bootloader's lines, the template logs INFO - Hello world!. Press Ctrl+R to reset the board and Ctrl+C to exit. The image size above is illustrative; yours depends on the template and the chip.

Run it unattended

Add --until and --timeout and espx reads the port itself, waits for a line and exits:

espx run --until 'Hello world!' --timeout 1m

It exits 0 on the first matching line and 124 if the minute runs out. The same flags work on espx monitor, and --json prints one JSON event per line. See Scripts and CI.

When something goes wrong

  • no board found: nothing with a known USB serial interface is attached. Check the cable carries data, then run espx devices --all to list every serial port.
  • several boards are connected: pass --port with a port, a board id or a board name, or bind the project to one board. See Boards and ports.
  • needs a person: above the error: espx could not get the bootloader to answer, also at 115200 baud. Hold BOOT, tap RESET, release BOOT, and flash again. If the line says the board is not on the USB bus, replug it.
  • A build error: espx prints cargo's diagnostics exactly as cargo would. Fix them and run again.

Next