Crate esp_bootloader_esp_idf

Source
Expand description

§Bootloader Support Library supplementing esp-hal

§Overview

This crate contains functionality related to the ESP-IDF 2nd stage bootloader.

  • populating the application-descriptor
  • read the partition table
  • conveniently use a partition to read and write flash contents

§Examples

§Populating the Application Descriptor

To use the default values:

#![no_std]
#![no_main]

#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! {
    loop {}
}

esp_bootloader_esp_idf::esp_app_desc!();

#[esp_hal::main]
fn main() -> ! {
    let _peripherals = esp_hal::init(esp_hal::Config::default());

    loop {}
}

If you want to customize the application descriptor:

#![no_std]
#![no_main]

#[panic_handler]
fn panic(_: &core::panic::PanicInfo) -> ! {
    loop {}
}

esp_bootloader_esp_idf::esp_app_desc!(
    // Version
    "1.0.0",
    // Project name
    "my_project",
    // Build time
    "12:00:00",
    // Build date
    "2021-01-01",
    // ESP-IDF version
    "4.4",
    // MMU page size
    8 * 1024,
    // Minimal eFuse block revision supported by image. Format: major * 100 + minor
    0,
    // Maximum eFuse block revision supported by image. Format: major * 100 + minor
    u16::MAX
);

#[esp_hal::main]
fn main() -> ! {
    let _peripherals = esp_hal::init(esp_hal::Config::default());

    loop {}
}

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

OptionStabilityDefault valueAllowed values

ESP_BOOTLOADER_ESP_IDF_CONFIG_MMU_PAGE_SIZE

ESP32-C2, ESP32-C6 and ESP32-H2 support configurable page sizes. This is currently only used to populate the app descriptor.

⚠️ Unstable64kOne of:
  • 8k
  • 16k
  • 32k
  • 64k

ESP_BOOTLOADER_ESP_IDF_CONFIG_ESP_IDF_VERSION

ESP-IDF version used in the application descriptor. Currently it’s not checked by the bootloader.

⚠️ Unstable0.0.0

ESP_BOOTLOADER_ESP_IDF_CONFIG_PARTITION_TABLE_OFFSET

The address of partition table (by default 0x8000). Allows you to move the partition table, it gives more space for the bootloader. Note that the bootloader and app will both need to be compiled with the same PARTITION_TABLE_OFFSET value.

⚠️ Unstable32768

§Feature Flags

  • validation (enabled by default) — Enable MD5 validation of the partition table.
  • log-04 — Enable support for version 0.4 of the log crate
  • defmt — Enable support for defmt

§Chip selection

One of the following features must be enabled to select the target chip:

  • esp32c2
  • esp32c3
  • esp32c6
  • esp32h2
  • esp32
  • esp32s2
  • esp32s3

Modules§

ota
Over The Air Updates (OTA)
partitions
Partition Table Support

Macros§

esp_app_desc
This macro populates the application descriptor (see EspAppDesc) which is available as a static named ESP_APP_DESC

Structs§

EspAppDesc
ESP-IDF compatible application descriptor

Constants§

BUILD_DATE
Build date
BUILD_TIME
Build time
ESP_IDF_COMPATIBLE_VERSION
The (pretended) ESP-IDF version
MMU_PAGE_SIZE
MMU page size in bytes