ESP32‑S3 Rust Development (Nix + direnv + espup + Just)

This project is set up to build and flash Rust firmware to an ESP32‑S3 using:

• Nix + direnv for a reproducible dev shell
• rustup + espup for the Xtensa Rust toolchain (esp)
• espflash for flashing and serial monitor
• Just for simplifying common commands

---

1. One‑time system / user setup (outside this repo)

You already have this, but for reference:

• NixOS / Nix configuration installs:
  • pkgs.rustup (so rustup exists globally),
  • Optional Nix Rust (pkgs.rust-bin…) for non‑ESP projects,
  • Tools like rust-analyzer, pkg-config, openssl, cargo-llvm-cov.

Minimal global requirements (already configured):

• Nix with flakes

• direnv integrated with your shell

• rustup installed globally via Nix

• A stable Rust toolchain via rustup:

  rustup install stable
  rustup default stable

---

2. One-time project setup

From the project root, run:

just setup

This command will:

• Create a .envrc file and allow direnv.
• Install the ESP Xtensa toolchain using espup.
• Set the esp toolchain as the default for this project using rustup.

You can verify the setup:

which rustc
rustc -V
rustup show active-toolchain

You should see output indicating the esp toolchain is active.

---

---

3. Project‑local Cargo configuration

A .cargo/config.toml file is provided in the project root to configure Cargo for the ESP32-S3 target and set espflash as the runner.

[build]
target = "xtensa-esp32s3-none-elf"

[target.xtensa-esp32s3-none-elf]
runner = "espflash flash --monitor"

[unstable]
build-std = ["core"]

Notes:

• Do not add manual rustflags like -C target-cpu=esp32s3.
• Let the ESP esp toolchain + target spec handle CPU settings.

---

3. What the dev shell does (short)

The flake.nix dev shell:

• Installs tools: espup, espflash, ldproxy, esp-generate, rust-analyzer.
• Sets:
  • CARGO_BUILD_TARGET=xtensa-esp32s3-none-elf
  • RUST_BACKTRACE=1
• In shellHook:
  • Sources ~/export-esp.sh (espup environment).
  • Puts esp toolchain bin first in PATH so Xtensa rustc is used.

---

4. Daily workflow

After completing the one-time setup, you can use the following just commands for your daily workflow:

• Build:

  just build-release

  This builds the project in release mode for the xtensa-esp32s3-none-elf target.

• Flash and Monitor:

  just flash

  or

  just flash-monitor

  This command builds the project, flashes it to your ESP32-S3, and opens the serial monitor. Important: Ensure the PORT environment variable is set correctly, or update the justfile with your specific serial port (e.g., /dev/tty.usbmodem2101). You can list available ports with just list-ports.

• List available serial ports:

  just list-ports

• Clean build artifacts:

  just clean

---

5. Why it works

• Nix + direnv: Provide a consistent and reproducible development environment, ensuring all necessary tools and dependencies are available.
• espup + rustup: Install and manage the specific Xtensa Rust toolchain required for ESP32-S3 development.
• .cargo/config.toml: Configures cargo to use the correct target and runner for the ESP32-S3.
• Justfile: Simplifies common development tasks into easy-to-remember commands, reducing the cognitive load and potential for errors.

---

---

6. TL;DR

One-time setup:

cd /Users/utopiaeh/Developer/mcu/guage-board
just setup

Day-to-day commands:

cd /Users/utopiaeh/Developer/mcu/guage-board

# Build
just build-release

# Flash and monitor (ensure port is correct in Justfile or set as env var)
just flash