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-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 |
---|---|---|
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 thelog
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
— Implementdefmt::Format
on certain types.
§PSRAM Feature Flags
quad-psram
— Use externally connected Quad PSRAMoctal-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§
- aes
unstable
Advanced Encryption Standard (AES). - analog
unstable
Analog Peripherals - assist_
debug unstable
Debug Assistant (ASSIST_DEBUG) - asynch
unstable
Asynchronous utilities. - CPU Clock Control
- config
unstable
Configuration - debugger
unstable
Debugger utilities - delay
unstable
Delay - dma
unstable
Direct Memory Access (DMA) - ecc
unstable
Elliptic Curve Cryptography (ECC) Accelerator - efuse
unstable
Stability - etm
unstable
Event Task Matrix (ETM) - General Purpose Input/Output (GPIO)
- hmac
unstable
Hash-based Message Authentication Code (HMAC) Accelerator - Inter-Integrated Circuit (I2C)
- i2s
unstable
Inter-IC Sound (I2S) - interrupt
unstable
Interrupt support - ledc
unstable
LED Controller (LEDC) - lp_core
unstable
Stability - mcpwm
unstable
Motor Control Pulse Width Modulator (MCPWM) - parl_io
unstable
Parallel IO (PARL_IO) - pcnt
unstable
Pulse Counter (PCNT) - Exclusive peripheral access
- Peripheral Instances
- reset
unstable
Hardware and Software Reset - rmt
unstable
Remote Control Peripheral (RMT) - rng
unstable
Random Number Generator (RNG) - rom
unstable
ESP ROM libraries - rsa
unstable
RSA (Rivest–Shamir–Adleman) accelerator. - rtc_
cntl unstable
Real-Time Control and Low-power Management (RTC_CNTL) - sha
unstable
Secure Hash Algorithm (SHA) Accelerator - Serial Peripheral Interface (SPI)
- system
unstable
System Control - time
unstable
Time - timer
unstable
General-purpose Timers - trace
unstable
RISC-V Trace Encoder (TRACE) - State of the CPU saved when entering exception or interrupt
- tsens
unstable
Temperature Sensor (tsens) - twai
unstable
Two-wire Automotive Interface (TWAI) - Universal Asynchronous Receiver/Transmitter (UART)
- usb_
serial_ jtag unstable
USB Serial/JTAG Controller (USB_SERIAL_JTAG)
Macros§
- The name of the chip (“esp32c6”) as
&str
- dma_
buffers unstable
Convenience macro to create DMA buffers and descriptors. - dma_
buffers_ chunk_ size unstable
Convenience macro to create DMA buffers and descriptors with specific chunk size. - dma_
circular_ buffers unstable
Convenience macro to create circular DMA buffers and descriptors. - dma_
circular_ buffers_ chunk_ size unstable
Convenience macro to create circular DMA buffers and descriptors with specific chunk size. - dma_
circular_ descriptors unstable
Convenience macro to create circular DMA descriptors. - Convenience macro to create circular DMA descriptors with specific chunk size
- dma_
descriptors unstable
Convenience macro to create DMA descriptors. - dma_
descriptors_ chunk_ size unstable
Convenience macro to create DMA descriptors with specific chunk size - dma_
loop_ buffer unstable
Convenience macro to create a DmaLoopBuf from a buffer size. - dma_
rx_ stream_ buffer unstable
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 unstable
Convenience macro to create a DmaTxBuf from buffer size. The buffer and descriptors are statically allocated and used to create theDmaTxBuf
. - load_
lp_ code unstable
Load code to be run on the LP/ULP core.
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.
- Persistable
unstable
Marker trait for types that can be safely used in#[ram(persistent)]
.
Functions§
- Initialize the system.