Using the Rust Standard Library (std)

Espressif provides a C-based development framework called esp-idf which has support for all Espressif chips starting with the ESP32; note that this framework does not support the ESP8266.

esp-idf in turn provides a newlib environment with enough functionality to build the Rust standard library (std) on top of it. This is the approach that is being taken to enable std support on ESP devices.

Chip Support

For applications targeting std to be built for ESP devices, two things are required:

  1. LLVM/Clang support
  2. Support for the device in esp-idf

Refer to the table below to see if your chip is supported.

ChipSupported?
ESP32✅
ESP32-C2planned
ESP32-C3✅
ESP32-S2✅
ESP32-S3✅
ESP32-H2planned
ESP8266❌

Since esp-idf does not have support for the ESP8266, we unfortunately are unable to use these libraries with it. See the Bare Metal page for information on the no_std HAL for this chip.

Standard Library Features

The supported std features are as follows:

  • Threads
  • Mutexes and other synchronization primitives
  • Collections
  • Random number generation
  • Sockets

In addition to the std features, there is an embedded-svc implementation for esp-idf, esp-idf-svc, which adds extra support for services/modules not available in the standard library, including:

  • Wi-Fi management
  • NVS (non-volatile storage)
  • Networking services like httpd and ping

In general, this approach should feel quite similar to developing for most normal PC environments.

Relevant esp-rs crates

RepositoryDescription
esp-rs/esp-idf-halAn implementation of the embedded-hal and other traits using the esp-idf framework.
esp-rs/esp-idf-svcAn implementation of embedded-svc using esp-idf drivers.
esp-rs/esp-idf-sysRust bindings to the esp-idf development framework. Gives raw (unsafe) access to drivers, Wi-Fi and more.
esp-rs/embedded-svcAbstraction traits for embedded services. (WiFi, Network, Httpd, Logging, etc.)

The aforementioned crates have interdependencies, and this relationship can be seen below.

graph TD;
    esp-idf-hal --> esp-idf-sys & embedded-svc
    esp-idf-svc --> esp-idf-sys & esp-idf-hal & embedded-svc

FAQ

I updated my sdkconfig.defaults file but it doesn't appear to have had any effect

You must clean your project and rebuild for changes in the sdkconfig.defaults to take effect:

cargo clean
cargo build

The documentation for the crates mentioned on this page is out of date or missing

Due to the resource limits imposed by docs.rs, internet access is blocked while building documentation and as such we are unable to build the documentation for esp-idf-sys or any crate depending on it.

Instead, we are building the documentation and hosting it ourselves on GitHub Pages:

***ERROR*** A stack overflow in task main has been detected.

If the second-stage bootloader reports this error, you likely need to increase the stack size for the main task. This can be accomplished by adding the following to the sdkconfig.defaults file:

CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000

In this example, we are allocating 7kB for the main task's stack.

How can I completely disable the watchdog timer(s)?

Add to your sdkconfig.defaults file:

CONFIG_INT_WDT=n
CONFIG_ESP_TASK_WDT=n

Recall that you must clean your project before rebuilding when modifying these configuration files.