Flash LVGL CircuitPython on a Qualia
This guide builds a full-LVGL CircuitPython image for the Adafruit Qualia S3
RGB666 (adafruit_qualia_s3_rgb666) and flashes it, keeping Adafruit’s TinyUF2
bootloader. The same steps apply to any 16 MB ESP32-S3 board whose stock app
partition is too small for LVGL.
Build
omnipython-builds’
build.py fetches CircuitPython, hands omnipython-lvgl’s CircuitPython port to its make as a
user C module, and runs the build. Two things go on the end of the command for
this board. CIRCUITPY_GIFIO=0 stops CircuitPython’s AnimatedGIF decoder
colliding with LVGL’s. A partition table with a 4 MB app slot goes in through
FLASH_SIZE_SDKCONFIG, because the stock 16 MB table gives the app 2 MB and the
LVGL firmware is about 2.9 MB.
git clone https://github.com/PyDevices/omnipython-builds
git clone --recurse-submodules --shallow-submodules https://github.com/PyDevices/omnipython-lvgl
cd omnipython-builds
LVCP="$(realpath ../omnipython-lvgl/ports/circuitpython)"
PARTS="$(pwd)/qualia-lvgl-partitions.defaults"
printf 'CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="%s"\nCONFIG_PARTITION_TABLE_FILENAME="%s"\n' \
"$LVCP/scripts/partitions-16MB-lvgl.csv" "$LVCP/scripts/partitions-16MB-lvgl.csv" \
> "$PARTS"
./build.py --interpreter circuitpython --port espressif \
--board adafruit_qualia_s3_rgb666 --modules "$LVCP" CIRCUITPY_GIFIO=0 \
"FLASH_SIZE_SDKCONFIG=esp-idf-config/sdkconfig-flash-16MB.defaults;$PARTS"
The first build clones CircuitPython and ESP-IDF, so it needs the network and takes a while. Later builds reuse them.
The output is in builds/circuitpython/espressif/adafruit_qualia_s3_rgb666/. A
board whose app slot already holds 3 MB or more needs only CIRCUITPY_GIFIO=0.
The partition path must be absolute. A relative path outside the port tree is ignored by the IDF’s config generator, and the build silently keeps the stock 2 MB table. Check the built config:
grep PARTITION_TABLE_FILENAME builds/circuitpython/espressif/adafruit_qualia_s3_rgb666/esp-idf/sdkconfig
It should name partitions-16MB-lvgl.csv. A good link reports about 2.9 MB used
(2942608 bytes used on CircuitPython 11.0.0-alpha.2) out of 4194304 bytes. Without the right table the build ends
in Too little flash!!!.
ports/circuitpython/scripts/partitions-16MB-lvgl.csv has ota_0 = 4096K; it moves uf2 to
0x610000 and shrinks user_fs.
Build files
In builds/circuitpython/espressif/adafruit_qualia_s3_rgb666/:
File |
Role |
|---|---|
|
App image only (flash at |
|
Joined IDF bootloader, partition table and app (esptool at |
|
Starts at |
firmware.uf2 needs no conversion. Like Adafruit’s official Qualia UF2s, it
starts at address 0x0, which TinyUF2 maps into ota_0, with family
0xc47e5767 (ESP32-S3).
Other build errors
Symptom |
Likely cause |
Action |
|---|---|---|
|
LVGL’s hundreds of |
Use |
|
Espressif’s warning flags |
|
Duplicate |
gifio and LVGL’s gif |
Put |
|
The stock partition CSV is still selected |
Add the |
Flash
Do not flash the joined firmware.bin if you want Adafruit’s TinyUF2. It
replaces the second-stage path with the IDF bootloader. Adafruit’s documented
flow uses TinyUF2, and the stock TinyUF2 layout (ota_0 = 2048K) cannot hold a
2.9 MB LVGL app. The 4 MB table above is what makes room.
Put the board in ROM download mode
From a running CircuitPython, no buttons are needed:
import microcontroller
microcontroller.on_next_reset(microcontroller.RunMode.BOOTLOADER)
microcontroller.reset()
The board comes back as 303A:0009, the S3’s ROM USB port.
Without a running CircuitPython, use the buttons. On the Qualia, the buttons are a side stack: Reset (top), UP and DN. Boot0 sits between UP and the MCU, not between UP and DN.
Hold Boot0 -> press and release Reset -> release Boot0
The board then shows USB ID 303A:1001, usually on a new serial port. Other IDs
you may meet:
VID:PID |
Meaning |
|---|---|
|
USB-Serial/JTAG while an app (such as MicroPython) runs |
|
ROM download mode, entered with the buttons |
|
ROM download mode, entered from CircuitPython |
|
TinyUF2 CDC; volume |
|
CircuitPython on the Qualia; volume |
esptool --before usb-reset while the app owns the port usually fails with
Invalid head of packet (0x08), so enter ROM mode one of the two ways above.
--after hard-reset often leaves the chip in ROM; --after watchdog-reset
restarts it. esptool 5.x rejects --flash-freq 120m: use 80m or keep.
Write TinyUF2, the partition table and the app
Download the TinyUF2 0.35.0 zip for the Qualia from the
tinyuf2 releases and take
bootloader.bin, tinyuf2.bin and ota_data_initial.bin from it. Make the
partition table binary from partitions-16MB-lvgl.csv with the IDF’s
gen_esp32part.py. In ROM mode:
python -m esptool --chip esp32s3 -p <serial-port> --before no-reset --after watchdog-reset --baud 460800 \
write-flash --flash-mode dio --flash-freq 80m --flash-size 16MB \
0x0 bootloader.bin \
0x8000 partition-table-lvgl.bin \
0xe000 ota_data_initial.bin \
0x10000 circuitpython-firmware.bin \
0x610000 tinyuf2.bin
The board restarts into TinyUF2 by itself.
Copy the UF2 once
ota_data_initial.bin from the TinyUF2 zip is all 0xFF. With a factory
(uf2) partition present, the bootloader chooses TinyUF2 and shows TFT_S3BOOT,
even though ota_0 already holds a valid app. With TFT_S3BOOT mounted, copy
the LVGL .uf2 (address 0x0) onto the drive. TinyUF2 programs ota_0 and
updates otadata, and the board comes back as CIRCUITPY with 239A:8148.
INFO_UF2.TXT on the drive shows Flash Size: 0x00400000 when the LVGL table
is active. Stock TinyUF2 shows 0x00200000.
Verify
At the CircuitPython prompt:
>>> import lvgl
>>> print(lvgl)
<module 'lvgl'>
Back to stock
For a baseline without LVGL, put the board in ROM mode and flash TinyUF2’s
combined.bin at 0x0 (dio, 80m, 16MB), press Reset to reach
TFT_S3BOOT, and copy Adafruit’s official UF2 from
circuitpython.org.
The official app is about 2 MB (1,957,712 bytes for 11.0.0-alpha.2), which
fits the stock 2 MB ota_0; LVGL adds about 1 MB to it.