From 9926b45497e7f367e60dc44ee5414c4d497ec0e2 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 15 Jul 2025 09:11:47 -0400 Subject: [PATCH 1/3] bump Espressif TinyUF2 version to 0.35.0 --- _data/bootloaders.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_data/bootloaders.json b/_data/bootloaders.json index 65d81c3333..6aab159b1b 100644 --- a/_data/bootloaders.json +++ b/_data/bootloaders.json @@ -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": {}, From a8e05c8a9415ad2d4aa0df49151af94bec798843 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 15 Jul 2025 09:12:17 -0400 Subject: [PATCH 2/3] Rework Espressif bootloader section --- _includes/download/board.html | 114 ++++++++++++++++++---------------- 1 file changed, 60 insertions(+), 54 deletions(-) diff --git a/_includes/download/board.html b/_includes/download/board.html index 481bdd72ed..652e44f8d6 100644 --- a/_includes/download/board.html +++ b/_includes/download/board.html @@ -39,8 +39,8 @@

CircuitPython {{ version.version }}

{% endif %} {% if page.family == 'nrf52840' %}

- 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 Update UF2 Bootloader below. + 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 Update UF2 Bootloader below.

{% endif %}

@@ -227,7 +227,7 @@

Previous Versions of CircuitPython

{% 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' %}

Install, Repair, or Update UF2 Bootloader

@@ -235,72 +235,78 @@

Install, Repair, or Update UF2 Bootloader

The UF2 bootloader allows you to load CircuitPython, MakeCode, and Arduino programs. - The bootloader is not CircuitPython. - If a UF2 bootloader is installed, you can check its version by looking in - the INFO_UF2.TXT file when the BOOT drive is visible - (FTHRS2BOOT, MAGTAGBOOT, HOUSEBOOT, etc.) + + The bootloader itself is not CircuitPython. + On Espressif boards, the UF2 bootloader is called TinyUF2. + If the TinyUF2 bootloader is installed, you can check its version by looking in + the INFO_UF2.TXT file when the BOOT drive is visible + (FTHRS2BOOT, MAGTAGBOOT, HOUSEBOOT, etc.)

- It is not necessary to reinstall a UF2 bootloader you unless a BOOT 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 in general necessary to update TinyUF2 at every version change. + You can read the release notes on GitHub to see what has been changed. + Update if you've been told about a necessary change or a bug fix.

-

- 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 .uf2 files onto the board. .bin files can be uploaded without a UF2 bootloader, using the - ESP Web Flasher - or esptool.py. +

Note: + CircuitPython 10 and later, on Espressif boards with 4MB flash, requires TinyUF2 0.33.0 or later. + The flash partition layout has changed (details).

-

- Note: update.uf2 files are not currently working on ESP32-S2 or ESP32-S3 boards. + 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 .uf2 files onto the board. + But you don't need the TinyUF2 bootloader to upload .bin files. They can be uploaded using the + built-in ROM bootloader, with the + Adafruit WebSerial ESPTool + or esptool.py.

- -

Important: - this will erase previously flashed firmware and sketches from the board, - but needs to be perfomed only once. +

Warning: + Installing the TinyUF2 bootloader will erase everything that was previously on the board. + Save any files in CIRCUITPY for which you don't have backups. +

+

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 Factory Reset page + in the Learn Guide for your particular board (example).

-

The instructions here are general. - We recommend you consult the manufacturer's board documentation for detailed - instructions, which may be different. +

The easiest way to install TinyUF2 is to use the OPEN INSTALLER button + (see above, in the CiruitPython sections). + You can also use the Adafruit WebSerial ESPTool, or esptool.py, + as described in the Factory Reset page.

-
    -
  • Unzip to find the file combined.bin.
    • -
  • Place board in bootloader mode: +
  • If you are not using the OPEN INSTALLER button, + download the combined.bin file using the DOWNLOAD BOOTLOADER combined.bin button below. + (If you use OPEN INSTALLER, it will do the download itself.)
    • +
  • First, place board in ROM bootloader mode:
    • 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.
      • -
    • Press and hold down the BOOT or 0 button.
      • -
    • Press and release the RESET or RST button.
      • -
    • Release the BOOT button.
      • +
    • Press and hold the BOOT button (sometimes marked "B0").
      • +
    • Press and release the RESET button (sometimes marked "RST").
      • +
    • Release the BOOT button. This starts the ROM bootloader.
    • -
  • Upload combined.bin (Google Chrome 89 or newer): -
      -
    • Open ESP Web Flasher in a new window/tab.
      • -
    • Select 460800 Baud from the pull-down menu (top-right).
      • -
    • Click Connect (top-right).
      • -
    • Select the COM or Serial port from the pop-up window.
      • -
    • After successful connection, click Erase.
      • -
    • After successful erase, click any Choose a file..., then locate and select the combined.bin file unzipped earlier.
      • -
    • After successfully choosing combined.bin, click Program.
      • -
    • After the TinyUF2 firmware update is complete, press the RESET button on the board. - A new drive BOOT should be visible in your file browser.
      • +
    • Then proceed with OPEN INSTALLER or one of the other tools.
      • +
    • After the TinyUF2 firmware installation is complete, press the RESET button on the board. + A new drive BOOT drive should be visible in your file browser.
{% if bootloader_instructions == nil %}

- 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.

{% else %}

{{ bootloader_instructions }}

{% endif %}

- After you update, check INFO_UF2.TXT to verify that the bootloader version has been updated. - Then you will need to load or reload CircuitPython using the .uf2 file. + If you are updating TinyUF2, look at INFO_UF2.TXT to verify the new version of TinyUF2, + by checking the version number. + Then you will need to copy the CircuitPython.uf2 file to the BOOT drive.

- DOWNLOAD BOOTLOADER ZIP + DOWNLOAD BOOTLOADER combined.bin
{% else %} @@ -313,7 +319,7 @@

Update UF2 Bootloader

The bootloader allows you to load CircuitPython, MakeCode, and Arduino programs. The bootloader is not CircuitPython. You can check the current version of your bootloader by looking in - the INFO_UF2.TXT file when the BOOT drive is visible (FEATHERBOOT, CPLAYBOOT, etc.). + the INFO_UF2.TXT file when the BOOT drive is visible (FEATHERBOOT, CPLAYBOOT, etc.).

It is not necessary to update your bootloader if it is working fine. @@ -324,17 +330,17 @@

Update UF2 Bootloader

{% if page.family == 'nrf52840' %}

- On nRF boards, CircuitPython 8.2.0 and later require UF2 bootloader version 0.6.1 or later. + 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 INFO_UF2.TXT when the BOOT drive is present. - + look at INFO_UF2.TXT when the BOOT drive is present. + To update the bootloader, refer to the "Update Bootloader" page in the guide for your board, or start with this page.

- After you update, check INFO_UF2.TXT to verify that the bootloader version has been updated. + After you update, check INFO_UF2.TXT to verify that the bootloader version has been updated. Then you will need to reload CircuitPython.

@@ -344,11 +350,11 @@

Update UF2 Bootloader

{% if page.family == 'atmel-samd' %}

- To update, first save the contents of CIRCUITPY, just in case. - Then double-click the reset button to show the BOOT drive. - Drag the update-bootloader .uf2 file to the BOOT drive. - Wait a few tens of seconds for the bootloader to update; the BOOT drive will reappear. - After you update, check INFO_UF2.TXT to verify that the bootloader version has been updated. + To update, first save the contents of CIRCUITPY, just in case. + Then double-click the reset button to show the BOOT drive. + Drag the update-bootloader .uf2 file to the BOOT drive. + Wait a few tens of seconds for the bootloader to update; the BOOT drive will reappear. + After you update, check INFO_UF2.TXT to verify that the bootloader version has been updated. Then you will need to reload CircuitPython.

From 5b21fa761a046dc32939ef7213101db0e3524cd3 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 15 Jul 2025 10:13:50 -0400 Subject: [PATCH 3/3] repititious "general..." --- _includes/download/board.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_includes/download/board.html b/_includes/download/board.html index 652e44f8d6..a492cf8517 100644 --- a/_includes/download/board.html +++ b/_includes/download/board.html @@ -243,7 +243,7 @@

Install, Repair, or Update UF2 Bootloader

(FTHRS2BOOT, MAGTAGBOOT, HOUSEBOOT, etc.)

- In general, it is not in general necessary to update TinyUF2 at every version change. + In general, it is not necessary to update TinyUF2 at every version change. You can read the release notes on GitHub to see what has been changed. Update if you've been told about a necessary change or a bug fix.