Simplified Embedded Rust: ESP Standard Library Edition - Book Repository 🦀

Welcome to the Simplified Embedded Rust: ESP Standard Library Edition book repository. Here you will find all the resources related to the book. You can get a copy of the book here.

📝 Reporting Issues & Content Suggestions

If you find any text errors, typos, or formatting issues in the book, please report a text error here so that it can be addressed in a later revision.

If you find any code issues in the book, please report a bug here so that it can be addressed in a later revision.

You are also welcome to suggest a feature here so it may be considered for content in the future.

🔗 GitHub Project Links

This is a list of the project links containing the example source code for the ESP32-C3 and the ESP32. This covers both RISC-V and Xtensa architechtures. Apart from that, variations among devices for the examples in the book are minor. All projects were setup using VS Code as an editor. Each branch contains the same collection of code examples accomodated for the different ESP device. Click on the link for the device you desire to work with and clone that particular branch.

Device	Devkit	GitHub Links
ESP32-C3	ESP32-C3-DevKitM-1	ESP32-C3 Branch
ESP32	ESP32-Dev-KitC	ESP32 Branch

🔌 Project Templates for End of Chapter Questions

Pre-wired project templates are provided to get you started with end of chapter questions. You can access all templates in the End of Chapter Questions Branch.

Questions that are not included would use exisiting book examples as templates. These are based on the ESP32-C3 device and would need to be rewired for other devices. If you notice a template missing or would like to request one, feel free to submit a feature request.

🧑‍💻 Development Options

⚠️ As of January 2025, Wowki stopped supporting the std builder on it's web interface. While the no_std builder is still supported on the web interface, an alternative beginner friendly option of using DevContainers and Wokwi with VSCode is introduced. With a few clicks in GitHub, Devcontainers enable the spawning of a full environment with all the book examples in a single workspace. Still, no need for any hardware and knowledge of Devcontainers is not required.

1. 🌐 Development Containers (Recommended)

This is the recommended option for beginners as it is the quickest and easiest way to get started. The full environment will be setup in your web browser with a few clicks and without leaving this repository. All you have to do is click on the green "Code" button in the upper right corder then navigate to the codespaces tab and click "create codespace on [device name]". A tab will automatically open setting up the whole environment with the example projects for you.

2. 🏡🛠️ Local Editor with Physical Hardware

If you prefer to develop locally with physical hardware, you can clone the examples locally and set them up to run on an external development board. The software required entails the ESP-IDF framework in addition to flashing tools to download code to the external hardware. The following links include the instructions for installing the ESP-IDF framework and flashing the development board.

a) Install Rust 🦀:

If you do not have Rust installed already, follow the instructions on the rustup website.

b) Install espup:

Run the following command in a terminal window:

cargo install espup

c) Install Toolchains:

Run the following command in a terminal window:

espup install

d) Install Python.

e) Install git.

f) Install the ldproxy Crate:

Run the following command in a terminal window:

cargo install ldproxy

g) Set Up the Environment Variables:

espup will create an export file that contains some environment variables required to build projects. If you’re on Windows, there’s no need to do anything special. However, for Unix-based systems, the file is $HOME/export-esp.sh. You can add the environment variables to your shell profile directly by adding the content of $HOME/export-esp.sh to your shell’s profile:

cat $HOME/export-esp.sh >> [path to profile]

For example, if you are using the zshrc profile your command may look something like this:

cat $HOME/export-esp.sh >> ~/.zshrc

Afterward, its recommended that you restart your terminal session for changes to take effect.

⚠️ If you are using macOS or Linux there may be additional prerequisites for setting up std development. Refer to Step 1 under the following link.

h) Install espflash:

Run the following command in a terminal window:

cargo install espflash

Afterward, the easiest way to flash an ELF binary, is to add espflash as your Cargo runner. This way, when enterning cargo run, the code would automaitcally perform the flashing after file generation. This is done by adding the following line to your .cargo/config.toml file:

[target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))']
runner = "espflash flash --monitor"

g) Install cargo-generate:

When creating your own projects from scratch, it is highly recommended that you use cargo-generate. Through cargo-generate you can create new project templates pre-configured for any ESP device. Click on the link below for instructions to install and use cargo-generate. To install cargo-generate run the following command:

cargo install cargo-generate

Afterward, to generate a std template run the following command:

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

3. 🏡🔮 Local Editor with Wokwi

If you prefer to develop locally with Wowki (no hardware), you can clone the examples locally and install the following extensions for the simulator:

• VSCode Wokwi Extension
• JetBrains Wokwi Plugin

⚠️ Local development with Wokwi still requires the installation of the ESP-IDF framework, however, flashing tools are not required since external hardware is not involved. Also through cargo-generate you can generate projects pre-configured for Wokwi skipping the second part after extension installation.

⛔️ Important Note:

Options 2, 3, and 4 are not recommended for beginners due to the added complexity and, in some cases, required installations. For example, installing the ESP-IDF framework in particular is quite involved and not necessarily always a smooth experience.

🧱 Hardware Component List (Optional)

This is a list of the components used in the different examples in the book. Acquiring these components is OPTIONAL and recommended only after you are comfortable with the material. You will only need these components if you are interested in doing physical hardware development at a later time (options 2 and 3 listed in the development options section earlier).

Component	Documenation	Purchase Links
Development Board (Choose one)	ESP32-C3-DevKitM-1 ESP32-C3-DevKit-RUST-1	ESP32-C3-DevKitM-1 (AliExpress) ESP32-C3-DevKit-RUST-1 (AliExpress)
Female to Male Wires	N/A	AliExpress
Prototyping Breadboard	N/A	AliExpress
LEDs	Datasheet	AliExpress
LED Bar	Datasheet	AliExpress
Push Button	Datasheet	AliExpress
Potentiometer	Datasheet	AliExpress
NTC Temperature Sensor	Datasheet	AliExpress
DS1307	Datasheet	AliExpress