Fit firmware on a small flash

On esp32 and rp2 the build can grow the firmware’s share of flash to fit the image: on esp32 the app partition, on rp2 the region before the filesystem. It leaves 1/32 of the flash as headroom, 64 KB to 256 KB. That moves the filesystem, so a board flashed with that image comes up with an empty one.

On the Arduino GIGA R1 the firmware has 1,280 KB, and the 512 KB after it is the M4 core’s. A build that doesn’t fit takes that too, 1,792 KB in all, and leaves out OpenAMP, which loads and talks to M4 programs: with its flash taken, the board has nowhere to keep one. The filesystem doesn’t move. The flash guide says what that means for the M4.

To refuse the growth and stop instead, add --no-autosize.

Keep a board’s files through an update

Autosize works the firmware’s share out again in each new build folder, so a newer image that is a few KB bigger can come out with a smaller filesystem than the one already on your board, and flashing it empties the board. To keep the board’s filesystem where it is, ask the board its size. On rp2:

import rp2
f = rp2.Flash()
print(f.ioctl(4, 0) * f.ioctl(5, 0))  # 589824 is 576 KB

On esp32:

import esp32
print(esp32.Partition.find(esp32.Partition.TYPE_DATA, label="vfs")[0].info()[3])  # 2752512 is 2688 KB

and build with that size:

./build.py --port rp2 --board RPI_PICO --modules displayif,lvgl,omnipython --keep-fs 576K
./build.py --port esp32 --board ESP32_GENERIC_S3 --variant LCD_7 --flash 8MB --modules all --keep-fs 2688K

If the firmware fits beside it, the image keeps that filesystem and your files are there after the flash. If it doesn’t, the build stops and says what size would fit, rather than moving it. On esp32 the filesystem is the end of the flash, so --keep-fs needs --flash, and the app partition takes the flash before it. On rp2, a rebuild in the same build folder starts from the size that folder used last, so it keeps the filesystem without --keep-fs unless the image has outgrown it.

The firmware page’s MicroPython images are built this way, so updating a board from one release to the next keeps its files. A release that has to move a board’s filesystem says so at the top of its notes.

On esp32, autosize works only if the flash size is right: the partition table tool refuses a table larger than the configured flash, so give --flash.

What you will see

The build finds out by trying. The first link fails, loudly, and only then does it build again. On esp32 that is a red Error: app partition is too small for binary micropython.bin size 0x…, then ninja: build stopped, make: *** Error 1 and a Build-Troubleshooting link. On rp2 it is region `FLASH' overflowed by … bytes, collect2: error: ld returned 1 exit status and nested Error 2 lines; on the GIGA, region `FLASH_TEXT' overflowed by … bytes. Then an autosize: line says the image didn’t fit and the build is running once more. On the GIGA that second build starts from scratch, because leaving out OpenAMP changes what every file is compiled with; a later build of the same modules starts in the larger region. With all, expect that second pass on every esp32 and rp2 board; it roughly doubles the build time, because the whole esp32 compile runs twice.

When nothing will fit

How much fits depends on the flash. On a Pico 2 (4 MB), all builds and fits, using 94 % of its 3392 KB firmware region and leaving a 704 KB filesystem. On a Pico (2 MB) it can’t: the image is bigger than the whole flash, so the build stops at the first link with the overflow error. Name what your project uses instead:

./build.py --port rp2 --board RPI_PICO --modules displayif,jpegio,pygraphics,palettes,pdwidgets

A display project’s set like this one builds to about 540 KB and fits with the Pico’s default 1408 KB filesystem untouched.

On a 4 MB ESP32, audioinstruments is the biggest of the modules, and you can freeze only the instruments you play, and of audioeffects only the effects you use: Build with a few instruments and effects.