Skip to content

About

ESP32S3 tinkering with projects using rust embedded

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Rust Embedded Packages — Quick Reference

Development Environment

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.

ESP32-S3

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.

Rust Embedded Concepts

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.

Project Structure

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.

Build & Flash Commands

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.

ESP32-S3 Project Configuration

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

ESP32-S3 Architecture

Important: ESP32-S3 uses the Xtensa LX7 architecture. It is not RISC-V, so a RISC-V target such as riscv32imc-unknown-none-elf should 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

Tool Installation

ESP Rust toolchain

cargo install espup

espup install

After espup install, load the generated environment:

source ~/export-esp.sh

Binary inspection tools

cargo install cargo-binutils

rustup component add llvm-tools-preview

Flash/debug tools

cargo install probe-rs-tools

espflash is installed automatically when required by the ESP project generation workflow, or can be installed separately if needed.

Project generation

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.

Rust IDE support

code --install-extension rust-lang.rust-analyzer

Environment Verification

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 --version may show the normal Rust toolchain outside an ESP project. Projects generated by esp-generate contain rust-toolchain.toml with channel = "esp", which selects the ESP toolchain for that project.

Important ESP32-S3 Toolchain Note

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.

Current Hardware

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

Current Learning Project


~/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.

First Successful Flash & Boot

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 run

If Linux reports permission denied for /dev/ttyACM0, add the user to dialout:

sudo usermod -aG dialout $USER

Then start a new login session, or temporarily activate the group in the current shell:

newgrp dialout

The 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

Current Learning Status

Completed

  • 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

Next

  • GPIO output
  • Blink an LED
  • GPIO input
  • Timers
  • Interrupts
  • UART
  • I2C / SPI
  • Wi-Fi
  • Flash / NVS
  • OTA
  • Production security

Common Boot Modes

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.

Useful Development Workflow


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

About

ESP32S3 tinkering with projects using rust embedded

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages