Skip to content

Commit 039d7d8

Browse files
dhalbertdhalbert
authored
Merge pull request #1659 from dhalbert/update-esp-bootloader
Update espressif bootloader; update instrutions
2 parents 8082eac + 5b21fa7 commit 039d7d8

File tree

2 files changed

+62
-56
lines changed

2 files changed

+62
-56
lines changed

‎_data/bootloaders.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@
77
"version": "v3.16.0"
88
},
99
"esp32s2": {
10-
"version": "0.21.0"
10+
"version": "0.35.0"
1111
},
1212
"esp32s3": {
13-
"version": "0.21.0"
13+
"version": "0.35.0"
1414
},
1515
"analog": {},
1616
"broadcom": {},

‎_includes/download/board.html

Lines changed: 60 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ <h3>CircuitPython {{ version.version }}</h3>
3939
{% endif %}
4040
{% if page.family == 'nrf52840' %}
4141
<p>
42-
<b>On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later.
43-
Older bootloaders cannot load the firmware. See <i>Update UF2 Bootloader</i> below.</b>
42+
<strong>On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later.
43+
Older bootloaders cannot load the firmware. See <i>Update UF2 Bootloader</i> below.</strong>
4444
</p>
4545
{% endif %}
4646
<p>
@@ -227,80 +227,86 @@ <h3>Previous Versions of CircuitPython</h3>
227227
{% endcomment %}
228228

