Skip to content

Update espressif bootloader; update instrutions #1659

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 15, 2025
Merged

Update espressif bootloader; update instrutions #1659

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9926b45
bump Espressif TinyUF2 version to 0.35.0
dhalbert Jul 15, 2025
a8e05c8
Rework Espressif bootloader section
dhalbert Jul 15, 2025
5b21fa7
repititious "general..."
dhalbert Jul 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions _data/bootloaders.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
"version": "v3.16.0"
},
"esp32s2": {
"version": "0.21.0"
"version": "0.35.0"
},
"esp32s3": {
"version": "0.21.0"
"version": "0.35.0"
},
"analog": {},
"broadcom": {},
Expand Down
114 changes: 60 additions & 54 deletions _includes/download/board.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ <h3>CircuitPython {{ version.version }}</h3>
{% endif %}
{% if page.family == 'nrf52840' %}
<p>
<b>On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later.
Older bootloaders cannot load the firmware. See <i>Update UF2 Bootloader</i> below.</b>
<strong>On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later.
Older bootloaders cannot load the firmware. See <i>Update UF2 Bootloader</i> below.</strong>
</p>
{% endif %}
<p>
Expand Down Expand Up @@ -227,80 +227,86 @@ <h3>Previous Versions of CircuitPython</h3>
{% endcomment %}

{% if bootloader_version and bootloader_id %}
{% if page.family == 'esp32s2' or page.family == 'esp32c3' or page.family == 'esp32s3' %}
{% if page.family == 'esp32s2' or page.family == 'esp32s3' %}
<div class="section unrecommended">
<h3>Install, Repair, or Update UF2 Bootloader</h3>
<p>
Latest version: {{ bootloader_version }}
</p>
<p>
<strong>The UF2 bootloader allows you to load CircuitPython, MakeCode, and Arduino programs.
The bootloader is not CircuitPython.</strong>
If a UF2 bootloader is installed, you can check its version by looking in
the <b>INFO_UF2.TXT</b> file when the <b>BOOT</b> drive is visible
(<b>FTHRS2BOOT</b>, <b>MAGTAGBOOT</b>, <b>HOUSEBOOT</b>, etc.)
</strong>
The bootloader itself is not CircuitPython.
On Espressif boards, the UF2 bootloader is called <em>TinyUF2</em>.
If the TinyUF2 bootloader is installed, you can check its version by looking in
the <strong>INFO_UF2.TXT</strong> file when the <strong>BOOT</strong> drive is visible
(<strong>FTHRS2BOOT</strong>, <strong>MAGTAGBOOT</strong>, <strong>HOUSEBOOT</strong>, etc.)
</p>
<p>
It is not necessary to reinstall a UF2 bootloader you unless a <b>BOOT</b> drive is not visible
when in UF2 bootloader mode, or you know of a problem with your current UF2 bootloader.
In general, it is not necessary to update TinyUF2 at every version change.
You can read the <a href="https://github.com/adafruit/tinyuf2/releases">release notes on GitHub</a> to see what has been changed.
Update if you've been told about a necessary change or a bug fix.
</p>
<p>
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
<a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">ESP Web Flasher</a>
or <b>esptool.py</b>.
<p><strong><em>Note:</em></strong>
<em>CircuitPython 10 and later, on Espressif boards with 4MB flash, requires TinyUF2 0.33.0 or later.
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>
</p>

<p>
<em>Note: <b>update.uf2</b> files are not currently working on ESP32-S2 or ESP32-S3 boards.</em>
If TinyUF2 has never been installed on the board,
or it was removed by erasing or overwriting the flash,
it must be installed in order to flash <strong>.uf2</strong> files onto the board.
But you don't need the TinyUF2 bootloader to upload <strong>.bin</strong> files. They can be uploaded using the
built-in ROM bootloader, with the
<a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">Adafruit WebSerial ESPTool</a>
or <strong>esptool.py</strong>.
</p>

