elf2flash
A tool for converting ELF binaries into UF2 format and flashing them to a microcontroller (RP2040, RP2350, CircuitPlaygroundBluefruit, etc.) and other supported boards.
Options
Usage: elf2flash [OPTIONS] [COMMAND]
Commands:
convert Convert ELF to UF2 file on disk
deploy Deploy ELF directly to a connected board
help Print this message or the help of the given subcommand(s)
Options:
-v, --verbose <VERBOSE> Set the logging verbosity [default: info] [possible values: off, error, warn, info, debug, trace]
-h, --help Print help
-V, --version Print version
Deploying
Usage: elf2flash deploy [OPTIONS] <INPUT>
Arguments:
<INPUT> Input ELF file
Options:
-b, --board <BOARD>
Same options as convert…
-v, --verbose <VERBOSE>
Set the logging verbosity [default: info] [possible values: off, error, warn, info, debug, trace]
-f, --family <FAMILY>
Override family ID
-e, --flash-sector-erase-size <FLASH_SECTOR_ERASE_SIZE>
Flash erase sector size
-p, --page-size <PAGE_SIZE>
Page size
-s, --serial
Connect to serial after deploy
-t, --term
Send termination message on Ctrl+C
-h, --help
Print help
Deploy for any project
elf2flash deploy --board rp2040 firmware.elf
Family IDs can be referenced from uf2families.json.
You can pass values in decimal (12345
), hexadecimal (0xe48bff59
), or binary (0b1010...
) formats.
Usage
To make your Rust project automatically flash the microcontroller whenever you run cargo run
, add this to your .cargo/config.toml
.
[]
= "elf2flash deploy -t -s"
[]
# target = "thumbv6m-none-eabi" # Pico 1 / Cortex-M0/M0+
= "thumbv8m.main-none-eabihf" # Pico 2 / Cortex-M23/M33
[]
= "debug"
If multiple boards are connected, elf2flash
will detect them and attempt to flash each valid UF2 partition automatically.
You can also force a specific board using --board rp2040
or --board rp2350
.
Adding support for a board
If you want to flash to an unsupported uf2 board, just add in the flags --family
, --flash-sector-erase-size
, and --page-size
, these have resonable defaults, so if you are unsure what the value is, just don't provide it, and attempt running.
If you wish to add a new default supported board, open a PR or an issue with the board you wish to support.
If you open a PR just add a new board under ./crates/elf2flash-core/src/boards/
.
Here is an example for supporting the circuit_playground_bluefruit board.
use crate;
;
If adding the flags doesn't work, please create an issue for your board.
Why this project instead of elf2uf2?
This project:
- Fixes several issues in
elf2uf2-rs
(#36, #38, #40, #41, #42) - Provides a reusable library (
elf2flash-core
) for programmatic use - Supports multiple families and explicit board selection
- Adds progress reporting, automatic board/partition detection, and optional serial logging after deploy
Credits
Thanks to JoNil for the excellent elf2uf2-rs
project, which this builds upon and extends.