make-uf2

Convert Astrobe binaries to UF2 format for Raspberry Pi microcontrollers

Name

make-uf2 – convert Astrobe binaries to UF2 format for Raspberry Pi microcontrollers

Synopsis

make-uf2 rp2040 bin_file [-v] [-b boot2_file]

make-uf2 rp2350 bin_file [-v] [--ns] [--no-meta]

Description

make-uf2 converts an Astrobe .bin file into a UF2 file that can be loaded onto an RP2040 (Pico) or RP2350 (Pico2) board. The UF2 file is written to the same directory as the input, with the .uf2 extension.

The tool has two subcommands, one for each target family. Each subcommand handles the chip-specific details:

rp2040 – Prepends a checksummed second-stage boot block (boot2.uf2) required for QSPI flash initialisation on the RP2040. The program code is placed at 10000100H (after the 256-byte boot block).

rp2350 – Prepends a 256-byte picobin metadata block containing an IMAGE_DEF entry and vector table pointer. The metadata block is placed at 10000000H and the program code at 10000100H. The image is tagged as Secure ARM by default.

The binary is split into 256-byte UF2 blocks with the appropriate family ID and flash addresses. The resulting .uf2 file can be copied to a Pico or Pico2 in BOOTSEL mode (mass-storage device), or uploaded using picotool.

Supported platforms: Windows and macOS.

Subcommands

rp2040

Create a UF2 file for the RP2040 (Pico).

bin_file: Path to the Astrobe .bin file (positional, required).
-v, --verbose: Print details: file paths, family ID, initial stack pointer, and entry address.
-b boot2_file: Path to the second-stage boot block file. Default: boot2.uf2 in the same directory as the make-uf2 installation. This file is a pre-compiled RP2040 boot2 image that initialises the QSPI flash interface.

rp2350

Create a UF2 file for the RP2350 (Pico2).

bin_file: Path to the Astrobe .bin file (positional, required).
-v, --verbose: Print details: file paths, family ID, security mode, initial stack pointer, and entry address.
--ns: Tag the image as Non-secure (rp2350-arm-ns). Default: Secure (rp2350-arm-s). This sets the UF2 family ID and the IMAGE_DEF security flag in the metadata block.
--no-meta: Do not prepend the metadata block. The program binary is written directly starting at 10000000H without an IMAGE_DEF entry.

Output

The UF2 file is written to the same directory as the input .bin file, with the same base name and the .uf2 extension. For example, SignalSync.bin produces SignalSync.uf2.

Examples

Create a UF2 file for RP2040:

make-uf2 rp2040 SignalSync.bin

Create a UF2 file for RP2350 (Secure, with metadata):

make-uf2 rp2350 SignalSync.bin

Create a UF2 file for RP2350 tagged as Non-secure:

make-uf2 rp2350 SignalSync.bin --ns

Create a UF2 file for RP2350 without metadata block:

make-uf2 rp2350 SignalSync.bin --no-meta

Verbose output:

make-uf2 rp2350 -v SignalSync.bin

UF2 Format

UF2 (USB Flashing Format) is a file format designed for flashing microcontrollers over USB. Each 512-byte UF2 block carries 256 bytes of payload data, a target flash address, and a family ID identifying the target chip. The RP2040 and RP2350 boot ROMs recognise UF2 files when the board is in BOOTSEL mode (entered by holding the BOOTSEL button during power-on or reset).

Loading

To load a UF2 file onto a board:

put the board into BOOTSEL mode (hold the BOOTSEL button while connecting USB or resetting)
the board appears as a USB mass-storage device
copy the .uf2 file to the device

The board reboots and runs the program automatically after the copy completes.

Diagnostics

The tool exits with status 0 on success and status 1 on any error. Common error conditions include:

binary file not found or not readable
Boot2 file not found (rp2040 subcommand)
unsupported platform (neither Windows nor macOS)

Notes

Astrobe produces a UF2 file automatically as part of the linking process. Both Astrobe and make-uf2 prepend a 256-byte block before the program code (a boot block on the RP2040, a metadata block on the RP2350), so the code start address in the Astrobe .ini configuration file must be 10000100H in both cases.

On the RP2040, the boot block is always required and both tools handle it the same way. The UF2 files produced by Astrobe and make-uf2 are binary equal.

On the RP2350, Astrobe includes the metadata block as a module within the program and uses a code start address of 10000000H. make-uf2 takes a different approach: it prepends the metadata block to the binary, requiring the code start address to be 10000100H. The two approaches produce UF2 files that are not binary equal.

The boot2.uf2 file distributed with make-uf2 is a pre-compiled second-stage boot block for the RP2040 QSPI flash interface. It is Copyright © 2019-2021 Raspberry Pi (Trading) Ltd., licensed under BSD-3-Clause.

The RP2350 metadata block follows the picobin format. It contains an IMAGE_DEF item (Secure or Non-secure ARM executable), a vector table pointer, and self-referencing link and terminator items. This is the same format used by the --image-def option in make-elf, but embedded in the UF2 stream rather than the ELF file.