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 7b0d7d8964..ec1248da38 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 26f3a82e01..1f66f3da8a 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 fb0bd9aa42..2f8ff821aa 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 379d2c3106..c2d6551170 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 b329b45f68..1e7c1627fd 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 5405100f36..abef429473 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 0620386350..521307376a 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 de0b2c8b1b..54de95ecb4 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 07355a6d70..b97a998051 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 987eeb9f0f..8547057198 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 beaf0d1e85..7b6bbacf98 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 4921e11e91..94bc0f685d 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 b667547f85..bcfc8a3c34 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 a931bb33da..5484924e8d 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 11d5109b3c..dc86a6c20c 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 1880e6ff9a..bbb1bf528a 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 890c3de685..433c1ac0c3 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 ==================