Skip to content

Commit c086603

Browse files
Marek Matejnashif
Marek Matej
authored and
nashif
committed
boards: Update ESP32 related documentation
Update the note on the booting method for all ESP32 related boards. Signed-off-by: Marek Matej <[email protected]>
1 parent 2395f08 commit c086603

File tree

17 files changed

+214
-82
lines changed

17 files changed

+214
-82
lines changed

‎boards/espressif/esp32_devkitc_wroom/doc/index.rst

Lines changed: 86 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,91 @@ below to retrieve those files.
115115
It is recommended running the command above after :file:`west update`.
116116

117117
Building & Flashing
118-
-------------------
118+
*******************
119+
120+
Simple boot
121+
===========
122+
123+
The board could be loaded using the single binary image, without 2nd stage bootloader.
124+
It is the default option when building the application without additional configuration.
125+
126+
.. note::
127+
128+
Simple boot does not provide any security features nor OTA updates.
129+
130+
MCUboot bootloader
131+
==================
132+
133+
User may choose to use MCUboot bootloader instead. In that case the bootloader
134+
must be build (and flash) at least once.
135+
136+
There are two options to be used when building an application:
137+
138+
1. Sysbuild
139+
2. Manual build
140+
141+
.. note::
142+
143+
User can select the MCUboot bootloader by adding the following line
144+
to the board default configuration file.
145+
```
146+
CONFIG_BOOTLOADER_MCUBOOT=y
147+
```
148+
149+
Sysbuild
150+
========
151+
152+
The sysbuild makes possible to build and flash all necessary images needed to
153+
bootstrap the board with the ESP32 SoC.
154+
155+
To build the sample application using sysbuild use the command:
156+
157+
.. zephyr-app-commands::
158+
:tool: west
159+
:app: samples/hello_world
160+
:board: esp_wrover_kit
161+
:goals: build
162+
:west-args: --sysbuild
163+
:compact:
164+
165+
By default, the ESP32 sysbuild creates bootloader (MCUboot) and application
166+
images. But it can be configured to create other kind of images.
167+
168+
Build directory structure created by sysbuild is different from traditional
169+
Zephyr build. Output is structured by the domain subdirectories:
170+
171+
.. code-block::
172+
173+
build/
174+
├── hello_world
175+
│ └── zephyr
176+
│ ├── zephyr.elf
177+
│ └── zephyr.bin
178+
├── mcuboot
179+
│ └── zephyr
180+
│ ├── zephyr.elf
181+
│ └── zephyr.bin
182+
└── domains.yaml
183+
184+
.. note::
185+
186+
With ``--sysbuild`` option the bootloader will be re-build and re-flash
187+
every time the pristine build is used.
188+
189+
For more information about the system build please read the :ref:`sysbuild` documentation.
190+
191+
Manual build
192+
============
193+
194+
During the development cycle, it is intended to build & flash as quickly possible.
195+
For that reason, images can be build one at a time using traditional build.
196+
197+
The instructions following are relevant for both manual build and sysbuild.
198+
The only difference is the structure of the build directory.
199+
200+
.. note::
201+
202+
Remember that bootloader (MCUboot) needs to be flash at least once.
119203

120204
Build and flash applications as usual (see :ref:`build_an_application` and
121205
:ref:`application_run` for more details).
@@ -149,7 +233,7 @@ message in the monitor:
149233
Hello World! esp32_devkitc_wroom
150234
151235
Debugging
152-
---------
236+
*********
153237

154238
ESP32-DEVKITC-WROOM support on OpenOCD is available upstream as of version 0.12.0.
155239
Download and install OpenOCD from `OpenOCD`_.

‎boards/espressif/esp32_devkitc_wrover/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -117,12 +117,15 @@ below to retrieve those files.
117117
Building & Flashing
118118
*******************
119119

120-
ESP-IDF bootloader
121-
==================
120+
Simple boot
121+
===========
122+
123+
The board could be loaded using the single binary image, without 2nd stage bootloader.
124+
It is the default option when building the application without additional configuration.
125+
126+
.. note::
122127

123-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
124-
It is build as a subproject at each application build. No further attention
125-
is expected from the user.
128+
Simple boot does not provide any security features nor OTA updates.
126129

