Crate esp_hal

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 . 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::{
    delay::Delay,
    gpio::{Io, Level, Output},
    prelude::*,
};

#[entry]
fn main() -> ! {
    let peripherals = esp_hal::init({
        let mut config = esp_hal::Config::default();
        // Configure the CPU to run at the maximum frequency.
        config.cpu_clock = CpuClock::max();
        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:

Name	Description	Default value
ESP_HAL_PLACE_SPI_DRIVER_IN_RAM	Places the SPI driver in RAM for better performance	false
ESP_HAL_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_PLACE_SWITCH_TABLES_IN_RAM	Places 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_PLACE_ANON_IN_RAM	Places 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

Re-exports

• pub use xtensa_lx;
• pub use xtensa_lx_rt;

Modules

• aes
  Advanced Encryption Standard (AES).
• analog
  Analog Peripherals
• clock
  CPU Clock Control
• config
  Configuration
• cpu_control
  Control CPU Cores (ESP32)
• debugger
  Debugger utilities
• delay
  Delay
• dma
  Direct Memory Access (DMA)
• efuse
  Reading of eFuses (ESP32)
• gpio
  General Purpose Input/Output (GPIO)
• i2c
  Inter-Integrated Circuit (I2C)
• i2s
  Inter-IC Sound (I2S)
• interrupt
  Interrupt support
• ledc
  LED Controller (LEDC)
• macros
  Macros used by the HAL.
• mcpwm
  Motor Control Pulse Width Modulator (MCPWM)
• pcnt
  Pulse Counter (PCNT)
• peripheral
  Exclusive peripheral access
• peripherals
  Peripheral Instances
• prelude
  The esp-hal Prelude
• psram
  PSRAM “virtual peripheral” driver (ESP32)
• reset
  Hardware and Software Reset
• rmt
  Remote Control Peripheral (RMT)
• rng
  Random Number Generator (RNG)
• rom
  ESP ROM libraries
• rsa
  RSA (Rivest–Shamir–Adleman) accelerator.
• rtc_cntl
  Real-Time Control and Low-power Management (RTC_CNTL)
• sha
  Secure Hash Algorithm (SHA) Accelerator
• spi
  Serial Peripheral Interface (SPI)
• system
  System Control
• time
  Time
• timer
  General-purpose Timers
• touch
  Capacitive Touch Sensor
• trapframe
  State of the CPU saved when entering exception or interrupt
• twai
  Two-wire Automotive Interface (TWAI)
• uart
  Universal Asynchronous Receiver/Transmitter (UART)

Macros

• chip
  The name of the chip (“esp32”) as &str
• dma_buffers
  Convenience macro to create DMA buffers and descriptors.
• dma_buffers_chunk_size
  Convenience macro to create DMA buffers and descriptors with specific chunk size.
• dma_circular_buffers
  Convenience macro to create circular DMA buffers and descriptors.
• dma_circular_buffers_chunk_size
  Convenience macro to create circular DMA buffers and descriptors with specific chunk size.
• dma_circular_descriptors
  Convenience macro to create circular DMA descriptors.
• dma_circular_descriptors_chunk_size
  Convenience macro to create circular DMA descriptors with specific chunk size
• dma_descriptors
  Convenience macro to create DMA descriptors.
• dma_descriptors_chunk_size
  Convenience macro to create DMA descriptors with specific chunk size
• dma_loop_buffer
  Convenience macro to create a DmaLoopBuf from a buffer size.
• dma_rx_stream_buffer
  Convenience macro to create a DmaRxStreamBuf from buffer size and optional chunk size (uses max if unspecified). The buffer and descriptors are statically allocated and used to create the DmaRxStreamBuf.
• dma_tx_buffer
  Convenience macro to create a DmaTxBuf from buffer size. The buffer and descriptors are statically allocated and used to create the DmaTxBuf.

Structs

• Async
  Driver initialized in async mode.
• Blocking
  Driver initialized in blocking mode.
• Config
  System configuration.

Enums

• Cpu
  Available CPU cores

Constants

• DEFAULT_INTERRUPT_HANDLER
  Default (unhandled) interrupt handler

Traits

• InterruptConfigurable
  Trait implemented by drivers which allow the user to set an interrupt::InterruptHandler
• Mode
  A marker trait for initializing drivers in a specific mode.
• Persistable
  Marker trait for types that can be safely used in #[ram(persistent)].

Functions

• init
  Initialize the system.

Attribute Macros

• entry
  Marks a function as the main function to be called on program start