#hal #idf #esp-idf #esp32

sys no-std esp-idf-hal

A Hardware abstraction layer for Espressif's ESP family of microcontrollers based on the ESP-IDF framework

66 releases

new 0.43.1 Feb 22, 2024
0.42.5 Nov 12, 2023
0.41.2 Jun 21, 2023
0.40.1 Dec 13, 2022
0.1.2 Aug 7, 2019

#23 in Embedded development

Download history 2802/week @ 2023-11-06 2481/week @ 2023-11-13 2593/week @ 2023-11-20 3060/week @ 2023-11-27 2251/week @ 2023-12-04 2030/week @ 2023-12-11 2305/week @ 2023-12-18 2859/week @ 2023-12-25 1790/week @ 2024-01-01 2208/week @ 2024-01-08 2162/week @ 2024-01-15 2825/week @ 2024-01-22 2938/week @ 2024-01-29 2275/week @ 2024-02-05 3119/week @ 2024-02-12 4978/week @ 2024-02-19

13,662 downloads per month
Used in 23 crates (21 directly)

MIT/Apache

705KB
15K SLoC

Safe Rust wrappers for the drivers in the ESP IDF SDK

CI crates.io Documentation Matrix Wokwi

Highlights

  • Implements the traits of embedded-hal V0.2 as well as those of V1.0 - both blocking and async
  • Supports almost all ESP IDF drivers: GPIO, SPI, I2C, TIMER, PWM, I2S, UART, etc.
  • Blocking and async mode for each driver (async support in progress)
  • Re-exports esp-idf-sys as esp_idf_hal::sys

You might want to also check out the ESP IDF Services wrappers, and the raw bindings to ESP IDF in the esp-idf-sys crate!

(For baremetal Rust ESP projects please check esp-hal.)

Build Prerequisites

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

Examples

The examples could be built and flashed conveniently with cargo-espflash. To run e.g. the ledc_simple 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 ledc_simple --monitor
MCU "--target"
esp32c2 riscv32imc-esp-espidf
esp32c3 riscv32imc-esp-espidf
esp32c6 riscv32imac-esp-espidf
esp32h2 riscv32imac-esp-espidf
esp32p4 riscv32imafc-esp-espidf
esp32 xtensa-esp32-espidf
esp32s2 xtensa-esp32s2-espidf
esp32s3 xtensa-esp32s3-espidf

In order to run the examples on other chips you will most likely need to adapt at least the used pins.

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:

Hardware Notes

Each chip has a number of GPIO pins which are generally used by the SPI0 and SPI1 peripherals in order to connect external PSRAM and/or SPI Flash memory. The datasheets explicitly state that these are not recommended for use, however this crate includes them anyways for completeness.

Please refer to the table below to determine the pins which are not recommended for use for your chip.

Chip GPIOs
ESP32 6 - 11, 16 - 17
ESP32-C2 12 - 17
ESP32-C3 12 - 17
ESP32-C6 24 - 30
ESP32-H2 15 - 21
ESP32-S2 26 - 32
ESP32-S3 26 - 32, 33 - 37*

* When using Octal Flash and/or Octal PSRAM

Dependencies

~4–13MB
~148K SLoC