Skip to content

espressif: update conf files and readme-espressif.md documentation #2580

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nvlsianpu merged 2 commits into from
Dec 23, 2025
+90 −58
Merged

espressif: update conf files and readme-espressif.md documentation #2580

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
86e14d4
espressif: update default bootloader.conf files
almir-okato Dec 12, 2025
d262a0b
espressif: update readme-espressif.md documentation
almir-okato Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions boot/espressif/port/esp32/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x1000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0x150000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x170000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x3E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -107,5 +107,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
# CONFIG_EFUSE_VIRTUAL=1
# CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
# CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
14 changes: 7 additions & 7 deletions boot/espressif/port/esp32c2/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@
# CONFIG_ESP_BOOT_SWAP_USING_MOVE=y
# CONFIG_ESP_BOOT_UPGRADE_ONLY=y

CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_FLASH_SIZE=2MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x0000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0xC0000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0xE0000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x1E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -93,5 +93,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
# CONFIG_EFUSE_VIRTUAL=1
# CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
# CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
12 changes: 6 additions & 6 deletions boot/espressif/port/esp32c3/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x0000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0x1C0000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x3E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -94,5 +94,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
# CONFIG_EFUSE_VIRTUAL=1
# CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
# CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
12 changes: 6 additions & 6 deletions boot/espressif/port/esp32c6/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x0000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0x1C0000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x3E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -94,5 +94,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
CONFIG_EFUSE_VIRTUAL=1
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
12 changes: 6 additions & 6 deletions boot/espressif/port/esp32h2/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x0000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0x1C0000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x3E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -96,5 +96,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
# CONFIG_EFUSE_VIRTUAL=1
# CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
# CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
12 changes: 6 additions & 6 deletions boot/espressif/port/esp32s2/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x1000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0x1C0000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x1E0000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x3E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -90,5 +90,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
# CONFIG_EFUSE_VIRTUAL=1
# CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
# CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
12 changes: 6 additions & 6 deletions boot/espressif/port/esp32s3/bootloader.conf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,12 @@
CONFIG_ESP_FLASH_SIZE=4MB
CONFIG_ESP_BOOTLOADER_SIZE=0xF000
CONFIG_ESP_BOOTLOADER_OFFSET=0x0000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x10000
CONFIG_ESP_APPLICATION_SIZE=0x100000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x110000
CONFIG_ESP_IMAGE0_PRIMARY_START_ADDRESS=0x20000
CONFIG_ESP_APPLICATION_SIZE=0x150000
CONFIG_ESP_IMAGE0_SECONDARY_START_ADDRESS=0x170000
CONFIG_ESP_MCUBOOT_WDT_ENABLE=y
CONFIG_ESP_SCRATCH_OFFSET=0x210000
CONFIG_ESP_SCRATCH_SIZE=0x40000
CONFIG_ESP_SCRATCH_OFFSET=0x3E0000
CONFIG_ESP_SCRATCH_SIZE=0x1F000

# When enabled, prevents updating image to an older version
# CONFIG_ESP_DOWNGRADE_PREVENTION=y
Expand Down Expand Up @@ -114,5 +114,5 @@ CONFIG_ESP_CONSOLE_UART_NUM=0
# to not overlap with other flash regions)
# CONFIG_EFUSE_VIRTUAL=1
# CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
# CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
# CONFIG_EFUSE_VIRTUAL_SIZE=0x2000
62 changes: 47 additions & 15 deletions docs/readme-espressif.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,13 @@ dependent, therefore, the system environment including toolchains, must be set a
standalone build version means that ESP-IDF and its toolchain are used as source. For 3rd parties
framework, HAL path and toolchain must be set.

---
***Note***

*Current compatible ESP-IDF version for HAL sources is `v5.1.6`*

---

Documentation about the MCUboot bootloader design, operation and features can be found in the
[design document](design.md).

Expand All @@ -16,7 +23,7 @@ The current port is available for use in the following SoCs within the OSes:

| | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C2 | ESP32-C6 | ESP32-H2 |
| :----: | :-------: | :-------: | :-------: | :-------: | :---------: | :-------: | :---------: |
| Zephyr | Supported | Supported | Supported | Supported | Supported | Supported | In progress |
| Zephyr | Supported | Supported | Supported | Supported | Supported | Supported | Supported |
| NuttX | Supported | Supported | Supported | Supported | In progress | Supported | Supported |

