Assignments
Spinning and Blinking
Rust
Setup

Setup

ℹ️
Ideally these steps would be omitted and a Docker image would be provided. Unfortunately the environment we are setting up relies on USB access which is currently unsupported on Apple Silicon. Learn more here.

Install Rust

To install rust, follow the instructions here.

Editor

There are many editors to choose from, here’s some:

  • VSCode (with the rust-analyzer extension)
  • Zed ✨
  • RustRover (if you like jetbrains)
  • Vim (with tree-sitter and rust-analyzer)

Embedded Tools

For ESP32s, we need to install ESP’s tools.

Execute:

cargo install espup espflash
espup install
macOS/Linux

Execute…

. $HOME/export-esp.sh

<button class=“hextra-code-copy-btn hx-group/copybtn hx-transition-all active:hx-opacity-50 hx-bg-primary-700/5 hx-border hx-border-black/5 hx-text-gray-600 hover:hx-text-gray-900 hx-rounded-md hx-p-1.5 dark:hx-bg-primary-300/10 dark:hx-border-white/10 dark:hx-text-gray-400 dark:hover:hx-text-gray-50” title=“Copy code”

<div class="copy-icon group-[.copied]/copybtn:hx-hidden hx-pointer-events-none hx-h-4 hx-w-4"></div>
<div class="success-icon hx-hidden group-[.copied]/copybtn:hx-block hx-pointer-events-none hx-h-4 hx-w-4"></div>

…in every terminal session, or append it to your shell profile.

Now we need to install cargo-embassy, a tool for generating Embassy projects.

Execute:

cargo install cargo-embassy --git https://github.com/ece-196/cargo-embassy.git

Project

It’s time to create our Rust project in the assignment repository. Make sure you are in the root directory of your assignment repo, and invoke cargo-embassy like so:

cd {your assignment root directory} # change directory to the assignment repo
cargo embassy init firmware --chip esp32s3 # create rust project in a subdirectory named "firmware"

The resulting file structure should look something like:

        • config.toml
        • main.rs
      • Cargo.toml
      • build.rs
      • rust-toolchain.toml
    • README.md
    • ℹ️
    You can learn more about this structure here.

    Open the Cargo.toml file and append the following:

    [patch.crates-io]
esp-hal = { git = "https://github.com/esp-rs/esp-hal/", rev = "f95ab0def50130a9d7da0ba0101c921e239ecdb5" }
esp-hal-embassy = { git = "https://github.com/esp-rs/esp-hal/", rev = "f95ab0def50130a9d7da0ba0101c921e239ecdb5" }
esp-backtrace = { git = "https://github.com/esp-rs/esp-hal/", rev = "f95ab0def50130a9d7da0ba0101c921e239ecdb5" }
esp-println = { git = "https://github.com/esp-rs/esp-hal/", rev = "f95ab0def50130a9d7da0ba0101c921e239ecdb5" }
    ⚠️
    The ESP32 Rust HAL is highly volatile right now, so as a precautionary measure, we are locking the version of the esp related crates with a dependency patch.

    Checkpoint

    Let’s make sure all we’ve done so far is working properly.

    In the firmware directory, execute:

    cargo build --release

    What does --release mean? Rust has multiple build profiles for different contexts. By default, the debug profile is used, this includes debug symbols in the resulting binary, and significantly reduces the optimizations done. release contains no debug symbols and is optimized (as specified in Cargo.toml).

    If this succeeds, plug your DevBoard into your computer and execute:

    cargo run --release

    It will ask you to select the port the DevBoard is connected to.

    If you see the builtin LED blinking, and Hello, World! printing on each blink, you have successfully deployed Rust code to an ESP32!

    Give yourself a pat on the back :)

    RustBlinking