Software

Follow the steps below for a default installation of the ESP32-C3 platform tooling.

🔎 Should you desire a customized installation (e.g. building parts from source, or adding support for Xtensa targets), instructions for doing so can be found in the Installation chapter of the Rust on ESP Book.

Rust toolchain

✅ If you haven't got Rust on your computer, obtain it via https://rustup.rs/

Furthermore, for ESP32-C3, a nightly version of the Rust toolchain is currently required, for this training we will use nightly-2023-11-14 version.

✅ Install nightly Rust and add support for the target architecture using the following command:

rustup toolchain install nightly-2023-11-14 --component rust-src --target riscv32imc-unknown-none-elf

🔎 Rust is capable of cross-compiling to any supported target (see rustup target list). By default, only the native architecture of your system is installed.

Espressif toolchain

Several tools are required:

  • cargo-espflash - upload firmware to the microcontroller and open serial monitor with cargo integration
  • espflash - upload firmware to the microcontroller and open serial monitor

✅ Install them with the following command:

cargo install cargo-espflash espflash

⚠️ The espflash and cargo-espflash commands listed in the book assume version is >= 2

Toolchain dependencies

Debian/Ubuntu

sudo apt install llvm-dev libclang-dev clang

macOS

When using the Homebrew package manager, which we recommend:

brew install llvm

Docker

An alternative environment, is to use Docker. The repository contains a Dockerfile with instructions to install the Rust toolchain, and all required packages. This virtualized environment is designed to compile the binaries for the Espressif target. Flashing binaries from containers is not possible, hence there are two options:

  • Execute flashing commands, e.g., cargo-espflash, on the host system. If proceeding with this option, it's recommended to keep two terminals open:
    • In the container: compile the project
    • On the host: use the cargo-espflash sub-command to flash the program onto the embedded hardware
  • Use web-flash crate to flash the resulting binaries from the container. The container already includes web-flash. Here is how you would flash the build output of hello-world project: 
    web-flash --chip esp32c3 target/riscv32imc-unknown-none-elf/release/hello-world

✅ Install Docker for your operating system.

✅ Get the docker image: There are 2 ways of getting the Docker image:

  • Build the Docker image from the Dockerfile: 
    docker image build --tag rust-std-training --file .devcontainer/Dockerfile .
    Building the image takes a while depending on the OS & hardware (20-30 minutes).
  • Download it from Dockerhub: 
    docker pull espressif/rust-std-training

✅ Start the new Docker container:

docker run --mount type=bind,source="$(pwd)",target=/workspace,consistency=cached -it rust-std-training /bin/bash

This starts an interactive shell in the Docker container. It also mounts the local repository to a folder named /workspace inside the container. Changes to the project on the host system are reflected inside the container & vice versa.

Additional Software

VS Code

One editor with good Rust support is VS Code, which is available for most platforms. When using VS Code, we recommend the following extensions to help during the development.

  • Rust Analyzer to provide code completion & navigation
  • Even Better TOML for editing TOML based configuration files

There are a few more useful extensions for advanced usage

  • lldb a native debugger extension based on LLDB
  • crates to help manage Rust dependencies

VS Code & Devcontainer

One extension for VS Code that might be helpful to develop inside a Docker container is Remote Containers. It uses the same Dockerfile as the Docker setup, but builds the image and connects to it from within VS Code. Once the extension is installed, VS Code recognizes the configuration in the .devcontainer folder. Use the Remote Containers - Reopen in Container command to connect VS Code to the container.