UF2 drag-and-drop flashing

The UF2 downloader is a small program that runs on the board: the board appears as a USB drive F101BOOT, and copying a .uf2 file into it writes the file to SPI NOR and reboots automatically when done. Once it is installed, downloading an application no longer needs xfel and FEL. For installing the downloader itself and the day-to-day use of .uf2 files, see Build and run; this page is the reference.

Entering the downloader

• When powering on, hold the button on PD5 (active low, internally pulled up) and the loader runs the downloader instead of the application.
• When there is no valid application in Flash, it also enters automatically without pressing the button.

The downloader source is zephyr-components/uf2-downloader/; build it with:

west build -b yuzukineko -d build/uf2 zephyr-components/uf2-downloader

Creating a .uf2

Generate one from an image with zephyr-components/uf2-downloader/tools/mkuf2.py:

mkuf2.py app build/hello/zephyr/zephyr.bin -o app.uf2       # application, Flash 0x200000
mkuf2.py system build/uf2/zephyr/zephyr.bin -o dl.uf2       # the downloader itself, Flash 0x030000
mkuf2.py loader flash-boot_spi.bin -o loader.uf2            # loader, Flash 0

Type	UF2 family	Write location	Writable range
app	0x31303146	0x200000	Application area only
system, loader	0x31303147	0x030000 / 0x000000	Any location

Common options: --load <address> sets the PSRAM address the image is loaded to (default 0x40000000, the same as the Zephyr link address); --raw outputs a raw Flash image with a header page instead of a .uf2, for use with xfel spinor write.

Caution

system and loader files can be written to any location; if you write them wrongly the board has no loader, and then only FEL can recover it. Only drag in files you trust, and do not cut power while writing.

Flash layout (16 MiB)

Content	Offset	Maximum size
Loader (three copies)	0x000000 / 0x010000 / 0x020000	64 KiB each
Saved Flash sampling points	0x02f000	Maintained by the loader itself; do not overwrite
System program (UF2 downloader)	0x030000	0x1CF000 bytes
Application	0x200000	0x9F0000 bytes

Both the downloader and the application carry a 4 KiB header page recording the PSRAM address and size the image is loaded to, generated by mkuf2.py. For the header page and the loader flash-boot implementation, see SyterKit. This layout is incompatible with the layout of the Linux and Asterinas images; see SPI NOR layout and backup.

First installation

When the board does not yet have the loader and the downloader, you must write them once with xfel; the steps are in “Step 1” of Build and run. Once the loader is in Flash, the board no longer enters FEL on its own, and you need to hold the FEL button; see FEL download mode and tools.