Crate esp_hal

Source
Expand description

§Bare-metal (no_std) HAL for all Espressif ESP32 devices.

§Overview

The HAL implements both blocking and async APIs for many peripherals. Where applicable, driver implement the embedded-hal and embedded-hal-async traits.

This documentation is built for the ESP32-C3 . Please ensure you are reading the correct documentation for your target device.

§Choosing a Device

Depending on your target device, you need to enable the chip feature for that device. You may also need to do this on ancillary esp-hal crates.

§Examples

We have a plethora of examples in the esp-hal repository. We use an xtask to automate the building, running, and testing of code and examples within esp-hal.

Invoke the following command in the root of the esp-hal repository to get started:

cargo xtask help

§Creating a Project

We have a book that explains the full esp-rs ecosystem and how to get started, it’s advisable to give that a read before proceeding. We also have a training that covers some common scenarios with examples.

We have developed a project generation tool, esp-generate, which we recommend when starting new projects. It can be installed and run, e.g. for the ESP32-C6, as follows:

cargo install esp-generate
esp-generate --chip=esp32c6 your-project

§Blinky

Some minimal code to blink an LED looks like this:

#![no_std]
#![no_main]

// You'll need a panic handler e.g. `use esp_backtrace as _;`
use esp_hal::{
    clock::CpuClock,
    delay::Delay,
    gpio::{Io, Level, Output},
    main,
};

#[main]
fn main() -> ! {
    let config = esp_hal::Config::default().with_cpu_clock(CpuClock::max());
    let peripherals = esp_hal::init(config);

    // Set GPIO0 as an output, and set its state high initially.
    let mut led = Output::new(peripherals.GPIO0, Level::High);

    let delay = Delay::new();

    loop {
        led.toggle();
        delay.delay_millis(1000);
    }
}

§Additional configuration

We’ve exposed some configuration options that don’t fit into cargo features. These can be set via environment variables, or via cargo’s [env] section inside .cargo/config.toml. Below is a table of tunable parameters for this crate:

NameDescriptionDefault value
ESP_HAL_CONFIG_PLACE_SPI_DRIVER_IN_RAMPlaces the SPI driver in RAM for better performancefalse
ESP_HAL_CONFIG_SPI_ADDRESS_WORKAROUND(ESP32 only) Enables a workaround for the issue where SPI in half-duplex mode incorrectly transmits the address on a single line if the data buffer is empty.true
ESP_HAL_CONFIG_PLACE_SWITCH_TABLES_IN_RAMPlaces switch-tables, some lookup tables and constants related to interrupt handling into RAM - resulting in better performance but slightly more RAM consumption.true
ESP_HAL_CONFIG_PLACE_ANON_IN_RAMPlaces anonymous symbols into RAM - resulting in better performance at the cost of significant more RAM consumption. Best to be combined with place-switch-tables-in-ram.false

It’s important to note that due to a bug in cargo, any modifications to the environment, local or otherwise will only get picked up on a full clean build of the project.

§Peripheral Pattern

Drivers take pins and peripherals as peripheral::Peripheral in most circumstances. This means you can pass the pin/peripheral or a mutable reference to the pin/peripheral.

The latter can be used to regain access to the pin when the driver gets dropped. Then it’s possible to reuse the pin/peripheral for a different purpose.

§Don’t use core::mem::forget

You should never use core::mem::forget on any type defined in the HAL. Some types heavily rely on their Drop implementation to not leave the hardware in undefined state and causing UB.

You might want to consider using #[deny(clippy::mem_forget) in your project.

§Feature Flags

  • debug — Enable debug features in the HAL (used for development).
  • log — Enable logging output using the log crate.

§RISC-V Exclusive Feature Flags

  • flip-link — Move the stack to start of RAM to get zero-cost stack overflow protection (ESP32-C6 and ESPS32-H2 only!).

§Trait Implementation Feature Flags

  • defmt — Implement defmt::Format on certain types.

§PSRAM Feature Flags

  • quad-psram — Use externally connected Quad PSRAM
  • octal-psram — Use externally connected Octal RAM

§Unstable APIs

Unstable APIs are drivers and features that are not yet ready for general use. They may be incomplete, have bugs, or be subject to change without notice. Unstable APIs are not covered by semver guarantees.

  • unstable (enabled by default) — Enables APIs that are not stable and thus come with no stability guarantees.

Re-exports§

  • pub use esp_riscv_rt;
    unstable
  • pub use esp_riscv_rt::riscv;
    unstable

Modules§

  • aesunstable
    Advanced Encryption Standard (AES).
  • analogunstable
    Analog Peripherals
  • assist_debugunstable
    Debug Assistant (ASSIST_DEBUG)
  • asynchunstable
    Asynchronous utilities.
  • CPU Clock Control
  • configunstable
    Configuration
  • debuggerunstable
    Debugger utilities
  • delayunstable
    Delay
  • dmaunstable
    Direct Memory Access (DMA)
  • efuseunstable
    Stability
  • General Purpose Input/Output (GPIO)
  • hmacunstable
    Hash-based Message Authentication Code (HMAC) Accelerator
  • Inter-Integrated Circuit (I2C)
  • i2sunstable
    Inter-IC Sound (I2S)
  • interruptunstable
    Interrupt support
  • ledcunstable
    LED Controller (LEDC)
  • Exclusive peripheral access
  • Peripheral Instances
  • resetunstable
    Hardware and Software Reset
  • rmtunstable
    Remote Control Peripheral (RMT)
  • rngunstable
    Random Number Generator (RNG)
  • romunstable
    ESP ROM libraries
  • rsaunstable
    RSA (Rivest–Shamir–Adleman) accelerator.
  • rtc_cntlunstable
    Real-Time Control and Low-power Management (RTC_CNTL)
  • shaunstable
    Secure Hash Algorithm (SHA) Accelerator
  • Serial Peripheral Interface (SPI)
  • systemunstable
    System Control
  • timeunstable
    Time
  • timerunstable
    General-purpose Timers
  • State of the CPU saved when entering exception or interrupt
  • tsensunstable
    Temperature Sensor (tsens)
  • twaiunstable
    Two-wire Automotive Interface (TWAI)
  • Universal Asynchronous Receiver/Transmitter (UART)
  • USB Serial/JTAG Controller (USB_SERIAL_JTAG)

Macros§

Structs§

  • Driver initialized in async mode.
  • Driver initialized in blocking mode.
  • System configuration.

Enums§

  • Available CPU cores

Traits§

  • A marker trait for initializing drivers in a specific mode.
  • Persistableunstable
    Marker trait for types that can be safely used in #[ram(persistent)].

Functions§

  • Initialize the system.

Attribute Macros§

  • handlerunstable
    Stability
  • Attribute to declare the entry point of the program
  • ramunstable
    Stability