229229
{% if bootloader_version and bootloader_id %}
230-
{% if page.family == 'esp32s2' or page.family == 'esp32c3' or page.family == 'esp32s3' %}
230+
{% if page.family == 'esp32s2' or page.family == 'esp32s3' %}
231231
<div class="section unrecommended">
232232
<h3>Install, Repair, or Update UF2 Bootloader</h3>
233233
<p>
234234
Latest version: {{ bootloader_version }}
235235
</p>
236236
<p>
237237
<strong>The UF2 bootloader allows you to load CircuitPython, MakeCode, and Arduino programs.
238-
The bootloader is not CircuitPython.</strong>
239-
If a UF2 bootloader is installed, you can check its version by looking in
240-
the <b>INFO_UF2.TXT</b> file when the <b>BOOT</b> drive is visible
241-
(<b>FTHRS2BOOT</b>, <b>MAGTAGBOOT</b>, <b>HOUSEBOOT</b>, etc.)
238+
</strong>
239+
The bootloader itself is not CircuitPython.
240+
On Espressif boards, the UF2 bootloader is called <em>TinyUF2</em>.
241+
If the TinyUF2 bootloader is installed, you can check its version by looking in
242+
the <strong>INFO_UF2.TXT</strong> file when the <strong>BOOT</strong> drive is visible
243+
(<strong>FTHRS2BOOT</strong>, <strong>MAGTAGBOOT</strong>, <strong>HOUSEBOOT</strong>, etc.)
242244
</p>
243245
<p>
244-
It is not necessary to reinstall a UF2 bootloader you unless a <b>BOOT</b> drive is not visible
245-
when in UF2 bootloader mode, or you know of a problem with your current UF2 bootloader.
246+
In general, it is not necessary to update TinyUF2 at every version change.
247+
You can read the <a href="https://github.com/adafruit/tinyuf2/releases">release notes on GitHub</a> to see what has been changed.
248+
Update if you've been told about a necessary change or a bug fix.
246249
</p>
247-
<p>
248-
If a UF2 bootloader has never been installed on the board, or the UF2 bootloader was removed by erasing or overwriting the flash, the UF2 bootloader must be installed in order to flash <b>.uf2</b> files onto the board. <b>.bin</b> files can be uploaded without a UF2 bootloader, using the
249-
<a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">ESP Web Flasher</a>
250-
or <b>esptool.py</b>.
250+
<p><strong><em>Note:</em></strong>
251+
<em>CircuitPython 10 and later, on Espressif boards with 4MB flash, requires TinyUF2 0.33.0 or later.
252+
The flash partition layout has changed (<a href="https://learn.adafruit.com/adafruit-esp32-s3-feather/update-tinyuf2-bootloader-for-circuitpython-10-4mb-boards-only">details</a>).</em>
251253
</p>
252-
253254
<p>
254-
<em>Note: <b>update.uf2</b> files are not currently working on ESP32-S2 or ESP32-S3 boards.</em>
255+
If TinyUF2 has never been installed on the board,
256+
or it was removed by erasing or overwriting the flash,
257+
it must be installed in order to flash <strong>.uf2</strong> files onto the board.
258+
But you don't need the TinyUF2 bootloader to upload <strong>.bin</strong> files. They can be uploaded using the
259+
built-in ROM bootloader, with the
260+
<a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">Adafruit WebSerial ESPTool</a>
261+
or <strong>esptool.py</strong>.
255262
</p>
256-
257-
<p><strong><em>Important</em></strong>:
258-
<em>this will erase previously flashed firmware and sketches from the board,
259-
but needs to be perfomed only once.</em>
263+
<p><strong><em>Warning:</em></strong>
264+
<em>Installing the TinyUF2 bootloader will erase everything that was previously on the board.
265+
Save any files in <strong>CIRCUITPY</strong> for which you don't have backups.</em>
266+
</p>
267+
<p>There are several ways to install the TinyUF2 bootloader on your board.
268+
Check to see if your board's manufacturer provides specific instructions.
269+
For Adafruit boards, consult the <em>Factory Reset</em> page
270+
in the Learn Guide for your particular board (<a href="https://learn.adafruit.com/adafruit-esp32-s3-feather/factory-reset">example</a>).
260271
</p>
261-
<p><em>The instructions here are general.
262-
We recommend you consult the manufacturer's board documentation for detailed
263-
instructions, which may be different.</em>
272+
<p>The easiest way to install TinyUF2 is to use the <strong>OPEN INSTALLER</strong> button
273+
(see above, in the CiruitPython sections).
274+
You can also use the <a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">Adafruit WebSerial ESPTool</a>, or <strong>esptool.py</strong>,
275+
as described in the Factory Reset page.
264276
</p>
265-
<ul>
266-
<li>Unzip to find the file <b>combined.bin</b>.</li>
267-
<li>Place board in bootloader mode:
277+
<li>If you are not using the <strong>OPEN INSTALLER</strong> button,
278+
download the <strong>combined.bin</strong> file using the <strong>DOWNLOAD BOOTLOADER combined.bin</strong> button below.
279+
(If you use <strong>OPEN INSTALLER</strong>, it will do the download itself.)</li>
280+
<li>First, place board in ROM bootloader mode:
268281
<ul>
269282
<li>Plug board into a USB port on your computer using a data/sync cable. Make sure it is the only board plugged in, and that a charge-only cable is not being used.</li>
270-
<li>Press and <strong>hold down</strong> the <b>BOOT</b> or <b>0</b> button.</li>
271-
<li>Press and <strong>release</strong> the <b>RESET</b> or <b>RST</b> button.</li>
272-
<li>Release the <b>BOOT</b> button.</li>
283+
<li>Press and <em>hold</em> the BOOT button (sometimes marked "B0").</li>
284+
<li>Press and <em>release</em> the RESET button (sometimes marked "RST").</li>
285+
<li>Release the BOOT button. This starts the ROM bootloader.</li>
273286
</ul>
274287
</li>
275-
<li>Upload <b>combined.bin</b> (Google Chrome 89 or newer):
276-
<ul>
277-
<li>Open <a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">ESP Web Flasher</a> in a new window/tab.</li>
278-
<li>Select <b>460800 Baud</b> from the pull-down menu (top-right).</li>
279-
<li>Click <b>Connect</b> (top-right).</li>
280-
<li>Select the COM or Serial port from the pop-up window.</li>
281-
<li>After successful connection, click <b>Erase</b>.</li>
282-
<li>After successful erase, click any <b>Choose a file...</b>, then locate and select the <b>combined.bin</b> file unzipped earlier.</li>
283-
<li>After successfully choosing <b>combined.bin</b>, click <b>Program</b>.</li>
284-
<li>After the TinyUF2 firmware update is complete, press the <b>RESET</b> button on the board.
285-
A new drive <b>BOOT</b> should be visible in your file browser.</li>
288+
<li>Then proceed with <strong>OPEN INSTALLER</strong> or one of the other tools.</li>
289+
<li>After the TinyUF2 firmware installation is complete, press the RESET button on the board.
290+
A new drive <strong>BOOT</strong> drive should be visible in your file browser.</li>
286291
</ul>
287292
</li>
288293
</ul>
289294
{% if bootloader_instructions == nil %}
290295
<p>
291-
After installing the UF2 bootloader, enter the bootloader by double-clicking the reset button.
292-
On boards with an RGB status LED, tap reset once, wait for the LED to turn purple, and tap
296+
After installing TinyUF2, enter the UF2 bootloader by double-clicking the RESET button.
297+
On boards with an RGB status LED, you usually tap reset once, wait for the LED to turn purple, and tap
293298
again before the purple goes away. On other boards, consult the board documentation.
294299
</p>
295300
{% else %}
296301
<p>{{ bootloader_instructions }}</p>
297302
{% endif %}
298303
<p>
299-
After you update, check <b>INFO_UF2.TXT</b> to verify that the bootloader version has been updated.
300-
Then you will need to load or reload CircuitPython using the <b>.uf2</b> file.
304+
If you are updating TinyUF2, look at <strong>INFO_UF2.TXT</strong> to verify the new version of TinyUF2,
305+
by checking the version number.
306+
Then you will need to copy the CircuitPython<strong>.uf2</strong> file to the <strong>BOOT</strong> drive.
301307
</p>
302308
<div>
303-
<a class="download-button" href="https://github.com/adafruit/tinyuf2/releases/download/{{ bootloader_version }}/tinyuf2-{{ bootloader_id }}-{{ bootloader_version }}.zip">DOWNLOAD BOOTLOADER ZIP<i class="fas fa-download" aria-hidden="true"></i></a>
309+
<a class="download-button" href="https://adafruit-circuit-python.s3.amazonaws.com/bootloaders/esp32/{{ bootloader_id }}/tinyuf2-{{ bootloader_id }}-{{ bootloader_version }}-combined.bin">DOWNLOAD BOOTLOADER combined.bin<i class="fas fa-download" aria-hidden="true"></i></a>
304310
</div>
305311
</div>
306312
{% else %}
@@ -313,7 +319,7 @@ <h3>Update UF2 Bootloader</h3>
313319
<strong>The bootloader allows you to load CircuitPython, MakeCode, and Arduino programs.
314320
The bootloader is not CircuitPython.</strong>
315321
You can check the current version of your bootloader by looking in
316-
the <b>INFO_UF2.TXT</b> file when the <b>BOOT</b> drive is visible (<b>FEATHERBOOT</b>, <b>CPLAYBOOT</b>, etc.).
322+
the <strong>INFO_UF2.TXT</strong> file when the <strong>BOOT</strong> drive is visible (<strong>FEATHERBOOT</strong>, <strong>CPLAYBOOT</strong>, etc.).
317323
</p>
318324
<p>
319325
It is not necessary to update your bootloader if it is working fine.
@@ -324,17 +330,17 @@ <h3>Update UF2 Bootloader</h3>
324330

