Crafting a 'Hello World' in Rust for the ESP-32: A Step-by-Step Guide

Jumping into embedded programming with Rust is a daunting challenge. I’ve written this blog post to help get you started. I’ll be showing you how to get the most basic of code, the ‘Hello world!’ running on the ESP-32, in Rust.

To write this post I’ve distilled information from The Rust on ESP Book (licensed under CC-BY-SA v4.0), and I highly recommend giving it a read, especially if this topic interests you, as it trumps this blog post in detail and thoroughness.

Setup

Plug your ESP-32 in to a USB port on your machine. A light should turn on and you should now be able to see the serial port in your terminal.

ls /dev/ttyUSB0

your serial port name may be different here, this just happens to be mine.

Configure Your Host System

add yourself to the tty and dialout group. You’ll need this to be able to interact with the board over its serial connection.

sudo usermod -aG dialout <youruser>
sudo usermod -aG tty <youruser>

After this, logout and log back in to your machine, check that you are a member of these groups with groups

On your host system install cargo generate. We’ll be using this to generate a template, meaning all the extra code and configuration we need for the ESP-32.

cargo install cargo-generate

Note: on my system, I had to install openssl-dev on my host to compile past errors.

Generate Your Code

Now generate the required template for our system.

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

you'll see a TUI menu, set the project name to hello_world, the MCU to esp32, and don’t configure advanced options.

You can read this section of the tutorial I mentioned above if you want to know more about the generator.

You should now see some new files! The most important of which is src/main.rs.

Create Build Environment

Now we need to create the build environment. We’ll be using the container provided by espressif, since it already has all the configurations and packages requires.

Change directories into your generated project, pull the container, and start it:

cd hello_world
docker pull espressif/idf-rust:all_1.83.0.1
docker run -it -v $PWD:/home/esp/hello_world  espressif/idf-rust:all_1.83.0.1 bash

the above docker command will start an interactive shell inside the container, and mount a volume of your generated project inside of it.

You should have now have a shell inside the container:

Build, Flash and Run, Code

In the container shell, cd into the hello_world directory and build the code as you would any other Rust project:

cd hello_world
cargo build

After some time, your build will finish.

Back on the hosts shell, install espflash. This is a neat little tool that makes flashing the ESP32 as easy as 01,10,11 :)

cargo install espflash

For install errors, I had to install systemd-devel for the this to work.

Now that we're installed, let's flash our code to the board!

espflash flash target/xtensa-esp32-espidf/debug/hello_world --monitor

This command will both flash to the board, as well as monitor on the serial port for any logging.

The ESP-32 will automatically run your code on boot, so you wont need to do anything else here.

Success! Now you can play around on your own here. I personally just like to set up an infinite loop for fun :)

Next Steps

Now that you have a system set up to run Rust code on the ESP-32, the world is your oyster! I urge you to find more examples to broaden your horizon, or just experiment a little! Take a look at the esp-rs website for some other reccomendations, and good luck! 🫡

Footnote

This post could not have been written without help from The Rust on ESP Book. I’ve distilled information from that book, as well as included some of my own. That book is licensed under CC-BY-SA v4.0.