article: MCUboot Getting Start Guide for ESP32 #618

almir-okato · 2025-12-13T22:49:46Z

Description

Article translated and updated from my original from Embarcados portal.

Testing

Built and visualized using local hugo server.

Checklist

Before submitting a Pull Request, please ensure the following:

🚨 This PR does not introduce breaking changes.
All CI checks (GH Actions) pass.
Documentation is updated as needed.
Tests are updated or added as necessary.
Code is well-commented, especially in complex areas.
Git history is clean — commits are squashed to the minimum necessary.

FBEZ

Thank you @almir-okato for this article!

I’ve left a few comments for you to review. I also noticed that MCUBoot is in bold every time. I suggest keeping it plain or using a monospaced/verbatim style if needed.

content/blog/2025/12/mcuboot-getting-started/assets/mcuboot-process-overview1.webp

content/blog/2025/12/mcuboot-getting-started/index.md

almir-okato · 2025-12-17T18:00:12Z

Thank you @almir-okato for this article!

I’ve left a few comments for you to review. I also noticed that MCUBoot is in bold every time. I suggest keeping it plain or using a monospaced/verbatim style if needed.

Thanks @FBEZ

Regarding the bold style for MCUboot and some other names, I've tried to keep the directions suggested on the review of my previous article in the Developer Portal.
Should I change for MCUboot and the other terms?

FBEZ

@almir-okato thank you@ I’ve just added a final comment regarding the annotation block.
I still see MCUBoot in bold throughout. Would you like to keep it that way? I find it a bit eye straining.

content/blog/2025/12/mcuboot-getting-started/index.md

Article translated and updated from my original from Embarcados portal. Signed-off-by: Almir Okato <[email protected]>

github-actions · 2025-12-18T16:33:33Z

🎉 A preview for this PR is available at: https://preview-developer.espressif.com/pr618/

almir-okato · 2025-12-18T16:36:12Z

@almir-okato thank you@ I’ve just added a final comment regarding the annotation block. I still see MCUBoot in bold throughout. Would you like to keep it that way? I find it a bit eye straining.

I think you are right, I reduced the amount of names in bold, tried to keep only for first occurrences or some highlight notes. Thanks!

f-hollow · 2025-12-22T08:11:31Z

Thank you @almir-okato for this article!
I’ve left a few comments for you to review. I also noticed that MCUBoot is in bold every time. I suggest keeping it plain or using a monospaced/verbatim style if needed.

Thanks @FBEZ

Regarding the bold style for MCUboot and some other names, I've tried to keep the directions suggested on the review of my previous article in the Developer Portal. Should I change for MCUboot and the other terms?

@almir-okato Francesco is right about the formatting of MCUboot and other software names.

To be honest, I am not sure why we ended up with all terms in bold in your previous article. I checked all my comments and only found this edit related: #363 (comment)

However, I only proposed to make these words bold, because these are the summary words in bullet points, not because all software titles should be in bold. Sorry if I didn't make it clear!

f-hollow

@almir-okato Thank you for contributing this article!

I pointed a out a few nitpicks and shared some ideas on further content polishing.

f-hollow · 2025-12-22T08:15:30Z

content/blog/2025/12/mcuboot-getting-started/index.md

+authors:
+  - "almir-okato"
+tags: ["Bootloader", "MCUboot", "NuttX", "Zephyr"]
+summary: "This guide provides a practical getting‑started walkthrough for using MCUboot on ESP32. It covers step-by-step environment setup, bootloader building, application configuration, flashing, and gives an overview of the MCUboot's execution flow"


The comma separated list is already quite long. I suggest breaking it into two sentences to improve readability:

Suggested change

summary: "This guide provides a practical getting‑started walkthrough for using MCUboot on ESP32. It covers step-by-step environment setup, bootloader building, application configuration, flashing, and gives an overview of the MCUboot's execution flow"

summary: "This guide provides a practical getting‑started walkthrough for using MCUboot on ESP32. It covers step-by-step environment setup, bootloader building, application configuration, and flashing. It also gives an overview of MCUboot's execution flow."

f-hollow · 2025-12-22T08:23:26Z

content/blog/2025/12/mcuboot-getting-started/index.md

+In the embedded world, firmware updates are essential and increasingly important. As IoT solutions grow exponentially in numbers and complexity, so does the concern to make devices secure and updatable in the field efficiently.
+
+Some years ago, **MCUboot** emerged as an open source bootloader project for small and low-cost systems, designed to simplify and provide a standard in this field. It started as an Apache Mynewt subproject when developers decided to separate the bootloader from OS development. Later, it was ported to **Zephyr RTOS** and became its default bootloader.
+
+**Espressif Systems** has been broadening support for additional **third-party RTOSes** such as **Zephyr** and **NuttX**, offering developers more choices for its SoCs. For this reason, a port for Espressif SoCs has been created within the MCUboot project.
+
+This guide shows how to get started with MCUboot on your ESP32-based project.


