A template for a "Hello, world!" Rust binary crate for the ESP-IDF framework. Based on cargo-generate.
This is the crate you get when running cargo new
, but augmented with extra configuration so that it does build for the ESP32[XX] with ESP-IDF and (by default) with STD support.
Or if you rather
idf.py
CMake project - follow these instructionsFor more check out the links in the additional information section
Please make sure you have installed all prerequisites first!
cargo generate esp-rs/esp-idf-template cargo
The command will display a few prompts:
Project Name
: Name of the crate.Which MCU to target?
: SoC model, e.g. esp32
, esp32s2
, esp32c3
etc.Configure advanced template options?
: If false
, skips the rest of the prompts and uses their default value. If true
, you will be prompted with:
Enable STD support?
: When true
(default), adds support for the Rust Standard Library. Otherwise, a no_std
Rust Core Library crate would be created.ESP-IDF Version
: ESP-IDF branch/tag to use. Possible choices:v4.4
: Stablev5.1
: Stablemaster
: UnstableConfigure project to support Wokwi simulation with Wokwi VS Code extension?
: Adds support for Wokwi simulation using VS Code Wokwi extension.Configure project to use Dev Containers (VS Code and GitHub Codespaces)?
: Adds support for:
cd <your-project-name>
cargo build
<your-project-name>
with the name of the generated projectIn the root of the generated project:
espflash flash target/<mcu-target>/debug/<your-project-name>
MCU | Target |
---|---|
ESP32 | xtensa-esp32-espidf |
ESP32-S2 | xtensa-esp32s2-espidf |
ESP32-S3 | xtensa-esp32s3-espidf |
ESP32-C2 | riscv32imc-esp-espidf |
ESP32-C3 | riscv32imc-esp-espidf |
ESP32-C6 | riscv32imac-esp-espidf |
ESP32-H2 | riscv32imac-esp-espidf |
ESP32-P4 | riscv32imafc-esp-espidf |
espflash
will print a list of the recognized USB ports for you to select
the desired port, if it detectes multiple boards.<your-project-name>
with the name of the generated project--monitor
argument to the espflash
command to open a serial monitor after flashing the device.espflash
usage see the READMEespflash monitor /dev/ttyUSB0
dev/ttyUSB0
above with the USB port where you've connected the board. If you do not
specify any USB port, cargo-espflash
/espflash
will print a list of the recognized USB ports for you to select
the desired port.The monitor should output more or less the following:
Opening /dev/tty.usbserial-0001 with speed 115200
Resetting device... done
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
configsip: 0, SPIWP:0xee
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
mode:DIO, clock div:2
load:0x3fff0048,len:12
ho 0 tail 12 room 4
load:0x3fff0054,len:4800
load:0x40078000,len:17448
load:0x4007c428,len:4840
entry 0x4007c6a0
I (178) cpu_start: Pro cpu up.
I (178) cpu_start: Starting app cpu, entry point is 0x4008115c
I (0) cpu_start: App cpu up.
I (193) cpu_start: Pro cpu start user code
I (193) cpu_start: cpu freq: 160000000
I (193) cpu_start: Application information:
I (197) cpu_start: Project name: esp-idf
I (202) cpu_start: App version: f08dcd7
I (207) cpu_start: Compile time: Oct 23 2021 14:48:03
I (213) cpu_start: ELF file SHA256: 0000000000000000...
I (219) cpu_start: ESP-IDF: 4.3.0
I (224) heap_init: Initializing. RAM available for dynamic allocation:
I (231) heap_init: At 3FFAE6E0 len 00001920 (6 KiB): DRAM
I (237) heap_init: At 3FFB3498 len 0002CB68 (178 KiB): DRAM
I (243) heap_init: At 3FFE0440 len 00003AE0 (14 KiB): D/IRAM
I (250) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
I (256) heap_init: At 4008C538 len 00013AC8 (78 KiB): IRAM
I (263) spi_flash: detected chip: generic
I (267) spi_flash: flash io: dio
I (272) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
Hello, world!
For more information, check out:
Linux/Mac users: Make sure you have the dependencies installed,that are mentiond in the esp-idf install guide. You dont need to manually install esp-idf, just its dependencies.
For detailed instructions see Setting Up a Development Environment chapter of The Rust on ESP Book.
rustup
)If you don't have rustup
installed yet, follow the instructions on the rustup.rs site
cargo install cargo-generate
cargo install ldproxy
cargo install espup
cargo install espflash
cargo install cargo-espflash # Optional
[!NOTE] If you are running Linux then
libudev
must also be installed forespflash
andcargo-espflash
; this is available via most popular package managers. If you are running Windows you can ignore this step.# Debian/Ubuntu/etc. apt-get install libudev-dev # Fedora dnf install systemd-devel
Also, the
espflash
andcargo-espflash
commands shown below, assume that version2.0
or greater.
espup
)espup install
# Unix
. $HOME/export-esp.sh
[!WARNING] Make sure you source the generated export file, as shown above, in every terminal before building any application as it contains the required environment variables.
See the Installation chapter of The Rust on ESP Book for more details.
While you can target the RISC-V Espressif SOCs (esp32-cXX
and esp32-hXX
) with the espup
installer just fine, SOCs with this architecture are also supported by the nightly Rust compiler and by recent, stock Clang compilers (as in Clang 11+):
nightly
Rust toolchain with the rust-src
component included:
rustup toolchain install nightly --component rust-src
nightly
toolchain override, i.e. cargo +nightly ...
.You need a Python 3.7 or later installed on your machine.
sudo apt install python3
You'll also need the Python PIP and Python VENV modules. On Debian systems, you can install with:
sudo apt install python3-pip python3-venv
You'll only need the GDB utility for on-chip debugging or for decoding backraces in panics for RISCV Espressif SOCS.
To install it:
tar xvfz
) into a directory of your choicePATH
, so that e.g. invoking riscv32-esp-elf-gdb
(or xtensa-esp-elf-gdb
for xtensa-based SOCs) without any path prefixes is possible, as esp-idf-monitor
wants thatesp-idf-monitor
While espflash
has a built-in monitor, its monitor is currently unable to properly decode ESP-IDF stacktraces generated by the
RISCV Espressif MCUs (ESP32-CXX/ESP32-HX/ESP32-PX).
Therefore, use esp-idf-monitor
instead.
... and finally - to install esp-idf-monitor
itself - do:
pip install esp-idf-monitor
To run esp-idf-monitor
with panic backtrace decoding for e.g. ESP32-C3, do:
python -m esp_idf_monitor [-p your-com-port-eg-`dev/ttyUSB0`] --toolchain-prefix riscv32-esp-elf- --target esp32c3 --decode-panic backtrace <your-elf-file-that-you-just-flashed>
For other RISCV SOCs like e.g. ESP32-C6 you only need to change the --target
to esp32c6
, but the toolchain prefix (and thus GDB itself) would remain the same.
Using WSL2 does not exhibit path length issues; furthermore, using WSL2 reduces the waiting time between command line cargo invocations and Rust Analyzer operating on the same projects.
sudo apt install linux-tools-generic hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20
$HOME
directory.cargo build
or cargo b
.lsusb
.espflash board-info
.espflash flash target/xtensa-esp32-espidf/debug/<your-project-name>
OR
espflash board-info
cargo run
espflash monitor
usbipd detach --busid <busid>
This remains effective even after a system restart.
usbipd attach --wsl --busid <busid>
in such cases.
C:\Users\<UserName>\Project
or /mnt/c/Users/<UserName>/Project
can lead to performance issues.C:\Users\<UserName>\Project
or /mnt/c/Users/<UserName>/Project
may also cause ESP-IDF builds to fail with OS Error 2.