127130
MCUboot bootloader
128131
==================

‎boards/espressif/esp32_ethernet_kit/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -438,12 +438,15 @@ below to retrieve those files.
438438
Building & Flashing
439439
*******************
440440

441-
ESP-IDF bootloader
442-
==================
441+
Simple boot
442+
===========
443+
444+
The board could be loaded using the single binary image, without 2nd stage bootloader.
445+
It is the default option when building the application without additional configuration.
446+
447+
.. note::
443448

444-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
445-
It is build as a subproject at each application build. No further attention
446-
is expected from the user.
449+
Simple boot does not provide any security features nor OTA updates.
447450

448451
MCUboot bootloader
449452
==================

‎boards/espressif/esp32c3_devkitm/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -92,12 +92,15 @@ below to retrieve those files.
9292
Building & Flashing
9393
*******************
9494

95-
ESP-IDF bootloader
96-
==================
95+
Simple boot
96+
===========
97+
98+
The board could be loaded using the single binary image, without 2nd stage bootloader.
99+
It is the default option when building the application without additional configuration.
100+
101+
.. note::
97102

98-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
99-
It is build as a subproject at each application build. No further attention
100-
is expected from the user.
103+
Simple boot does not provide any security features nor OTA updates.
101104

102105
MCUboot bootloader
103106
==================

‎boards/espressif/esp32s2_saola/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,12 +88,15 @@ below to retrieve those files.
8888
Building & Flashing
8989
*******************
9090

91-
ESP-IDF bootloader
92-
==================
91+
Simple boot
92+
===========
93+
94+
The board could be loaded using the single binary image, without 2nd stage bootloader.
95+
It is the default option when building the application without additional configuration.
96+
97+
.. note::
9398

94-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
95-
It is build as a subproject at each application build. No further attention
96-
is expected from the user.
99+
Simple boot does not provide any security features nor OTA updates.
97100

98101
MCUboot bootloader
99102
==================

‎boards/espressif/esp32s3_devkitm/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -137,12 +137,15 @@ below to retrieve those files.
137137
Building & Flashing
138138
*******************
139139

140-
ESP-IDF bootloader
141-
==================
140+
Simple boot
141+
===========
142+
143+
The board could be loaded using the single binary image, without 2nd stage bootloader.
144+
It is the default option when building the application without additional configuration.
145+
146+
.. note::
142147

143-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
144-
It is build as a subproject at each application build. No further attention
145-
is expected from the user.
148+
Simple boot does not provide any security features nor OTA updates.
146149

147150
MCUboot bootloader
148151
==================

‎boards/espressif/esp_wrover_kit/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -503,12 +503,15 @@ below to retrieve those files.
503503
Building & Flashing
504504
*******************
505505

506-
ESP-IDF bootloader
507-
==================
506+
Simple boot
507+
===========
508+
509+
The board could be loaded using the single binary image, without 2nd stage bootloader.
510+
It is the default option when building the application without additional configuration.
511+
512+
.. note::
508513

509-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
510-
It is build as a subproject at each application build. No further attention
511-
is expected from the user.
514+
Simple boot does not provide any security features nor OTA updates.
512515

513516
MCUboot bootloader
514517
==================

‎boards/franzininho/esp32s2_franzininho/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -54,12 +54,15 @@ below to retrieve those files.
5454
Building & Flashing
5555
*******************
5656

57-
ESP-IDF bootloader
58-
==================
57+
Simple boot
58+
===========
59+
60+
The board could be loaded using the single binary image, without 2nd stage bootloader.
61+
It is the default option when building the application without additional configuration.
62+
63+
.. note::
5964

60-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
61-
It is build as a subproject at each application build. No further attention
62-
is expected from the user.
65+
Simple boot does not provide any security features nor OTA updates.
6366

6467
MCUboot bootloader
6568
==================

‎boards/heltec/heltec_wifi_lora32_v2/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,12 +42,15 @@ below to retrieve those files.
4242
Building & Flashing
4343
*******************
4444

45-
ESP-IDF bootloader
46-
==================
45+
Simple boot
46+
===========
47+
48+
The board could be loaded using the single binary image, without 2nd stage bootloader.
49+
It is the default option when building the application without additional configuration.
50+
51+
.. note::
4752

