Home

Awesome

Rust on ESP-IDF "Hello, World" template

Cargo CI CMake CI Documentation Matrix Wokwi

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

For more check out the links in the additional information section

Generate the project

Please make sure you have installed all prerequisites first!

cargo generate esp-rs/esp-idf-template cargo

The command will display a few prompts:

Build

cd <your-project-name>
cargo build

Flash

In the root of the generated project:

espflash flash target/<mcu-target>/debug/<your-project-name>
MCUTarget
ESP32xtensa-esp32-espidf
ESP32-S2xtensa-esp32s2-espidf
ESP32-S3xtensa-esp32s3-espidf
ESP32-C2riscv32imc-esp-espidf
ESP32-C3riscv32imc-esp-espidf
ESP32-C6riscv32imac-esp-espidf
ESP32-H2riscv32imac-esp-espidf
ESP32-P4riscv32imafc-esp-espidf

Monitor

espflash monitor /dev/ttyUSB0

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!

License of the generated code

While the esp-idf-template repository code itself is dual-licensed by Apache OR MIT, the code generated by the esp-idf-template generator can be considered in the Public Domain - or equivalently - as if licensed under the MIT No Attribution License.

We are however explicitly not outputting any license file in the generated content, which allows the developers to add their own content on top of the generated one and the combined work would be assumed to be a proprietary work, until/if a license file is explicitly added by the developer.

Additional information

For more information, check out:

Prerequisites

Linux/Mac users: Install the OS dependencies mentioned in the esp-idf install guide.

In other words, the equivalent of

sudo apt-get install git wget flex bison gperf python3 python3-pip python3-venv cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

...command for your OS, if you are not on Ubuntu/Debian.

Please:

Install Rust (with rustup)

If you don't have rustup installed yet, follow the instructions on the rustup.rs site

Install Cargo Sub-Commands

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 for espflash and cargo-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 and cargo-espflash commands shown below, assume that version 2.0 or greater.

Install Rust & Clang toolchains for Espressif SoCs (with 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.

Alternative (for RISC-V Espressif SOCs only): install & use upstream nightly Rust and upstream stable Clang

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+):

Install Python3

You need a Python 3.7 or later installed on your machine.

You'll also need the Python PIP and Python VENV modules. On Debian systems, you can install with:

Optionally Install GDB

You'll only need the GDB utility for on-chip debugging or for decoding backraces in panics for RISCV Espressif SOCS.

To install it:

Install esp-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 on Windows

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.

Setup

  1. Follow the WSL2 setup guide and the WSL2 development environment setup guide.
  2. Install a Linux distro as per the guide or the Ubuntu App; set up and update the packages.
  3. Follow the Prerequisites section for toolchain setup.
  4. Configure USB access in WSL2:
    • Install usbipd-win on Windows.
    • (Optional) In your WSL2 terminal, run: 
      sudo apt install linux-tools-generic hwdata
sudo update-alternatives --install /usr/local/bin/usbip usbip /usr/lib/linux-tools/*-generic/usbip 20

Flashing an ESP32 Target from WSL2

  1. Launch WSL2 from PowerShell and run your Linux distro or launch the Ubuntu app as installed from the Microsoft Store.
  2. Create a new project folder in your $HOME directory.
  3. Generate a new project using Cargo Generate.
  4. Build the project by running cargo build or cargo b.
  5. Open a PowerShell terminal as an administrator and run the usbipd commands to share the USB device with the Linux distro.
  6. Open the Linux terminal and check attached USB devices using lsusb.
  7. Check the attached target with espflash board-info.
  8. Flash the device: 
    espflash flash target/xtensa-esp32-espidf/debug/<your-project-name>
    OR 
    espflash board-info
cargo run
  9. Monitor the device: 
    espflash monitor

Notes