- 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 @@ By the way, boolean operation precedence is right to left! (yeesh) {% 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' %}
@@ -235,72 +235,78 @@ By the way, boolean operation precedence is right to left! (yeesh)
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. +
+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).
- 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. + 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.
- -- Note: update.uf2 files are not currently working on ESP32-S2 or ESP32-S3 boards. +
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.
- -Important: - this will erase previously flashed firmware and sketches from the board, - but needs to be perfomed only once. +
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.
-- 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.
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' %}
- 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.
- 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.