48-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
49-
It is build as a subproject at each application build. No further attention
50-
is expected from the user.
53+
Simple boot does not provide any security features nor OTA updates.
5154

5255
MCUboot bootloader
5356
==================

‎boards/heltec/heltec_wireless_stick_lite_v3/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -156,12 +156,15 @@ below to retrieve those files.
156156
Programming and Debugging
157157
*************************
158158

159-
ESP-IDF bootloader
160-
==================
159+
Simple boot
160+
===========
161+
162+
The board could be loaded using the single binary image, without 2nd stage bootloader.
163+
It is the default option when building the application without additional configuration.
164+
165+
.. note::
161166

162-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
163-
It is build as a subproject at each application build. No further attention
164-
is expected from the user.
167+
Simple boot does not provide any security features nor OTA updates.
165168

166169
MCUboot bootloader
167170
==================

‎boards/luatos/esp32c3_luatos_core/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -110,12 +110,15 @@ below to retrieve those files.
110110
Building & Flashing
111111
*******************
112112

113-
ESP-IDF bootloader
114-
==================
113+
Simple boot
114+
===========
115+
116+
The board could be loaded using the single binary image, without 2nd stage bootloader.
117+
It is the default option when building the application without additional configuration.
118+
119+
.. note::
115120

116-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
117-
It is build as a subproject at each application build. No further attention
118-
is expected from the user.
121+
Simple boot does not provide any security features nor OTA updates.
119122

120123
MCUboot bootloader
121124
==================

‎boards/luatos/esp32s3_luatos_core/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -136,12 +136,15 @@ below to retrieve those files.
136136
Building & Flashing
137137
*******************
138138

139-
ESP-IDF bootloader
140-
==================
139+
Simple boot
140+
===========
141+
142+
The board could be loaded using the single binary image, without 2nd stage bootloader.
143+
It is the default option when building the application without additional configuration.
144+
145+
.. note::
141146

142-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
143-
It is build as a subproject at each application build. No further attention
144-
is expected from the user.
147+
Simple boot does not provide any security features nor OTA updates.
145148

146149
MCUboot bootloader
147150
==================

‎boards/olimex/olimex_esp32_evb/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -111,12 +111,15 @@ below to retrieve those files.
111111
Building & Flashing
112112
*******************
113113

114-
ESP-IDF bootloader
115-
==================
114+
Simple boot
115+
===========
116+
117+
The board could be loaded using the single binary image, without 2nd stage bootloader.
118+
It is the default option when building the application without additional configuration.
119+
120+
.. note::
116121

117-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
118-
It is build as a subproject at each application build. No further attention
119-
is expected from the user.
122+
Simple boot does not provide any security features nor OTA updates.
120123

121124
MCUboot bootloader
122125
==================

‎boards/others/icev_wireless/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -98,12 +98,15 @@ incredibly easy 🎉 following the steps below.
9898
Building and Flashing
9999
*********************
100100

101-
ESP-IDF bootloader
102-
==================
101+
Simple boot
102+
===========
103+
104+
The board could be loaded using the single binary image, without 2nd stage bootloader.
105+
It is the default option when building the application without additional configuration.
106+
107+
.. note::
103108

104-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
105-
It is build as a subproject at each application build. No further attention
106-
is expected from the user.
109+
Simple boot does not provide any security features nor OTA updates.
107110

108111
MCUboot bootloader
109112
==================

‎boards/seeed/xiao_esp32c3/doc/index.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -80,12 +80,15 @@ below to retrieve those files.
8080
Building & Flashing
8181
*******************
8282

83-
ESP-IDF bootloader
84-
==================
83+
Simple boot
84+
===========
85+
86+
The board could be loaded using the single binary image, without 2nd stage bootloader.
87+
It is the default option when building the application without additional configuration.
88+
89+
.. note::
8590

86-
The board is using the ESP-IDF bootloader as the default 2nd stage bootloader.
87-
It is build as a subproject at each application build. No further attention
88-
is expected from the user.
91+
Simple boot does not provide any security features nor OTA updates.
8992

9093
MCUboot bootloader
9194
==================

0 commit comments

Comments
 (0)