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-S2 . 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]

use esp_hal::{
    clock::CpuClock,
    gpio::{Io, Level, Output, OutputConfig},
    main,
    time::{Duration, Instant},
};

// You need a panic handler. Usually, you you would use esp_backtrace, panic-probe, or
// something similar, but you can also bring your own like this:
#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! {
    esp_hal::system::software_reset()
}

#[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, OutputConfig::default());

    loop {
        led.toggle();
        // Wait for half a second
        let delay_start = Instant::now();
        while delay_start.elapsed() < Duration::from_millis(500) {}
    }
}

§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 valueAllowed value
ESP_HAL_CONFIG_PLACE_SPI_DRIVER_IN_RAMPlaces the SPI driver in RAM for better performancefalse-
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-
ESP_HAL_CONFIG_XTAL_FREQUENCYThe frequency of the crystal oscillator, in MHz. Set to auto to automatically detect the frequency. auto may not be able to identify the clock frequency in some cases. Also, configuring a specific frequency may increase performance slightly.40Any of [“40”]
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_FLIP_LINK(ESP32-C6/ESP32-H2 only): Move the stack to start of RAM to get zero-cost stack overflow protection.false-
ESP_HAL_CONFIG_PSRAM_MODE(ESP32, ESP32-S2 and ESP32-S3 only, octal is only supported for ESP32-S3) SPIRAM chip modequadAny of [“quad”, “octal”]

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.

§Trait Implementation Feature Flags

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

§PSRAM Feature Flags

  • psram — Use externally connected PSRAM (quad by default, can be configured to octal via ESP_HAL_CONFIG_PSRAM_MODE)

§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 — Enables APIs that are not stable and thus come with no stability guarantees.

Re-exports§

  • pub use xtensa_lx_rt;
    unstable
  • pub use xtensa_lx_rt::xtensa_lx;
    unstable

Modules§

  • aesunstable
    Advanced Encryption Standard (AES).
  • analogunstable
    Analog Peripherals
  • asynchunstable
    Asynchronous utilities.
  • clock
    CPU Clock Control
  • configunstable
    Configuration
  • debuggerunstable
    Debugger utilities
  • delayunstable
    Delay
  • dmaunstable
    Direct Memory Access (DMA)
  • efuseunstable
    Stability
  • gpio
    General Purpose Input/Output (GPIO)
  • hmacunstable
    Hash-based Message Authentication Code (HMAC) Accelerator
  • i2c
    Inter-Integrated Circuit (I2C)
  • i2sunstable
    Inter-IC Sound (I2S)
  • interruptunstable
    Interrupt support
  • ledcunstable
    LED Controller (LEDC)
  • otg_fsunstable
    USB On-The-Go (USB OTG)
  • pcntunstable
    Pulse Counter (PCNT)
  • peripheral
    Exclusive peripheral access
  • peripherals
    Peripheral Instances
  • psramunstable
    Stability
  • 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
  • spi
    Serial Peripheral Interface (SPI)
  • system
    System Control
  • time
    Timekeeping
  • timerunstable
    General-purpose Timers
  • trapframeunstable
    State of the CPU saved when entering exception or interrupt
  • twaiunstable
    Two-wire Automotive Interface (TWAI)
  • uart
    Universal Asynchronous Receiver/Transmitter (UART)
  • ulp_coreunstable
    Stability

Macros§

Structs§

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

Traits§

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

Functions§

  • init
    Initialize the system.

Attribute Macros§

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