v0.1.1

Introduction

espx installs the esp-rs tools, creates esp-hal projects, and builds, flashes and monitors your ESP32.

espx is Rust on ESP32 with zero setup. One binary installs the esp-rs tools, scaffolds a bare-metal esp-hal project, then builds, flashes and monitors your board.

espx setup        # tools into ~/.espx/bin, RISC-V targets into rustup
espx new blinky   # an esp-hal project for the ESP32-C6
cd blinky
espx run          # build, flash and open the serial monitor

With one board connected you never pass a port.

Three surfaces, one core

espx is one core with three interfaces on top of it. They share the same board handling, so a board that one of them has open is reachable from the others.

SurfaceWhat it doesStart it with
The espx commandEvery feature as a terminal command. Headless by default, with --json output for scripts and CIespx --help
The desktop appA window for your projects, attached boards, serial output, recordings and AI agent clientscargo run -p espx-desktop in the espx repository
The MCP serverThe build, flash and monitor loop as tools for coding agents such as Claude Code, Cursor and Codexespx mcp

What espx installs

espflash 4.5.0cargo-espflash 4.5.0esp-generate 1.3.0234SHA-256 checkedmust match to go in1~/.espx/bin5
  1. 1SHA-256 checked must match to go in
  2. 2espflash 4.5.0
  3. 3cargo-espflash 4.5.0
  4. 4esp-generate 1.3.0
  5. 5~/.espx/bin
$ espx setup$ espx uninstall --allespflash 4.5.0 · sha-256 okcargo-espflash 4.5.0 · sha-256 okesp-generate 1.3.0 · sha-256 ok3 binaries · nothing in ~/.cargo/binremoving ~/.espx~/.espx removed

espx setup downloads pinned binaries into ~/.espx/bin and adds the Rust pieces through rustup.

ToolVersionRoleWhere
espflash4.5.0list ports, board info, flash, erase, monitor~/.espx/bin/espflash
cargo-espflash4.5.0build and flash in one step~/.espx/bin/cargo-espflash
esp-generate1.3.0scaffold a project from the current esp-hal template~/.espx/bin/esp-generate
rust-src, RISC-V targetsrustup-managedriscv32imc-unknown-none-elf, riscv32imac-unknown-none-elf~/.rustup

Only when you ask for an Xtensa chip (esp32, esp32s2, esp32s3):

ToolVersionRoleWhere
espup0.17.1installs Espressif's Rust fork~/.espx/bin/espup
esp toolchainwhat espup shipsXtensa-capable rustc, clang and GCC linker, about 1 GB~/.rustup/toolchains/esp, ~/.espup
export filewritten by espupLIBCLANG_PATH and PATH for the fork~/.espx/export-esp.sh

Every binary is checked against the SHA-256 in the tool manifest before it is written to disk. Nothing goes into ~/.cargo/bin. Set ESPX_HOME to keep everything somewhere other than ~/.espx, and run espx uninstall --all to take it all back out.

What espx never does

espx never reimplements the toolchain. A build is cargo build --release, a flash is cargo espflash flash --release, a new project is esp-generate --headless, and targets come from rustup target add. espx fills in the flags and tells you which command it runs:

=> building blinky for the ESP32-C6 (cargo build --release)

The one part espx does itself is the serial monitor when you script it. Reading the port directly lets espx decode defmt frames, name the reason for each boot, resolve panics to source lines and share one board between several processes. Monitor and replay explains when that happens.

Two more rules hold everywhere:

  • No command waits for input unless you pass -i. Every choice is a flag, and a missing choice is an error that names the flag.
  • Builds are always --release. A debug esp-hal binary is slow and often too big to flash.

Platforms

espx runs on Apple silicon macOS and on Linux (arm64 or x86_64). The tool mirror ships no build for Intel Macs, so espx setup stops with an unsupported_platform error there.

It supports every chip esp-generate can scaffold: the ESP32, ESP32-S2 and ESP32-S3 (Xtensa), and the ESP32-C2, C3, C5, C6, C61 and H2 (RISC-V). The C5 and C61 are marked preview. Chips and boards has the full table.

Next steps