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 add support for Xtensa/ESP32-S3), instructions for doing so can be found in the Installing Rust chapter of the Rust on ESP Book.
✅ If you haven't got Rust on your computer, obtain it via https://rustup.rs/
Furthermore, for ESP32-C3, a specific nightly version of the Rust toolchain is currently required.
✅ Install nightly Rust and add support for the target architecture using the following console commands:
$ rustup install nightly-2022-03-10 $ rustup component add rust-src --toolchain nightly-2022-03-10
🔎 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.
To build for the Xtensa architecture (not part of this material), a fork of the Rust compiler is required as of January 2022.
Several tools are required:
cargo-espflash- upload firmware to the microcontroller
ldproxy- Espressif build toolchain dependency
✅ Install them with the following command:
$ cargo install cargo-espflash ldproxy
$ sudo apt install llvm-dev libclang-dev clang
(when using the Homebrew package manager, which we recommend)
$ brew install llvm
Python 3 is a required dependency. It comes preinstalled on stock macOS and typically on desktop Linux distributions. An existing Python 2 installation with the
virtualenvadd-on pointing to it is known to potentially cause build problems.
failed to run custom build command for libudev-sys v0.1.4or
At time of writing, this can be solved by
- running this line from the
apt-get update \ && apt-get install -y vim nano git curl gcc ninja-build cmake libudev-dev python3 python3-pip libusb-1.0-0 libssl-dev \ pkg-config libtinfo5
restarting the terminal
If this is not working, try
cargo clean, remove the
~/.espressiffolder and reinstall according to esp instructions.
⚠️ In step 2, do not clone the
https://github.com/espressif/esp-idf.gitrepository. For this training, we are using a git tag.
Instead, do the following:
git clone --recursive --depth 1 --shallow-submodules email@example.com:espressif/esp-idf.git --branch "v4.4.1" esp-idf-v4.4 cd esp-idf-v4.4 ./install.sh esp32c3 . ./export.sh
If you change terminal, you will need to source the
- On Ubuntu, you might need to change your kernel to
uname -rto obtain your kernel version.
- running this line from the
❗️ Please note the Docker container provides an alternative option to compile the Rust exercises in. It is meant for users that have experience with virtualized environments. Be aware that we cannot provide help for Docker specific issues during the training.
An alternative environment to compile the Rust exercises in is to use Docker. In this repository there is a
with instructions to install the Rust toolchain & all required packages. This virtualized environment is designed
to only compile the binaries for the espressif target. Other commands, e.g. using
cargo-espflash, still need to
be executed on the host system.
Docker for your operating system.
To build the Docker image run the following command from the root folder:
$ docker image build --tag esp --file .devcontainer/Dockerfile .
Building the image takes a while depending on the OS & hardware (20-30 minutes).
To start the new Docker container run:
$ docker run --mount type=bind,source="$(pwd)",target=/workspace,consistency=cached -it esp /bin/bash
This starts an interactive shell in the Docker container. It also mounts the local repository to a folder
/workspace inside the container. Changes to the project on the host system are reflected inside the container & vice versa.
Using this Docker setup requires certain commands to run inside the container, while other have to be executed on the host system. It's recommended to keep two terminals open, one connected to the Docker container, one on the host system.
- in the container: compile the project
- on the host: use the
cargo-espflashsub-command to flash the program onto the embedded hardware
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.
Even Better TOMLfor editing TOML based configuration files
Rust Analyzerto provide code completion & navigation
There are a few more useful extensions for advanced usage
One extension for VS Code that might be helpful to develop inside a Docker container is
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.