uf2l is a program for dealing with UF2 format firmware images.
This is similar to the elf2uf2 tool but with less validation and more
capabilities. In particular, this tool will not check that your ELF files
target defined memory regions for your microcontroller (because we don't
know what they are) or that the architecture is correct -- it simply moves
data to and from UF2 files, and does exactly what you ask it to.
Bonus features:
- Can act as a very simple linker for overlaying multiple ELF files, such as a bootloader and a main program.
- Has an
infocommand that will scan UF2 files for potential issues, including detecting files that will set off the RP2040 ROM bug raspberrypi/pico-bootrom-rp2040#19. - Can lookup family IDs using the names used in the UF2 repo
- Has a
flashcommand that will identify attached boards waiting for UF2 firmware files, optionally filter them (in case you have more than one attached), and transfer the packed UF2 output directly. (This command is available when the defaultsysinfofeature is set; you may wish to disable it if you're on an operating system that thesysinfocrate does not support.)
Listing available boards:
uf2l scan
Flashing a program to a Raspberry Pi Pico, which happens to be the default target if no flags are specified, is simple if the program includes the stage 2 bootloader itself:
uf2l flash program.elf
If you have a separate bootloader, such as rp2040-rustboot, you can include it:
uf2l flash rustboot-w25q080.elf program.elf
Flashing a program to the Seeed Wio Terminal board (and not other boards you might have plugged in):
uf2l flash --family-id SAMD51 --board WioTerminal program.elf
uf2l flash can also be defined as the runner in your .cargo/config to
cause cargo run to work. You just need to set the family ID (here it's the
ATSAMD51):
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
runner = "uf2l flash -f SAMD51"To install:
- Clone this repo (tool is not yet on crates.io)
- Run:
cargo install --path . --locked
You'll need a reasonably recent Rust toolchain, ideally one managed by Rustup. I've tested on 1.60.
uf2l --help will get top-level help. Here are snapshots of the help as of the
time of this writing; run the actual program to get current help.
Top level:
uf2l (pronounced U-F-Tool) manipulates UF2 firmware images
USAGE:
uf2l [OPTIONS] <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
-v, --verbose Enable additional output, probably more of it than you'd
like
SUBCOMMANDS:
flash Converts ELF files into UF2 like `pack`, but instead of writing
the result to a normal file, scans for attached bootloaders
emulating USB mass storage devices and copies the firmware
directly to one
help Print this message or the help of the given subcommand(s)
info Read a UF2 file, check validity, and print information about its
contents
pack Convert one or more ELF files into UF2 format
scan Scans for attached bootloaders like `flash`, but lists them
instead of attempting to upload to one
uf2l pack --help:
uf2l-pack
Convert one or more ELF files into UF2 format
USAGE:
uf2l pack [OPTIONS] <INPUTS>... <OUTPUT>
ARGS:
<INPUTS>... Paths to one or more ELF files to combine into a UF2
image. Files must not overlap
<OUTPUT> Path for UF2 output
OPTIONS:
--allow-small-blocks
Allow output to contain partial blocks, smaller than the block size.
Note that common UF2 implementations will choke on this
-b, --block-size <BLOCK_SIZE>
Number of bytes per target system block/page. The UF2 format
effectively limits this to 476 [default: 256]
-e, --pad-erase-sectors <SECTOR_BYTES>
Pad any written data out to erase sector boundaries of this many
bytes, naturally aligned. This is critical for loading files into
the RP2040 to work around a boot ROM bug
-f, --family-id <FAMILY_ID>
Family ID identifying the type of processor this image is intended
for, given either as a decimal number, a hex number prefixed with
`0x`, or the name of the family from the UF2 spec. Pass `help` to
see a list of known names [default: RP2040]
-h, --help
Print help information
--padding <PADDING>
Padding byte to use to pad partial blocks (if --allow-small-blocks
is not set) and unused portions of erase sectors (if
--pad-erase-sectors is set) [default: 0]
-v, --verbose
Enable additional output, probably more of it than you'd like
uf2l flash --help:
uf2l-flash
Converts ELF files into UF2 like `pack`, but instead of writing the result to a
normal file, scans for attached bootloaders emulating USB mass storage devices
and copies the firmware directly to one.
Any mounted drive that contains an `INFO_UF2.TXT` file at its root will be
considered as a potential attached bootloader. Arguments to this command allow
filtering based on the contents of that file.
USAGE:
uf2l flash [OPTIONS] <INPUTS>...
ARGS:
<INPUTS>... Paths to one or more ELF files to combine into a UF2
image. Files must not overlap
OPTIONS:
--allow-small-blocks
Allow output to contain partial blocks, smaller than the block size.
Note that common UF2 implementations will choke on this
-b, --block-size <BLOCK_SIZE>
Number of bytes per target system block/page. The UF2 format
effectively limits this to 476 [default: 256]
--board <BOARD>
Board type to search for when enumerating UF2 bootloaders. This will
be used to match the second component of the `Board-Id` line of an
`INFO_UF2.TXT` file. If omitted, any board will be accepted
--cpu <CPU>
CPU type to search for when enumerating UF2 bootloaders. This will
be used to match the first component of the `Board-Id` line of an
`INFO_UF2.TXT` file. If omitted, any CPU type will be accepted
-e, --pad-erase-sectors <SECTOR_BYTES>
Pad any written data out to erase sector boundaries of this many
bytes, naturally aligned. This is critical for loading files into
the RP2040 to work around a boot ROM bug
-f, --family-id <FAMILY_ID>
Family ID identifying the type of processor this image is intended
for, given either as a decimal number, a hex number prefixed with
`0x`, or the name of the family from the UF2 spec. Pass `help` to
see a list of known names [default: RP2040]
--feeling-lucky
Normally, the tool will fail if multiple attached bootloaders match,
to avoid doing something questionable. This flag overrides that
behavior and arbitrarily selects one
-h, --help
Print help information
--padding <PADDING>
Padding byte to use to pad partial blocks (if --allow-small-blocks
is not set) and unused portions of erase sectors (if
--pad-erase-sectors is set) [default: 0]
--revision <REVISION>
Board revision to search for when enumerating UF2 bootloaders. This
will be used to match the third component of the `Board-Id` line of
an `INFO_UF2.TXT` file. If omitted, any board revision will be
accepted
-v, --verbose
Enable additional output, probably more of it than you'd like
uf2l info --help:
uf2l-info
Read a UF2 file, check validity, and print information about its contents
USAGE:
uf2l info [OPTIONS] <INPUT>
ARGS:
<INPUT> Path to a UF2 file to analyze
OPTIONS:
-h, --help Print help information
-v, --verbose Enable additional output, probably more of it than you'd
like
uf2l scan --help:
uf2l-scan
Scans for attached bootloaders like `flash`, but lists them instead of
attempting to upload to one
USAGE:
uf2l scan [OPTIONS]
OPTIONS:
--board <BOARD>
Board type to search for when enumerating UF2 bootloaders. This will
be used to match the second component of the `Board-Id` line of an
`INFO_UF2.TXT` file. If omitted, any board will be accepted
--cpu <CPU>
CPU type to search for when enumerating UF2 bootloaders. This will
be used to match the first component of the `Board-Id` line of an
`INFO_UF2.TXT` file. If omitted, any CPU type will be accepted
-h, --help
Print help information
--revision <REVISION>
Board revision to search for when enumerating UF2 bootloaders. This
will be used to match the third component of the `Board-Id` line of
an `INFO_UF2.TXT` file. If omitted, any board revision will be
accepted
-v, --verbose
Enable additional output, probably more of it than you'd like