Crate esp_hal

Expand description

You might want to browse the esp-hal documentation on the esp-rs website instead.

The documentation here on docs.rs is built for a single chip only (ESP32-C6, in particular), while on the esp-rs website you can select your exact chip from the list of supported devices. Available peripherals and their APIs change depending on the chip.

§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-C6 . 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:

Name	Description	Default value	Allowed value
ESP_HAL_CONFIG_PLACE_SPI_DRIVER_IN_RAM	Places the SPI driver in RAM for better performance	false	-
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_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_CONFIG_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

§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.
clock: CPU Clock Control
configunstable: Configuration
debuggerunstable: Debugger utilities
delayunstable: Delay
dmaunstable: Direct Memory Access (DMA)
eccunstable: Elliptic Curve Cryptography (ECC) Accelerator
efuseunstable: Stability
etmunstable: Event Task Matrix (ETM)
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)
lp_coreunstable: Stability
mcpwmunstable: Motor Control Pulse Width Modulator (MCPWM)
parl_iounstable: Parallel IO (PARL_IO)
pcntunstable: Pulse Counter (PCNT)
peripheral: Exclusive peripheral access
peripherals: 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
spi: Serial Peripheral Interface (SPI)
systemunstable: System Control
timeunstable: Time
timerunstable: General-purpose Timers
traceunstable: RISC-V Trace Encoder (TRACE)
trapframe: State of the CPU saved when entering exception or interrupt
tsensunstable: Temperature Sensor (tsens)
twaiunstable: Two-wire Automotive Interface (TWAI)
uart: Universal Asynchronous Receiver/Transmitter (UART)
usb_serial_jtagunstable: USB Serial/JTAG Controller (USB_SERIAL_JTAG)

Macros§

chip: The name of the chip (“esp32c6”) as &str
dma_buffersunstable: Convenience macro to create DMA buffers and descriptors.
dma_buffers_chunk_sizeunstable: Convenience macro to create DMA buffers and descriptors with specific chunk size.
dma_circular_buffersunstable: Convenience macro to create circular DMA buffers and descriptors.
dma_circular_buffers_chunk_sizeunstable: Convenience macro to create circular DMA buffers and descriptors with specific chunk size.
dma_circular_descriptorsunstable: Convenience macro to create circular DMA descriptors.
dma_circular_descriptors_chunk_sizeunstable: Convenience macro to create circular DMA descriptors with specific chunk size
dma_descriptorsunstable: Convenience macro to create DMA descriptors.
dma_descriptors_chunk_sizeunstable: Convenience macro to create DMA descriptors with specific chunk size
dma_loop_bufferunstable: Convenience macro to create a DmaLoopBuf from a buffer size.
dma_rx_stream_bufferunstable: 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_bufferunstable: Convenience macro to create a DmaTxBuf from buffer size. The buffer and descriptors are statically allocated and used to create the DmaTxBuf.
load_lp_codeunstable: Load code to be run on the LP/ULP core.

Structs§

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

Enums§

Cpu: Available CPU cores

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

Crate esp_halCopy item path

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