From c0866030ebc9c0588eb349de34eb96af5317161e Mon Sep 17 00:00:00 2001 From: Marek Matej Date: Tue, 19 Mar 2024 18:20:30 +0100 Subject: [PATCH] boards: Update ESP32 related documentation Update the note on the booting method for all ESP32 related boards. Signed-off-by: Marek Matej --- .../esp32_devkitc_wroom/doc/index.rst | 88 ++++++++++++++++++- .../esp32_devkitc_wrover/doc/index.rst | 13 +-- .../esp32_ethernet_kit/doc/index.rst | 13 +-- .../espressif/esp32c3_devkitm/doc/index.rst | 13 +-- boards/espressif/esp32s2_saola/doc/index.rst | 13 +-- .../espressif/esp32s3_devkitm/doc/index.rst | 13 +-- boards/espressif/esp_wrover_kit/doc/index.rst | 13 +-- .../esp32s2_franzininho/doc/index.rst | 13 +-- .../heltec_wifi_lora32_v2/doc/index.rst | 13 +-- .../doc/index.rst | 13 +-- .../luatos/esp32c3_luatos_core/doc/index.rst | 13 +-- .../luatos/esp32s3_luatos_core/doc/index.rst | 13 +-- boards/olimex/olimex_esp32_evb/doc/index.rst | 13 +-- boards/others/icev_wireless/doc/index.rst | 13 +-- boards/seeed/xiao_esp32c3/doc/index.rst | 13 +-- boards/seeed/xiao_esp32s3/doc/index.rst | 13 +-- boards/vcc-gnd/yd_esp32/doc/index.rst | 13 +-- 17 files changed, 214 insertions(+), 82 deletions(-) diff --git a/boards/espressif/esp32_devkitc_wroom/doc/index.rst b/boards/espressif/esp32_devkitc_wroom/doc/index.rst index 7b0d7d8964c..ec1248da38e 100644 --- a/boards/espressif/esp32_devkitc_wroom/doc/index.rst +++ b/boards/espressif/esp32_devkitc_wroom/doc/index.rst @@ -115,7 +115,91 @@ below to retrieve those files. It is recommended running the command above after :file:`west update`. Building & Flashing -------------------- +******************* + +Simple boot +=========== + +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. + +MCUboot bootloader +================== + +User may choose to use MCUboot bootloader instead. In that case the bootloader +must be build (and flash) at least once. + +There are two options to be used when building an application: + +1. Sysbuild +2. Manual build + +.. note:: + + User can select the MCUboot bootloader by adding the following line + to the board default configuration file. + ``` + CONFIG_BOOTLOADER_MCUBOOT=y + ``` + +Sysbuild +======== + +The sysbuild makes possible to build and flash all necessary images needed to +bootstrap the board with the ESP32 SoC. + +To build the sample application using sysbuild use the command: + +.. zephyr-app-commands:: + :tool: west + :app: samples/hello_world + :board: esp_wrover_kit + :goals: build + :west-args: --sysbuild + :compact: + +By default, the ESP32 sysbuild creates bootloader (MCUboot) and application +images. But it can be configured to create other kind of images. + +Build directory structure created by sysbuild is different from traditional +Zephyr build. Output is structured by the domain subdirectories: + +.. code-block:: + + build/ + ├── hello_world + │ └── zephyr + │ ├── zephyr.elf + │ └── zephyr.bin + ├── mcuboot + │ └── zephyr + │ ├── zephyr.elf + │ └── zephyr.bin + └── domains.yaml + +.. note:: + + With ``--sysbuild`` option the bootloader will be re-build and re-flash + every time the pristine build is used. + +For more information about the system build please read the :ref:`sysbuild` documentation. + +Manual build +============ + +During the development cycle, it is intended to build & flash as quickly possible. +For that reason, images can be build one at a time using traditional build. + +The instructions following are relevant for both manual build and sysbuild. +The only difference is the structure of the build directory. + +.. note:: + + Remember that bootloader (MCUboot) needs to be flash at least once. Build and flash applications as usual (see :ref:`build_an_application` and :ref:`application_run` for more details). @@ -149,7 +233,7 @@ message in the monitor: Hello World! esp32_devkitc_wroom Debugging ---------- +********* ESP32-DEVKITC-WROOM support on OpenOCD is available upstream as of version 0.12.0. Download and install OpenOCD from `OpenOCD`_. diff --git a/boards/espressif/esp32_devkitc_wrover/doc/index.rst b/boards/espressif/esp32_devkitc_wrover/doc/index.rst index 26f3a82e011..1f66f3da8a9 100644 --- a/boards/espressif/esp32_devkitc_wrover/doc/index.rst +++ b/boards/espressif/esp32_devkitc_wrover/doc/index.rst @@ -117,12 +117,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/espressif/esp32_ethernet_kit/doc/index.rst b/boards/espressif/esp32_ethernet_kit/doc/index.rst index fb0bd9aa425..2f8ff821aad 100644 --- a/boards/espressif/esp32_ethernet_kit/doc/index.rst +++ b/boards/espressif/esp32_ethernet_kit/doc/index.rst @@ -438,12 +438,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/espressif/esp32c3_devkitm/doc/index.rst b/boards/espressif/esp32c3_devkitm/doc/index.rst index 379d2c31065..c2d6551170c 100644 --- a/boards/espressif/esp32c3_devkitm/doc/index.rst +++ b/boards/espressif/esp32c3_devkitm/doc/index.rst @@ -92,12 +92,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/espressif/esp32s2_saola/doc/index.rst b/boards/espressif/esp32s2_saola/doc/index.rst index b329b45f682..1e7c1627fd1 100644 --- a/boards/espressif/esp32s2_saola/doc/index.rst +++ b/boards/espressif/esp32s2_saola/doc/index.rst @@ -88,12 +88,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/espressif/esp32s3_devkitm/doc/index.rst b/boards/espressif/esp32s3_devkitm/doc/index.rst index 5405100f364..abef4294733 100644 --- a/boards/espressif/esp32s3_devkitm/doc/index.rst +++ b/boards/espressif/esp32s3_devkitm/doc/index.rst @@ -137,12 +137,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/espressif/esp_wrover_kit/doc/index.rst b/boards/espressif/esp_wrover_kit/doc/index.rst index 06203863505..521307376a0 100644 --- a/boards/espressif/esp_wrover_kit/doc/index.rst +++ b/boards/espressif/esp_wrover_kit/doc/index.rst @@ -503,12 +503,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/franzininho/esp32s2_franzininho/doc/index.rst b/boards/franzininho/esp32s2_franzininho/doc/index.rst index de0b2c8b1b7..54de95ecb40 100644 --- a/boards/franzininho/esp32s2_franzininho/doc/index.rst +++ b/boards/franzininho/esp32s2_franzininho/doc/index.rst @@ -54,12 +54,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst b/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst index 07355a6d70b..b97a9980512 100644 --- a/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst +++ b/boards/heltec/heltec_wifi_lora32_v2/doc/index.rst @@ -42,12 +42,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst b/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst index 987eeb9f0f1..85470571981 100644 --- a/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst +++ b/boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst @@ -156,12 +156,15 @@ below to retrieve those files. Programming and Debugging ************************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/luatos/esp32c3_luatos_core/doc/index.rst b/boards/luatos/esp32c3_luatos_core/doc/index.rst index beaf0d1e85b..7b6bbacf982 100644 --- a/boards/luatos/esp32c3_luatos_core/doc/index.rst +++ b/boards/luatos/esp32c3_luatos_core/doc/index.rst @@ -110,12 +110,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/luatos/esp32s3_luatos_core/doc/index.rst b/boards/luatos/esp32s3_luatos_core/doc/index.rst index 4921e11e915..94bc0f685d3 100644 --- a/boards/luatos/esp32s3_luatos_core/doc/index.rst +++ b/boards/luatos/esp32s3_luatos_core/doc/index.rst @@ -136,12 +136,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/olimex/olimex_esp32_evb/doc/index.rst b/boards/olimex/olimex_esp32_evb/doc/index.rst index b667547f859..bcfc8a3c346 100644 --- a/boards/olimex/olimex_esp32_evb/doc/index.rst +++ b/boards/olimex/olimex_esp32_evb/doc/index.rst @@ -111,12 +111,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/others/icev_wireless/doc/index.rst b/boards/others/icev_wireless/doc/index.rst index a931bb33da7..5484924e8d6 100644 --- a/boards/others/icev_wireless/doc/index.rst +++ b/boards/others/icev_wireless/doc/index.rst @@ -98,12 +98,15 @@ incredibly easy 🎉 following the steps below. Building and Flashing ********************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/seeed/xiao_esp32c3/doc/index.rst b/boards/seeed/xiao_esp32c3/doc/index.rst index 11d5109b3cf..dc86a6c20ca 100644 --- a/boards/seeed/xiao_esp32c3/doc/index.rst +++ b/boards/seeed/xiao_esp32c3/doc/index.rst @@ -80,12 +80,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/seeed/xiao_esp32s3/doc/index.rst b/boards/seeed/xiao_esp32s3/doc/index.rst index 1880e6ff9a4..bbb1bf528ae 100644 --- a/boards/seeed/xiao_esp32s3/doc/index.rst +++ b/boards/seeed/xiao_esp32s3/doc/index.rst @@ -96,12 +96,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ================== diff --git a/boards/vcc-gnd/yd_esp32/doc/index.rst b/boards/vcc-gnd/yd_esp32/doc/index.rst index 890c3de6855..433c1ac0c30 100644 --- a/boards/vcc-gnd/yd_esp32/doc/index.rst +++ b/boards/vcc-gnd/yd_esp32/doc/index.rst @@ -117,12 +117,15 @@ below to retrieve those files. Building & Flashing ******************* -ESP-IDF bootloader -================== +Simple boot +=========== -The board is using the ESP-IDF bootloader as the default 2nd stage bootloader. -It is build as a subproject at each application build. No further attention -is expected from the user. +The board could be loaded using the single binary image, without 2nd stage bootloader. +It is the default option when building the application without additional configuration. + +.. note:: + + Simple boot does not provide any security features nor OTA updates. MCUboot bootloader ==================