| Package / Tool | Usage |
|---|---|
rustup |
Manages Rust toolchains, versions, targets, and Rust components. |
rustc |
Compiles Rust source code into machine code for the selected target. |
cargo |
Builds projects, manages dependencies, runs tests, and executes Rust applications. |
espup |
Installs and configures the ESP-specific Rust toolchain, including Xtensa support required by ESP32-S3. |
esp Rust toolchain |
ESP-specific Rust compiler/toolchain used to compile Rust applications for ESP32 Xtensa chips. |
llvm-tools-preview |
Provides LLVM utilities used for inspecting and manipulating compiled binaries. |
cargo-binutils |
Provides Cargo commands such as cargo size and cargo objcopy for analyzing and converting embedded binaries. |
probe-rs-tools |
Provides tools for flashing, running, and debugging supported microcontrollers through debug probes. |
probe-rs |
Communicates with supported microcontrollers/debug probes for flashing and debugging firmware. |
rust-analyzer |
Provides IDE features such as autocomplete, navigation, diagnostics, and type information for Rust. |
cargo-generate |
Creates Rust projects from existing project templates. |
esp-generate |
Current ESP Rust project generator for creating ESP32 projects with the required Cargo, toolchain, and target configuration. |
espflash |
Flashes ESP firmware over USB and provides a serial monitor. |
esp-config |
ESP configuration utility used by the ESP Rust project ecosystem. |
| Package / Component | Usage |
|---|---|
esp-hal |
Hardware Abstraction Layer for accessing ESP32-S3 peripherals through Rust APIs. |
esp-pac |
Low-level Peripheral Access Crate providing access to ESP32-S3 hardware registers. |
xtensa-esp-elf-gcc |
Xtensa GCC compiler provided by the ESP toolchain and used as part of the ESP32-S3 build environment. |
esp-generate |
Generates a new ESP Rust project with the required target, Cargo configuration, dependencies, and build setup. |
espflash |
Flashes firmware to ESP32 boards and provides serial monitoring. |
export-esp.sh |
Environment setup script generated by espup for configuring the ESP Rust toolchain in the current shell. |
| Component | Usage |
|---|---|
#![no_std] |
Allows Rust applications to run without the standard library, which is typical for bare-metal embedded systems. |
#![no_main] |
Allows an embedded application to use its own entry-point mechanism instead of Rust's normal main startup. |
HAL |
Provides higher-level APIs for controlling hardware peripherals such as GPIO, UART, SPI, and I2C. |
PAC |
Provides low-level access to MCU memory-mapped peripheral registers. |
memory.x |
Defines the microcontroller's Flash/RAM memory layout used by the linker when a project uses a linker script. |
| Linker script | Tells the linker how compiled code and data should be placed into MCU memory. |
esp-hal::init() |
Initializes the ESP hardware abstraction layer and returns access to the configured peripherals. |
#[main] |
ESP HAL entry-point attribute used by the generated application to define the firmware entry function. |
panic_handler |
Defines what happens when a panic occurs in a no_std embedded application. |
A generated ESP32-S3 project currently looks roughly like:
esp32-s3-learning/
├── .cargo/
│ └── config.toml
├── src/
│ ├── lib.rs
│ └── bin/
│ └── main.rs
├── Cargo.toml
├── Cargo.lock
├── build.rs
├── rust-toolchain.toml
└── .clippy.toml
| File | Usage |
|---|---|
Cargo.toml |
Defines the Rust package, binary target, dependencies, and build profiles. |
Cargo.lock |
Locks dependency versions used by the project. |
rust-toolchain.toml |
Selects the ESP Rust toolchain for the project. |
.cargo/config.toml |
Configures the ESP32-S3 target, linker/build settings, and espflash runner. |
src/bin/main.rs |
Main ESP32-S3 firmware/application entry point. |
src/lib.rs |
Library crate root; currently contains #![no_std] in the generated project. |
build.rs |
Runs build-time configuration required by the project. |
.clippy.toml |
Project-specific Clippy configuration. |
| Command | Usage |
|---|---|
cargo build |
Compiles the embedded Rust application without flashing it. Useful when the ESP32-S3 is not connected. |
cargo build --release |
Builds an optimized release firmware. |
cargo run |
Builds the firmware and invokes the configured runner, which currently uses espflash to flash and monitor the ESP32-S3. |
cargo size |
Shows the amount of Flash/RAM used by the compiled firmware when supported by the configured toolchain. |
cargo objcopy |
Converts the compiled firmware into formats such as .bin or .hex when configured/supported. |
espflash board-info |
Reads information from a connected ESP board over USB. |
espflash flash |
Flashes firmware to an ESP board. |
probe-rs run |
Flashes and runs firmware on supported microcontrollers through a compatible debug probe. |
The generated project uses:
[toolchain]
channel = "esp"
and:
[build]
target = "xtensa-esp32s3-none-elf"
The Cargo runner is configured as:
[target.xtensa-esp32s3-none-elf]
runner = "espflash flash --monitor --chip esp32s3"
Therefore:
cargo build
↓
ESP Rust toolchain
↓
Xtensa ESP32-S3 target
↓
Firmware binary
while:
cargo run
↓
cargo build
↓
espflash
↓
USB
↓
ESP32-S3
↓
Serial monitor
Important: ESP32-S3 uses the Xtensa LX7 architecture. It is not RISC-V, so a RISC-V target such as
riscv32imc-unknown-none-elfshould not be used for this board.
Rust Application
↓
esp-hal
↓
esp-pac
↓
ESP Rust / Xtensa Toolchain
↓
Xtensa ESP32-S3 Target
↓
ESP32-S3
↓
Xtensa LX7
↓
Hardware
cargo install espup
espup install
After espup install, load the generated environment:
source ~/export-esp.sh
cargo install cargo-binutils
rustup component add llvm-tools-preview
cargo install probe-rs-tools
espflash is installed automatically when required by the ESP project generation workflow, or can be installed separately if needed.
cargo install cargo-generate
Current ESP project generation uses:
esp-generate
For example:
cd ~/rust-embedded
esp-generate
Then select:
esp32s3
as the target chip.
code --install-extension rust-lang.rust-analyzer
After:
source ~/export-esp.sh
verify the ESP compiler environment:
rustc --version
xtensa-esp-elf-gcc --version
Verify the installed tools:
espflash --version
probe-rs --version
esp-config --version
cargo size --version
Note:
rustc --versionmay show the normal Rust toolchain outside an ESP project. Projects generated byesp-generatecontainrust-toolchain.tomlwithchannel = "esp", which selects the ESP toolchain for that project.
Do not install the ESP32-S3 target using:
rustup target add xtensa-esp32s3-none-elf
The standard Rust distribution does not provide a normal prebuilt Xtensa ESP32-S3 target in the same way it provides common targets.
Instead, install the ESP-specific toolchain using:
cargo install espup
espup install
source ~/export-esp.sh
espup sets up the ESP Rust/Xtensa environment required to compile for the ESP32-S3.
Board: ESP32-S3 N16R8 Dual USB-C Wi-Fi + Bluetooth Development Board
MCU: ESP32-S3
CPU: Xtensa LX7 dual-core
Flash: 16 MB
PSRAM: 8 MB
USB: Dual USB-C
Connectivity: Wi-Fi + Bluetooth LE
~/rust-embedded/esp32-s3-learning
The project was generated using:
esp-generate
with:
--chip esp32s3
Current dependencies include:
esp-hal = { version = "~1.1.0", features = ["esp32s3"] }
esp-bootloader-esp-idf = { version = "0.5.0", features = ["esp32s3"] }
critical-section = "1.2.0"
The generated firmware currently initializes the ESP32-S3 HAL and enters an infinite loop with a 500 ms busy-wait.
The project successfully passes:
cargo build
The firmware has not yet been flashed because the ESP32-S3 board is currently waiting for a USB-C cable.
The first hardware flashing session followed this sequence:
USB-C connected
↓
Linux detected /dev/ttyACM0
↓
User added to dialout group
↓
ESP32-S3 entered download mode with BOOT + RESET
↓
espflash board-info connected successfully
↓
cargo run built the Rust firmware
↓
espflash flashed and verified the firmware
↓
RESET switched the chip to normal boot
↓
ESP32-S3 booted from SPI flash
↓
Rust application started
Useful commands:
# Check the serial device
ls -l /dev/ttyACM0
# Check ESP32-S3 information
espflash board-info --port /dev/ttyACM0
# Build and flash/run
cargo runIf Linux reports permission denied for /dev/ttyACM0, add the user to dialout:
sudo usermod -aG dialout $USERThen start a new login session, or temporarily activate the group in the current shell:
newgrp dialoutThe current board was detected as:
Chip type: esp32s3 (revision v0.2)
Crystal frequency: 40 MHz
Flash size: 16MB
Features: WiFi, BLE, Embedded Flash
Secure Boot: Disabled
Flash Encryption: Disabled
- Install Rust
- Install ESP Rust/Xtensa toolchain with
espup - Generate ESP32-S3 Rust project with
esp-generate - Build the project with
cargo build - Connect ESP32-S3 over USB
- Resolve Linux dialout serial permissions
- Enter ESP32-S3 download mode
- Detect the chip with
espflash - Flash firmware with
cargo run - Verify flashed firmware
- Boot the Rust application from SPI flash
- GPIO output
- Blink an LED
- GPIO input
- Timers
- Interrupts
- UART
- I2C / SPI
- Wi-Fi
- Flash / NVS
- OTA
- Production security
The ESP32-S3 can show different boot messages depending on its state.
Download mode:
boot:0x0 (DOWNLOAD(USB/UART0))
waiting for download
This means the chip is waiting for firmware to be uploaded.
Normal application boot:
boot:0x8 (SPI_FAST_FLASH_BOOT)
This means the chip is booting firmware from SPI flash.
For normal development, cargo run can put the chip into the required flashing state, flash the firmware, and open the serial monitor. If the chip remains in download mode after a manual BOOT + RESET sequence, release the BOOT button and reset the board normally.
1. Install ESP toolchain
↓
2. source ~/export-esp.sh
↓
3. Create project with esp-generate
↓
4. cargo build
↓
5. Connect ESP32-S3 over USB
↓
6. espflash board-info
↓
7. cargo run
↓
8. Flash + serial monitor
↓
9. Develop GPIO / timers / UART / SPI / I2C
↓
10. Wi-Fi / Bluetooth / Embassy / async