<p><strong><em>Important</em></strong>:
<em>this will erase previously flashed firmware and sketches from the board,
but needs to be perfomed only once.</em>
<p><strong><em>Warning:</em></strong>
<em>Installing the TinyUF2 bootloader will erase everything that was previously on the board.
Save any files in <strong>CIRCUITPY</strong> for which you don't have backups.</em>
</p>
<p>There are several ways to install the TinyUF2 bootloader on your board.
Check to see if your board's manufacturer provides specific instructions.
For Adafruit boards, consult the <em>Factory Reset</em> page
in the Learn Guide for your particular board (<a href="https://learn.adafruit.com/adafruit-esp32-s3-feather/factory-reset">example</a>).
</p>
<p><em>The instructions here are general.
We recommend you consult the manufacturer's board documentation for detailed
instructions, which may be different.</em>
<p>The easiest way to install TinyUF2 is to use the <strong>OPEN INSTALLER</strong> button
(see above, in the CiruitPython sections).
You can also use the <a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">Adafruit WebSerial ESPTool</a>, or <strong>esptool.py</strong>,
as described in the Factory Reset page.
</p>
<ul>
<li>Unzip to find the file <b>combined.bin</b>.</li>
<li>Place board in bootloader mode:
<li>If you are not using the <strong>OPEN INSTALLER</strong> button,
download the <strong>combined.bin</strong> file using the <strong>DOWNLOAD BOOTLOADER combined.bin</strong> button below.
(If you use <strong>OPEN INSTALLER</strong>, it will do the download itself.)</li>
<li>First, place board in ROM bootloader mode:
<ul>
<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>
<li>Press and <strong>hold down</strong> the <b>BOOT</b> or <b>0</b> button.</li>
<li>Press and <strong>release</strong> the <b>RESET</b> or <b>RST</b> button.</li>
<li>Release the <b>BOOT</b> button.</li>
<li>Press and <em>hold</em> the BOOT button (sometimes marked "B0").</li>
<li>Press and <em>release</em> the RESET button (sometimes marked "RST").</li>
<li>Release the BOOT button. This starts the ROM bootloader.</li>
</ul>
</li>
<li>Upload <b>combined.bin</b> (Google Chrome 89 or newer):
<ul>
<li>Open <a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">ESP Web Flasher</a> in a new window/tab.</li>
<li>Select <b>460800 Baud</b> from the pull-down menu (top-right).</li>
<li>Click <b>Connect</b> (top-right).</li>
<li>Select the COM or Serial port from the pop-up window.</li>
<li>After successful connection, click <b>Erase</b>.</li>
<li>After successful erase, click any <b>Choose a file...</b>, then locate and select the <b>combined.bin</b> file unzipped earlier.</li>
<li>After successfully choosing <b>combined.bin</b>, click <b>Program</b>.</li>
<li>After the TinyUF2 firmware update is complete, press the <b>RESET</b> button on the board.
A new drive <b>BOOT</b> should be visible in your file browser.</li>
<li>Then proceed with <strong>OPEN INSTALLER</strong> or one of the other tools.</li>
<li>After the TinyUF2 firmware installation is complete, press the RESET button on the board.
A new drive <strong>BOOT</strong> drive should be visible in your file browser.</li>
</ul>
</li>
</ul>
{% if bootloader_instructions == nil %}
<p>
After installing the UF2 bootloader, enter the bootloader by double-clicking the reset button.
On boards with an RGB status LED, tap reset once, wait for the LED to turn purple, and tap
After installing TinyUF2, enter the UF2 bootloader by double-clicking the RESET button.
On boards with an RGB status LED, you usually tap reset once, wait for the LED to turn purple, and tap
again before the purple goes away. On other boards, consult the board documentation.
</p>
{% else %}
<p>{{ bootloader_instructions }}</p>
{% endif %}
<p>
After you update, check <b>INFO_UF2.TXT</b> to verify that the bootloader version has been updated.
Then you will need to load or reload CircuitPython using the <b>.uf2</b> file.
If you are updating TinyUF2, look at <strong>INFO_UF2.TXT</strong> to verify the new version of TinyUF2,
by checking the version number.
Then you will need to copy the CircuitPython<strong>.uf2</strong> file to the <strong>BOOT</strong> drive.
</p>
<div>
<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>
<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>
</div>
</div>
{% else %}
Expand All @@ -313,7 +319,7 @@ <h3>Update UF2 Bootloader</h3>
<strong>The bootloader allows you to load CircuitPython, MakeCode, and Arduino programs.
The bootloader is not CircuitPython.</strong>
You can check the current version of your bootloader by looking in
the <b>INFO_UF2.TXT</b> file when the <b>BOOT</b> drive is visible (<b>FEATHERBOOT</b>, <b>CPLAYBOOT</b>, etc.).
the <strong>INFO_UF2.TXT</strong> file when the <strong>BOOT</strong> drive is visible (<strong>FEATHERBOOT</strong>, <strong>CPLAYBOOT</strong>, etc.).
</p>
<p>
It is not necessary to update your bootloader if it is working fine.
Expand All @@ -324,17 +330,17 @@ <h3>Update UF2 Bootloader</h3>

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

{% if page.family == 'atmel-samd' %}
<p>
To update, first save the contents of <b>CIRCUITPY</b>, just in case.
Then double-click the reset button to show the <b>BOOT</b> drive.
Drag the <b>update-bootloader</b> <b>.uf2</b> file to the <b>BOOT</b> drive.
Wait a few tens of seconds for the bootloader to update; the <b>BOOT</b> drive will reappear.
After you update, check <b>INFO_UF2.TXT</b> to verify that the bootloader version has been updated.
To update, first save the contents of <strong>CIRCUITPY</strong>, just in case.
Then double-click the reset button to show the <strong>BOOT</strong> drive.
Drag the <strong>update-bootloader</strong> <strong>.uf2</strong> file to the <strong>BOOT</strong> drive.
Wait a few tens of seconds for the bootloader to update; the <strong>BOOT</strong> drive will reappear.
After you update, check <strong>INFO_UF2.TXT</strong> to verify that the bootloader version has been updated.
Then you will need to reload CircuitPython.
</p>
<p>
Expand Down