Rust on ESP Book

To work effectively with Espressif devices in Rust, you need to understand two primary pillars:

1. Hardware Overview: Knowledge of the Espressif SoC (System on Chip) families, their specific architectures, and available development boards. This is necessary for selecting the correct chip and understanding the hardware constraints of your target device.
2. Ancillary Crates: The software ecosystem consists of various crates that provide essential building blocks, such as memory allocation and wireless communication protocols.

Mastering these two areas is a prerequisite for the practical setup and application development covered in the Getting Started chapter.

When developing with the esp-rs ecosystem, be aware of the stability guarantees provided by different components:

• Stabilized Modules: These follow Semantic Versioning (SemVer) and are not subject to breaking changes.
• Unstable Features: Components marked as unstable (such as certain parts of esp-hal and specific drivers) are actively under development. These do not follow SemVer guarantees. Using unstable components means your project may break during a cargo update, similar to using the Rust nightly compiler.

It is recommended to track dependencies closely and consult migration guides provided for major crates when updating.

The probe-rs project provides a suite of tools for interacting with embedded microcontrollers. It supports flashing, monitoring, and robust debugging capabilities for Espressif chips.

Hardware Requirements:

• Internal Debugging: If your Espressif device has the USB-JTAG-SERIAL peripheral, you can use probe-rs without external hardware. This peripheral is available on:
  • ESP32-C6
  • ESP32-H2
  • ESP32-S3
  • ESP32-C3 (revision 0.3 or later)
• External Debugging: For devices lacking the USB-JTAG-SERIAL peripheral, you must use an external programmer such as the ESP-Prog.

Do not use std::mem::forget on peripheral drivers. Drivers in the ESP ecosystem implement the Drop trait to ensure peripherals are returned to a safe, unconfigured state and to cancel any active Direct Memory Access (DMA) transactions.

Using mem::forget can lead to:

• Erroneously configured peripherals.
• DMA transactions that run indefinitely and never complete.

The ESP ROM bootloader selects the boot mode by reading the state of specific strapping pins during reset:

• SPI Boot mode: The chip runs the application from Flash. This occurs if the boot strapping pin is high.
• Download mode: The chip waits for new firmware via UART or USB and writes it to Flash. This occurs if the boot strapping pin is low.

When in Download mode, the serial output will display: waiting for download.

For advanced connectivity features like Wi-Fi, BLE, esp-now, or IEEE 802.15.4, use the esp-radio crate.

Important Requirements:

• Radio support requires a stack running continuously in the background (timers, interrupts, state machines).
• esp-radio relies on an implementation of esp-radio-rtos-driver to define the necessary scheduling and runtime interface.
• esp-rtos is the default supported backend. esp-generate will automatically add esp-rtos if you enable the appropriate template options.

Over The Air (OTA) updates allow you to update an application without using physical production flashing tools. This process relies on a bootloader to manage the switching, replacement, and rollback of OTA images (firmware updates).

Currently, the Rust ecosystem for ESP supports the ESP-IDF bootloader via the [esp-bootloader-esp-idf] crate.

Choose the narration perspective based on the context:

• First person (we): Use when introducing a tutorial or explaining how the authors will proceed (e.g., "We'll start writing a program...").
• Second person (you/imperative): Use when describing actions the reader must take, such as installation or procedures (e.g., "1. Install cargo-generate cargo install cargo-generate").
• Third person (the user, it): Use when describing how hardware or software works (e.g., "A driver has to be initialized...").

For resource-constrained environments like ESP32, defmt is a highly efficient logging framework. It uses compact, binary-encoded log messages to minimize overhead compared to traditional string-based logging.

Recommendation: Pair defmt with probe-rs for the best experience on Espressif chips.