CircuitPython 10 will change the flash storage layout on Espressif boards with 4MB flash, to allow for larger CircuitPython builds with more features. CircuitPython 10.0.0-alpha.5 makes this change only for the Adafruit Feather ESP32-S3 4MB Flash 2MB PSRAM board, as a trial. Later, the change will be made for all boards.

This page describes how to update your bootloader to use the new storage layout.

Originally, these 4MB boards had two "ota" (over-the-air) partitions. One contained the CIrcuitPython firmware, and the other was empty, to be used as to update the firmware "over the air". However, that functionality was never fully developed, and the space consumed by the unused partition limited the firmware size of CIrcuitPython. The smaller partition size limited the features that could be included.

This diagram shows the old and new partition layout, and how the two partitions are combined into one.

Step A. Download the TinyUF2 .zip release file for your board

Find the latest .zip file for your board, using the link below. Note that many boards have similar names (Feather ESP32-S3 TFT vs. Feather ESP32-S3 Reverse TFT, etc.), so make sure you have exactly the right file. Do not download the .uf2 file.

Step B. Extract the combined.bin file from the TinyUF2 release .zip file

The file you downloaded in Step 2 is a .zip file. Unzip the file and find the combined.bin file. The file may appear to be larger than you expect, but it is actually mostly empty. Save this file to your desktop or wherever you plan to run esptool from, or another convenient location where you can find it.

Step C. Continue as if you are doing a factory reset

From this point on, you should follow the directions on the Factory Reset page for your board. Look in the left sidebar on this page for a link to the Factory Reset page, and start with Step 2 on that page. Follow the instructions on that page to use the WebSerial ESPTool Method or the esptool Method, but, instead of loading a factory reset .bin file, load the combined.bin file you extracted above, in step B. You should still erase the flash as described.

Step D. Load a CircuitPython 10 build onto your board

After you've successfully loaded the new bootloader, when you double-click the Reset button, a ...BOOT drive should appear, such as FTHRS3BOOT. The INFO_UF2.TXT file in that drive should show that it's version 0.31.0 or later. At this point you can load the CircuitPython .uf2 file for your board as usual.

Note that this TinyUF2upgrade is upward compatible with CircuitPython 9.1.0 and later, so if you need to go back to, say, CircuitPython 9.2.7 from CircuitPython 10, you don't need to reinstall the TinyUF2 bootloader.