adafruit-mirror/circuitpython-org
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #1659 from dhalbert/update-esp-bootloader

Browse source 
Update espressif bootloader; update instrutions
This commit is contained in:
Dan Halbert 2025-07-15 10:22:08 -04:00 committed by GitHub
commit 039d7d81c4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 62 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
_data/bootloaders.json
View file

@ -7,10 +7,10 @@
"version": "v3.16.0" "version": "v3.16.0"
}, },
"esp32s2": { "esp32s2": {
"version": "0.21.0" "version": "0.35.0"
}, },
"esp32s3": { "esp32s3": {
"version": "0.21.0" "version": "0.35.0"
}, },
"analog": {}, "analog": {},
"broadcom": {}, "broadcom": {},

114
_includes/download/board.html
View file

@ -39,8 +39,8 @@
{% endif %} {% endif %}
{% if page.family == 'nrf52840' %} {% if page.family == 'nrf52840' %}
<p> <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. See <i>Update UF2 Bootloader</i> below.</b> Older bootloaders cannot load the firmware. See <i>Update UF2 Bootloader</i> below.</strong>
</p> </p>
{% endif %} {% endif %}
<p> <p>
@ -227,7 +227,7 @@ By the way, boolean operation precedence is right to left! (yeesh)
{% endcomment %} {% endcomment %}
{% if bootloader_version and bootloader_id %} {% 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"> <div class="section unrecommended">
<h3>Install, Repair, or Update UF2 Bootloader</h3> <h3>Install, Repair, or Update UF2 Bootloader</h3>
<p> <p>
@ -235,72 +235,78 @@ By the way, boolean operation precedence is right to left! (yeesh)
</p> </p>
<p> <p>
<strong>The UF2 bootloader allows you to load CircuitPython, MakeCode, and Arduino programs. <strong>The UF2 bootloader allows you to load CircuitPython, MakeCode, and Arduino programs.
The bootloader is not CircuitPython.</strong> </strong>
If a UF2 bootloader is installed, you can check its version by looking in The bootloader itself is not CircuitPython.
the <b>INFO_UF2.TXT</b> file when the <b>BOOT</b> drive is visible On Espressif boards, the UF2 bootloader is called <em>TinyUF2</em>.
(<b>FTHRS2BOOT</b>, <b>MAGTAGBOOT</b>, <b>HOUSEBOOT</b>, etc.) 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>
<p> <p>
It is not necessary to reinstall a UF2 bootloader you unless a <b>BOOT</b> drive is not visible In general, it is not necessary to update TinyUF2 at every version change.
when in UF2 bootloader mode, or you know of a problem with your current UF2 bootloader. 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><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>
<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 If TinyUF2 has never been installed on the board,
<a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">ESP Web Flasher</a> or it was removed by erasing or overwriting the flash,
or <b>esptool.py</b>. 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>
<p><strong><em>Warning:</em></strong>
<p> <em>Installing the TinyUF2 bootloader will erase everything that was previously on the board.
<em>Note: <b>update.uf2</b> files are not currently working on ESP32-S2 or ESP32-S3 boards.</em> Save any files in <strong>CIRCUITPY</strong> for which you don't have backups.</em>
</p> </p>
<p>There are several ways to install the TinyUF2 bootloader on your board.
<p><strong><em>Important</em></strong>: Check to see if your board's manufacturer provides specific instructions.
<em>this will erase previously flashed firmware and sketches from the board, For Adafruit boards, consult the <em>Factory Reset</em> page
but needs to be perfomed only once.</em> in the Learn Guide for your particular board (<a href="https://learn.adafruit.com/adafruit-esp32-s3-feather/factory-reset">example</a>).
</p> </p>
<p><em>The instructions here are general. <p>The easiest way to install TinyUF2 is to use the <strong>OPEN INSTALLER</strong> button
We recommend you consult the manufacturer's board documentation for detailed (see above, in the CiruitPython sections).
instructions, which may be different.</em> 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> </p>
<ul> <li>If you are not using the <strong>OPEN INSTALLER</strong> button,
<li>Unzip to find the file <b>combined.bin</b>.</li> download the <strong>combined.bin</strong> file using the <strong>DOWNLOAD BOOTLOADER combined.bin</strong> button below.
<li>Place board in bootloader mode: (If you use <strong>OPEN INSTALLER</strong>, it will do the download itself.)</li>
<li>First, place board in ROM bootloader mode:
<ul> <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>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 <em>hold</em> the BOOT button (sometimes marked "B0").</li>
<li>Press and <strong>release</strong> the <b>RESET</b> or <b>RST</b> button.</li> <li>Press and <em>release</em> the RESET button (sometimes marked "RST").</li>
<li>Release the <b>BOOT</b> button.</li> <li>Release the BOOT button. This starts the ROM bootloader.</li>
</ul> </ul>
</li> </li>
<li>Upload <b>combined.bin</b> (Google Chrome 89 or newer): <li>Then proceed with <strong>OPEN INSTALLER</strong> or one of the other tools.</li>
<ul> <li>After the TinyUF2 firmware installation is complete, press the RESET button on the board.
<li>Open <a href="https://adafruit.github.io/Adafruit_WebSerial_ESPTool/">ESP Web Flasher</a> in a new window/tab.</li> A new drive <strong>BOOT</strong> drive should be visible in your file browser.</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>
</ul> </ul>
</li> </li>
</ul> </ul>
{% if bootloader_instructions == nil %} {% if bootloader_instructions == nil %}
<p> <p>
After installing the UF2 bootloader, enter the bootloader by double-clicking the reset button. After installing TinyUF2, enter the UF2 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 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. again before the purple goes away. On other boards, consult the board documentation.
</p> </p>
{% else %} {% else %}
<p>{{ bootloader_instructions }}</p> <p>{{ bootloader_instructions }}</p>
{% endif %} {% endif %}
<p> <p>
After you update, check <b>INFO_UF2.TXT</b> to verify that the bootloader version has been updated. If you are updating TinyUF2, look at <strong>INFO_UF2.TXT</strong> to verify the new version of TinyUF2,
Then you will need to load or reload CircuitPython using the <b>.uf2</b> file. by checking the version number.
Then you will need to copy the CircuitPython<strong>.uf2</strong> file to the <strong>BOOT</strong> drive.
</p> </p>
<div> <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>
</div> </div>
{% else %} {% else %}
@ -313,7 +319,7 @@ By the way, boolean operation precedence is right to left! (yeesh)
<strong>The bootloader allows you to load CircuitPython, MakeCode, and Arduino programs. <strong>The bootloader allows you to load CircuitPython, MakeCode, and Arduino programs.
The bootloader is not CircuitPython.</strong> The bootloader is not CircuitPython.</strong>
You can check the current version of your bootloader by looking in 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>
<p> <p>
It is not necessary to update your bootloader if it is working fine. It is not necessary to update your bootloader if it is working fine.
@ -324,17 +330,17 @@ By the way, boolean operation precedence is right to left! (yeesh)
{% if page.family == 'nrf52840' %} {% if page.family == 'nrf52840' %}
<p> <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. Older bootloaders cannot load the firmware.
To check the version of your board's bootloader, To check the version of your board's bootloader,
look at <i>INFO_UF2.TXT</i> when the <i>BOOT</i> drive is present. look at <strong>INFO_UF2.TXT</strong> when the <strong>BOOT</strong> drive is present.
</b> </strong>
To update the bootloader, refer to the "Update Bootloader" page in the guide for To update the bootloader, refer to the "Update Bootloader" page in the guide for
your board, or start with your board, or start with
<a href="https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/update-bootloader">this page</a>. <a href="https://learn.adafruit.com/introducing-the-adafruit-nrf52840-feather/update-bootloader">this page</a>.
</p> </p>
<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. Then you will need to reload CircuitPython.
</p> </p>
<div> <div>
@ -344,11 +350,11 @@ By the way, boolean operation precedence is right to left! (yeesh)
{% if page.family == 'atmel-samd' %} {% if page.family == 'atmel-samd' %}
<p> <p>
To update, first save the contents of <b>CIRCUITPY</b>, just in case. To update, first save the contents of <strong>CIRCUITPY</strong>, just in case.
Then double-click the reset button to show the <b>BOOT</b> drive. Then double-click the reset button to show the <strong>BOOT</strong> drive.
Drag the <b>update-bootloader</b> <b>.uf2</b> file to the <b>BOOT</b> 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 <b>BOOT</b> drive will reappear. Wait a few tens of seconds for the bootloader to update; the <strong>BOOT</strong> drive will reappear.
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. Then you will need to reload CircuitPython.
</p> </p>
<p> <p>