Raw Rust bindings for the ESP IDF SDK

Highlights

• Build is cargo driven and automatically downloads & configures everything by default; no need to download the ESP IDF SDK manually, or set up a C toolchain
• Supports both native ESP IDF build (default), as well as a PlatformIO build
• Option to use in a mixed Rust/C project. Check the documentation in the esp-idf-template crate

You might want to also check out the type safe Rust wrappers built on top of these raw bindings:

• Type safe wrappers for ESP IDF Services
• Type safe wrappers for ESP IDF Drivers

Note
esp-idf-sys's build script will download the esp-idf, its gcc toolchain, and build it. To show progress and build information about this process run cargo with the -vv (very verbose) flag, so that build script output is also displayed. This is especially useful since the initial build will take a while.

Community Effort

Please note that all esp-idf-* crates are a community effort, in that Espressif puts little to no paid developer time in these. So while ESP-IDF itself is very popular and well tested, the esp-idf-* crates:

• Might be a bit lagging behind the latest stable ESP-IDF version
• Are (currently) missing HIL tests
• Need more documentation

For a HAL which is officially supported by Espressif (as in - with paid developer time), please look at esp-hal. Keep in mind that esp-hal is no_std-only, does not use ESP-IDF and requires async programming.

Build Prerequisites

Follow the Prerequisites section in the esp-idf-template crate.

Customizing how the ESP IDF SDK is built

Read the documentation here.

Examples

The examples could be built and flashed conveniently with cargo-espflash. To run e.g. std_basics on an e.g. ESP32-C3: (Swap the Rust target and example name with the target corresponding for your ESP32 MCU and with the example you would like to build)

with cargo-espflash:

$ MCU=esp32c3 cargo espflash flash --target riscv32imc-esp-espidf --example std_basics --monitor

Setting up a "Hello, world!" binary crate with ESP IDF

Use the esp-idf-template project. Everything would be arranged and built for you automatically - no need to manually clone the ESP IDF repository.

More information

For more information, check out:

• The Rust on ESP Book
• The ESP Embedded Training
• The esp-idf-template project
• The esp-idf-svc project
• The esp-idf-hal project
• The embedded-svc project
• The embedded-hal project
• The Rust for Xtensa toolchain
• The Rust-with-STD demo project

Known limitations

• ESP IDF can’t be compiled on filesystems without support for symbolic links (e.g. FAT)

• projects that use a custom partitions.csv:

  • do not define CONFIG_PARTITION_TABLE_CUSTOM=y, CONFIG_PARTITION_TABLE_[CUSTOM_]FILENAME in your sdkconfig.defaults. The build would not use your custom partitions - nor does it need to.
  • for flashing use espflash flash [...] --partition-table partitions.csv