325331
{% if page.family == 'nrf52840' %}
326332
<p>
327-
<b>On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later.
333+
<strong>On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later.
328334
Older bootloaders cannot load the firmware.
329335
To check the version of your board's bootloader,
330-
look at <i>INFO_UF2.TXT</i> when the <i>BOOT</i> drive is present.
331-
</b>
336+
look at <strong>INFO_UF2.TXT</strong> when the <strong>BOOT</strong> drive is present.
337+
</strong>
332338
To update the bootloader, refer to the "Update Bootloader" page in the guide for
333339
your board, or start with
334340
<a href="https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/update-bootloader">this page</a>.
335341
</p>
336342
<p>
337-
After you update, check <b>INFO_UF2.TXT</b> to verify that the bootloader version has been updated.
343+
After you update, check <strong>INFO_UF2.TXT</strong> to verify that the bootloader version has been updated.
338344
Then you will need to reload CircuitPython.
339345
</p>
340346
<div>
@@ -344,11 +350,11 @@ <h3>Update UF2 Bootloader</h3>
344350

345351
{% if page.family == 'atmel-samd' %}
346352
<p>
347-
To update, first save the contents of <b>CIRCUITPY</b>, just in case.
348-
Then double-click the reset button to show the <b>BOOT</b> drive.
349-
Drag the <b>update-bootloader</b> <b>.uf2</b> file to the <b>BOOT</b> drive.
350-
Wait a few tens of seconds for the bootloader to update; the <b>BOOT</b> drive will reappear.
351-
After you update, check <b>INFO_UF2.TXT</b> to verify that the bootloader version has been updated.
353+
To update, first save the contents of <strong>CIRCUITPY</strong>, just in case.
354+
Then double-click the reset button to show the <strong>BOOT</strong> drive.
355+
Drag the <strong>update-bootloader</strong> <strong>.uf2</strong> file to the <strong>BOOT</strong> drive.
356+
Wait a few tens of seconds for the bootloader to update; the <strong>BOOT</strong> drive will reappear.
357+
After you update, check <strong>INFO_UF2.TXT</strong> to verify that the bootloader version has been updated.
352358
Then you will need to reload CircuitPython.
353359
</p>
354360
<p>

0 commit comments

Comments
 (0)