Crate esp_hal

source ·
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. 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 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 have a template for quick starting bare-metal projects, esp-template. The template uses cargo-generate, so ensure that it is installed and run

cargo generate -a esp-rs/esp-template

§Feature Flags

  • debug — Enable debug features in the HAL (used for development).
  • log — Enable logging output using the log crate.
  • place-spi-driver-in-ram — Configuration for placing device drivers in the IRAM for faster access.

§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!).
  • rv-init-data — Initialize the .data section of memory.
  • rv-zero-rtc-bss — Zero the .bss section of low-power memory.
  • rv-init-rtc-data — Initialize the .data section of low-power memory.

§Trait Implementation Feature Flags

  • async — Enable support for asynchronous operation, with interfaces provided by embedded-hal-async and embedded-io-async.
  • defmt — Implement defmt::Format on certain types.
  • embedded-hal (enabled by default) — Implement the traits defined in the 1.0.0 releases of embedded-hal and embedded-hal-nb for the relevant peripherals.
  • embedded-hal-02 — Implement the traits defined in the 0.2.x release of embedded-hal.
  • embedded-io — Implement the traits defined in embedded-io for certain peripherals.
  • ufmt — Implement the ufmt_write::uWrite trait for certain peripherals.

§Embassy Feature Flags

  • embassy — Enable support for embassy, a modern asynchronous embedded framework.
  • embassy-executor-interrupt — Use the interrupt-mode embassy executor.
  • embassy-executor-thread — Use the thread-mode embassy executor.
  • embassy-integrated-timers — Uses hardware timers as alarms for the executors. Using this feature limits the number of executors to the number of hardware alarms provided by the time driver.
  • embassy-time-systick-16mhz — Enable the embassy time driver using the SYSTIMER peripheral. The SYSTIMER peripheral has three alarams available for use. Do not use when targeting an esp32s2.
  • embassy-time-systick-80mhz — Enable the embassy time driver using the SYSTIMER peripheral. The SYSTIMER peripheral has three alarams available for use. Must only be used when targeting an esp32s2.
  • embassy-time-timg0 — Enable the embassy time driver using the TIMG0 peripheral. The TIMG0 peripheral has two alarms available for use.

§PSRAM Feature Flags

  • psram-2m — Use externally connected PSRAM (2MB).
  • psram-4m — Use externally connected PSRAM (4MB).
  • psram-8m — Use externally connected PSRAM (8MB).
  • psram-80mhz — PSRAM 80Mhz frequency support

§Octal RAM Feature Flags

  • opsram-2m — Use externally connected Octal RAM (2MB).
  • opsram-4m — Use externally connected Octal RAM (4MB).
  • opsram-8m — Use externally connected Octal RAM (8MB).
  • opsram-16m — Use externally connected Octal RAM (16MB).

Re-exports§

Modules§

  • aes
    Advanced Encryption Standard (AES) support.
  • analog
    Analog Peripherals
  • assist_debug
    Debug Assistant
  • clock
    Clock Control
  • delay
    Delay driver
  • dma
    Direct Memory Access Commons
  • ecc
    ECC Accelerator
  • efuse
    Reading of eFuses (ESP32-C6)
  • etm
    Event Task Matrix (ETM)
  • gpio
    General Purpose I/Os
  • hmac
    HMAC Accelerator
  • i2c
    I2C Driver
  • i2s
    I2S Master
  • interrupt
    Interrupt support
  • ledc
    LEDC (LED PWM Controller) peripheral control
  • lp_core
    Control the LP core
  • mcpwm
    MCPWM (Motor Control Pulse Width Modulator) peripheral
  • parl_io
    Parallel IO
  • pcnt
    Pulse Counter peripheral driver
  • peripheral
    Exclusive peripheral access
  • peripherals
    Peripheral Instances
  • prelude
    The prelude
  • reset
    Hardware and Software Reset
  • rmt
    Remote Control Peripheral (RMT)
  • rng
    Random Number Generator
  • rom
    ESP ROM libraries
  • rsa
    RSA Accelerator support.
  • rtc_cntl
    RTC_CNTL (Real-Time Clock Control) and Low-power Management
  • sha
    Secure Hash Algorithm peripheral driver
  • spi
    Serial Peripheral Interface
  • system
    System Control
  • systimer
    System Timer peripheral driver
  • timer
    General-purpose timers
  • trace
    RISC­V Trace Encoder (TRACE)
  • trapframe
    State of the CPU saved when entering exception or interrupt
  • twai
    Two-wire Automotive Interface (TWAI)
  • uart
    Universal Asynchronous Receiver/Transmitter (UART)
  • usb_serial_jtag
    USB Serial/JTAG Controller

Macros§

Structs§

Enums§

  • Cpu
    Available CPU cores

Traits§

  • Mode
    A marker trait for intializing drivers in a specific mode.

Functions§

  • get_core
    Which core the application is currently executing on

Attribute Macros§

  • entry
    Attribute to declare the entry point of the program