Notice that any customization in the memory layout from the OS application must be done aware of
Expand Down Expand Up @@ -44,7 +51,12 @@ The following instructions considers a MCUboot Espressif port standalone build.
```

3. If ESP-IDF is the chosen option for use as HAL layer and the system already have ESP-IDF
installed, ensure that the environment is set:
installed, ensure that it is the current compatible version and the environment is set:

```bash
cd <IDF_PATH>
git checkout v5.1.6
```

```bash
<IDF_PATH>/install.sh
Expand Down Expand Up @@ -140,18 +152,27 @@ Additional configuration related to MCUboot features and slot partitioning may b
ninja -C build/ flash
```

If `MCUBOOT_FLASH_PORT` arg was not passed to `cmake`, the default `PORT` for flashing will be
`/dev/ttyUSB0`.
If the below arguments were not passed to `cmake` build step, the default values for each on
the flashing operation will be as following:

Alternatively:
- `MCUBOOT_FLASH_PORT`: "/dev/ttyUSB0"
- `ESP_BAUD_RATE`: 115200
- `ESP_FLASH_MODE`: "dio"
- `ESP_FLASH_FREQ`: "40m" for ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6;
"60m" for ESP32-C2;
"24m" for ESP32-H2.

Alternatively, `esptool` can be used for flashing directly:

```bash
esptool.py -p <PORT> -b <BAUD> --before default_reset --after no_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> build/mcuboot_<TARGET>.bin
esptool.py -p <PORT> -b <BAUD> --before default_reset --after no_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <BOOTLOADER_FLASH_OFFSET> build/mcuboot_<TARGET>.bin
```

---
***Note***

Ensure that the flash parameters like `<FLASH_FREQ>`, `<FLASH_MODE>`, `<FLASH_SIZE>` matches
the same parameters from `cmake` step and configuration file.
You may adjust the port `<PORT>` (like `/dev/ttyUSB0`) and baud rate `<BAUD>` (like `2000000`)
according to the connection with your board. You can also skip `<PORT>` and `<BAUD>` parameters
so that esptool tries to automatically detect it.
Expand Down Expand Up @@ -209,7 +230,7 @@ Additional configuration related to MCUboot features and slot partitioning may b
2. Flash the signed application:

```bash
esptool.py -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <SLOT_OFFSET> <SIGNED_BIN>
esptool.py -p <PORT> -b <BAUD> --before default_reset --after hard_reset --chip <TARGET> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <SLOT_OFFSET> <SIGNED_BIN>
```

# [Downgrade prevention](#downgrade-prevention)
Expand Down Expand Up @@ -366,10 +387,14 @@ CONFIG_SECURE_FLASH_UART_BOOTLOADER_ALLOW_CACHE=1
# to not overlap with other flash regions)
CONFIG_EFUSE_VIRTUAL=1
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
CONFIG_EFUSE_VIRTUAL_SIZE=0x2000

```

Observe that the region defined by `CONFIG_EFUSE_VIRTUAL_OFFSET` and `CONFIG_EFUSE_VIRTUAL_SIZE`
must not overlap with other flash regions.

---

---
Expand Down Expand Up @@ -420,10 +445,13 @@ key are correct and you did not forget anything before flashing.*
---

Flash the bootloader as following, with `--after no_reset` flag, so you can reset the device only
when assured:
when assured. Also ensure that the flash parameters like `<FLASH_FREQ>`, `<FLASH_MODE>`,
`<FLASH_SIZE>` matches the same parameters from `cmake` step and configuration file, this is
important because `esptool` may modify the binary if it detects that these parameters are
different from what they were on the building.

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <SIGNED_BOOTLOADER_BIN>
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <BOOTLOADER_FLASH_OFFSET> <SIGNED_BOOTLOADER_BIN>
```

### [Secure Boot Process](#secure-boot-process)
Expand Down Expand Up @@ -510,10 +538,14 @@ CONFIG_SECURE_BOOT_ALLOW_JTAG=1
# to not overlap with other flash regions)
CONFIG_EFUSE_VIRTUAL=1
CONFIG_EFUSE_VIRTUAL_KEEP_IN_FLASH=1
CONFIG_EFUSE_VIRTUAL_OFFSET=0x250000
CONFIG_EFUSE_VIRTUAL_OFFSET=0x10000
CONFIG_EFUSE_VIRTUAL_SIZE=0x2000

```

Observe that the region defined by `CONFIG_EFUSE_VIRTUAL_OFFSET` and `CONFIG_EFUSE_VIRTUAL_SIZE`
must not overlap with other flash regions.

---

---
Expand Down Expand Up @@ -583,11 +615,11 @@ the SPI Flash.
Flash the bootloader and application normally:

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>
```

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>
```

On the **first boot**, the bootloader will:
Expand Down Expand Up @@ -642,11 +674,11 @@ of generate a new one.
Flashing the bootloader and application:

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <BOOTLOADER_FLASH_OFFSET> <BOOTLOADER_BIN>
```

```bash
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq 40m <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>
esptool.py -p <PORT> -b 2000000 --after no_reset --chip <ESP_CHIP> write_flash --flash_mode dio --flash_size <FLASH_SIZE> --flash_freq <FLASH_FREQ> <PRIMARY_SLOT_FLASH_OFFSET> <APPLICATION_BIN>
```

On the **first boot**, the bootloader will:
Expand Down
Loading