The intro is short, but it answered all my questions about what MCUboot is and what it isn't.

It is a masterclass in economy of words. Nicely done!

f-hollow · 2025-12-22T08:24:03Z

content/blog/2025/12/mcuboot-getting-started/index.md

+This guide shows how to get started with MCUboot on your ESP32-based project.
+
+{{< alert icon="circle-info" cardColor="#b3e0f2" iconColor="#04a5e5">}}
+This is a translated and updated version of my original article in [Embarcados website](https://embarcados.com.br/primeiros-passos-com-esp32-utilizando-mcuboot-como-bootloader/).


Why not move this information immediately under Introduction? I believe it fits there better.

Suggested change

This is a translated and updated version of my original article in [Embarcados website](https://embarcados.com.br/primeiros-passos-com-esp32-utilizando-mcuboot-como-bootloader/).

This is a translated and updated version of my original article on the [Embarcados website](https://embarcados.com.br/primeiros-passos-com-esp32-utilizando-mcuboot-como-bootloader/).

f-hollow · 2025-12-22T08:37:00Z

content/blog/2025/12/mcuboot-getting-started/index.md

+This is a translated and updated version of my original article in [Embarcados website](https://embarcados.com.br/primeiros-passos-com-esp32-utilizando-mcuboot-como-bootloader/).
+{{< /alert >}}
+
+This articles covers environment setup, required configuration in the application side, how to build the **MCUboot Espressif Port** bootloader and how to flash it into the device. The [ESP32 DevKitC](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html) board was used to prepare this guide.


The summary mentions this for the hands-on part:

It covers step-by-step environment setup, bootloader building, application configuration, flashing.

This paragraph lists slightly different components. The table of contents has its own wording.

I suggest that you make all the three more consistent. Maybe you need to stay closer to what you have in your table of contents.

For example:

Suggested change

This articles covers environment setup, required configuration in the application side, how to build the **MCUboot Espressif Port** bootloader and how to flash it into the device. The [ESP32 DevKitC](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html) board was used to prepare this guide.

This articles covers what MCUboot is, how to set the environment and configure the application side, then how to build the MCUboot Espressif Port bootloader and flash it onto the device. We will use the [ESP32 DevKitC](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html) board in this guide.

f-hollow · 2025-12-22T08:44:08Z

content/blog/2025/12/mcuboot-getting-started/index.md

+This articles covers environment setup, required configuration in the application side, how to build the **MCUboot Espressif Port** bootloader and how to flash it into the device. The [ESP32 DevKitC](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html) board was used to prepare this guide.
+
+{{< alert icon="eye" >}}
+The MCUboot-compatible application mentioned in this guide can be either a NuttX RTOS application or a Zephyr RTOS application built for Espressif SoCs with MCUboot compatibility configuration enable.


You can make it slightly shorter.

Suggested change

The MCUboot-compatible application mentioned in this guide can be either a NuttX RTOS application or a Zephyr RTOS application built for Espressif SoCs with MCUboot compatibility configuration enable.

The MCUboot-compatible application in this guide can be either a NuttX or Zephyr RTOS application built for Espressif SoCs with MCUboot compatibility configuration enabled.

f-hollow · 2025-12-22T09:21:04Z

content/blog/2025/12/mcuboot-getting-started/index.md

+
+### **MCUboot Espressif Port** HAL
+
+The MCUboot Espressif Port relies on HAL (Hardware Abstraction Layer) sources provided by **ESP-IDF**. You must either have ESP-IDF installed, which allows building the project standalone, or use one of Espressif’s HAL sources available for Zephyr (`zephyrproject-rtos/hal_espressif/`) or NuttX (`espressif/esp-hal-3rdparty`). For the latter options, it is recommended to use them only within their respective RTOS build systems, as the source revisions may not match the expected versions.


The information is packed quite densely in this paragraph. Why not makeing it less dense and easier to scan/follow?

Would it be clear to the reader what zephyrproject-rtos/hal_espressif/ and espressif/esp-hal-3rdparty refer to?

Suggested change

The MCUboot Espressif Port relies on HAL (Hardware Abstraction Layer) sources provided by **ESP-IDF**. You must either have ESP-IDF installed, which allows building the project standalone, or use one of Espressif’s HAL sources available for Zephyr (`zephyrproject-rtos/hal_espressif/`) or NuttX (`espressif/esp-hal-3rdparty`). For the latter options, it is recommended to use them only within their respective RTOS build systems, as the source revisions may not match the expected versions.

The MCUboot Espressif Port relies on HAL (Hardware Abstraction Layer) sources provided by **ESP-IDF**. To build the project, you should have **one of the following**:

- Install ESP-IDF, which allows building the project standalone

- Use Zephyr (`zephyrproject-rtos/hal_espressif/`) HAL source from Espressif

- Use NuttX (`espressif/esp-hal-3rdparty`) HAL source from Espressif

For Zephyr and NuttX, it is recommended to use their respective RTOS build systems, as the source revisions may not match the expected versions.

f-hollow · 2025-12-22T09:25:00Z

content/blog/2025/12/mcuboot-getting-started/index.md

+    ```
+
+{{< alert icon="eye" >}}
+MCUboot repository includes some sample cryptographic keys for signing and testing the secure boot verification. It is crucial that you never use these keys in production since the private key is available in the MCUboot repository.


Suggested change

MCUboot repository includes some sample cryptographic keys for signing and testing the secure boot verification. It is crucial that you never use these keys in production since the private key is available in the MCUboot repository.

MCUboot repository includes some sample cryptographic keys for signing and testing the secure boot verification. It is crucial that you **never use these sample keys in production** since the private key is available in the MCUboot repository.

f-hollow · 2025-12-22T09:30:10Z

content/blog/2025/12/mcuboot-getting-started/index.md

+A **Zephyr** image with MCUboot compatibility doesn't need the `--pad-header` parameter.
+{{< /alert >}}
+
+Here is a quick look on what these `imgtool sign` parameters do:


Suggested change

Here is a quick look on what these `imgtool sign` parameters do:

Here is a quick look into what these `imgtool sign` parameters do:

f-hollow · 2025-12-22T09:32:01Z

content/blog/2025/12/mcuboot-getting-started/index.md

+- `-S 0x00150000`: Indicates the slot size so the tool can add the MCUboot trailer properly.
+
+{{< alert icon="circle-info" cardColor="#b3e0f2" iconColor="#04a5e5">}}
+This step just adds the basic required header, however notice that we didn't add any cryptographic key for security verification yet. It will be covered in the next parts of this MCUboot guide series. Refer to the [imgtool documentation](https://docs.mcuboot.com/imgtool.html) for more information.


Suggested change

This step just adds the basic required header, however notice that we didn't add any cryptographic key for security verification yet. It will be covered in the next parts of this MCUboot guide series. Refer to the [imgtool documentation](https://docs.mcuboot.com/imgtool.html) for more information.

This step just adds the basic required header, however notice that we didn't add any cryptographic key for security verification yet. It will be covered in the following parts of this MCUboot guide series. Refer to the [imgtool documentation](https://docs.mcuboot.com/imgtool.html) for more information.

f-hollow · 2025-12-22T09:37:14Z

content/blog/2025/12/mcuboot-getting-started/index.md

+
+The next step for this series is to understand how updates work in the MCUboot and use this feature appropriately.
+
+## References


How about using the standard name Resources here?

I recommend that you provide link text for each link with a brief explanation of what the reader will find if they click the link.

For example:

Building and using MCUboot with Espressif’s chips (MCUboot official docs)

almir-okato force-pushed the mcuboot_getting_started branch from fe53127 to 246809d Compare December 15, 2025 14:05

pedrominatel requested a review from FBEZ December 16, 2025 13:21

pedrominatel added the needs review Needs someone to be assigned to review label Dec 16, 2025

FBEZ reviewed Dec 16, 2025

View reviewed changes

FBEZ added Awaiting Response Awaiting a response from the author and removed needs review Needs someone to be assigned to review labels Dec 17, 2025

almir-okato force-pushed the mcuboot_getting_started branch 2 times, most recently from 60c251f to 58884b5 Compare December 17, 2025 15:40

almir-okato requested a review from FBEZ December 17, 2025 18:13

FBEZ reviewed Dec 18, 2025

View reviewed changes

content/blog/2025/12/mcuboot-getting-started/index.md Outdated Show resolved Hide resolved

article: MCUboot Getting Start Guide for ESP32

f1b3cc5

Article translated and updated from my original from Embarcados portal. Signed-off-by: Almir Okato <[email protected]>

almir-okato force-pushed the mcuboot_getting_started branch from 58884b5 to f1b3cc5 Compare December 18, 2025 16:30

almir-okato requested a review from FBEZ December 18, 2025 16:36

f-hollow reviewed Dec 22, 2025

View reviewed changes

	summary: "This guide provides a practical getting‑started walkthrough for using MCUboot on ESP32. It covers step-by-step environment setup, bootloader building, application configuration, flashing, and gives an overview of the MCUboot's execution flow"
	summary: "This guide provides a practical getting‑started walkthrough for using MCUboot on ESP32. It covers step-by-step environment setup, bootloader building, application configuration, and flashing. It also gives an overview of MCUboot's execution flow."

	This is a translated and updated version of my original article in [Embarcados website](https://embarcados.com.br/primeiros-passos-com-esp32-utilizando-mcuboot-como-bootloader/).
	This is a translated and updated version of my original article on the [Embarcados website](https://embarcados.com.br/primeiros-passos-com-esp32-utilizando-mcuboot-como-bootloader/).

	This articles covers environment setup, required configuration in the application side, how to build the MCUboot Espressif Port bootloader and how to flash it into the device. The [ESP32 DevKitC](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html) board was used to prepare this guide.
	This articles covers what MCUboot is, how to set the environment and configure the application side, then how to build the MCUboot Espressif Port bootloader and flash it onto the device. We will use the [ESP32 DevKitC](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/hw-reference/esp32/get-started-devkitc.html) board in this guide.

	The MCUboot-compatible application mentioned in this guide can be either a NuttX RTOS application or a Zephyr RTOS application built for Espressif SoCs with MCUboot compatibility configuration enable.
	The MCUboot-compatible application in this guide can be either a NuttX or Zephyr RTOS application built for Espressif SoCs with MCUboot compatibility configuration enabled.


		### MCUboot Espressif Port HAL

		The MCUboot Espressif Port relies on HAL (Hardware Abstraction Layer) sources provided by ESP-IDF. You must either have ESP-IDF installed, which allows building the project standalone, or use one of Espressif’s HAL sources available for Zephyr (`zephyrproject-rtos/hal_espressif/`) or NuttX (`espressif/esp-hal-3rdparty`). For the latter options, it is recommended to use them only within their respective RTOS build systems, as the source revisions may not match the expected versions.

-The MCUboot Espressif Port relies on HAL (Hardware Abstraction Layer) sources provided by **ESP-IDF**. You must either have ESP-IDF installed, which allows building the project standalone, or use one of Espressif’s HAL sources available for Zephyr (`zephyrproject-rtos/hal_espressif/`) or NuttX (`espressif/esp-hal-3rdparty`). For the latter options, it is recommended to use them only within their respective RTOS build systems, as the source revisions may not match the expected versions.
+The MCUboot Espressif Port relies on HAL (Hardware Abstraction Layer) sources provided by **ESP-IDF**. To build the project, you should have **one of the following**:
+- Install ESP-IDF, which allows building the project standalone
+- Use Zephyr (`zephyrproject-rtos/hal_espressif/`) HAL source from Espressif
+- Use NuttX (`espressif/esp-hal-3rdparty`) HAL source from Espressif
+For Zephyr and NuttX, it is recommended to use their respective RTOS build systems, as the source revisions may not match the expected versions.

	MCUboot repository includes some sample cryptographic keys for signing and testing the secure boot verification. It is crucial that you never use these keys in production since the private key is available in the MCUboot repository.
	MCUboot repository includes some sample cryptographic keys for signing and testing the secure boot verification. It is crucial that you never use these sample keys in production since the private key is available in the MCUboot repository.

	Here is a quick look on what these `imgtool sign` parameters do:
	Here is a quick look into what these `imgtool sign` parameters do:

	This step just adds the basic required header, however notice that we didn't add any cryptographic key for security verification yet. It will be covered in the next parts of this MCUboot guide series. Refer to the [imgtool documentation](https://docs.mcuboot.com/imgtool.html) for more information.
	This step just adds the basic required header, however notice that we didn't add any cryptographic key for security verification yet. It will be covered in the following parts of this MCUboot guide series. Refer to the [imgtool documentation](https://docs.mcuboot.com/imgtool.html) for more information.


		The next step for this series is to understand how updates work in the MCUboot and use this feature appropriately.

		## References

article: MCUboot Getting Start Guide for ESP32 #618

Are you sure you want to change the base?

article: MCUboot Getting Start Guide for ESP32 #618

Uh oh!

Conversation

almir-okato commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related

Testing

Checklist

Uh oh!

FBEZ left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

almir-okato commented Dec 17, 2025

Uh oh!

FBEZ left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Dec 18, 2025

Uh oh!

almir-okato commented Dec 18, 2025

Uh oh!

f-hollow commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

f-hollow left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

almir-okato commented Dec 13, 2025 •

edited

Loading

f-hollow commented Dec 22, 2025 •

edited

Loading