picoload

Load binaries onto Raspberry Pi microcontrollers via picotool

Name

picoload – load binaries onto Raspberry Pi microcontrollers via picotool

Synopsis

picoload rp2040 bin_file [-v] [-x] [--quiet]

picoload rp2350 bin_file[:part] … [-v] [-x] [--quiet]

Description

picoload uploads binary files to an RP2040 (Pico) or RP2350 (Pico2) board using picotool. It provides a simplified interface for loading Astrobe-compiled programs, with subcommands for each target family.

The board must be in BOOTSEL mode (hold the BOOTSEL button while connecting USB or resetting).

Supported platforms: Windows and macOS.

Prerequisites

picotool must be installed and available on PATH. See External Tools for installation details.

Subcommands

rp2040

Upload a single binary file to a Pico board.

bin_file: Path to the binary file (positional, required). Typically a .uf2 file produced by make-uf2 or Astrobe.
-v: Verify the loaded data after uploading.
-x: Reboot the device after the file is loaded.
--quiet: Suppress picotool output.

rp2350

Upload one or more binary files to a Pico2 board. Each file may optionally specify a target partition.

bin_file[**:**part] …: One or more binary files (positional, required). Each file may be followed by a colon and a decimal partition number to target a specific flash partition. Without a partition number, picotool uses its default placement. Files may be .uf2 or .bin.
-v: Verify the loaded data after uploading.
-x: Reboot the device after all files are loaded.
--quiet: Suppress picotool output.

Examples

Load a UF2 file onto an RP2040:

picoload rp2040 SignalSync.uf2

Load and reboot:

picoload rp2040 -x SignalSync.uf2

Load with verification:

picoload rp2350 -v SignalSync.uf2

Load multiple files to specific partitions on RP2350:

picoload rp2350 app.uf2:0 data.bin:1

Load and reboot quietly:

picoload rp2350 -x --quiet SignalSync.uf2

Diagnostics

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

picotool not found on PATH
binary file not found
invalid partition number (must be a decimal integer)
picotool reports a loading or reboot error
unsupported platform (neither Windows nor macOS)

Notes

picoload is a convenience wrapper around picotool. All loading and device communication is handled by picotool; picoload constructs the appropriate picotool command lines and manages the sequence of load and reboot operations.

picoload does not add any safety checks beyond what picotool itself provides. If a picotool operation is destructive, the same operation through picoload will be equally destructive. For example, uploading a .bin file without specifying a partition loads in absolute mode, which can overwrite the flash partition table.

The RP2350 subcommand accepts multiple files, which are loaded sequentially. This is useful for multi-partition layouts where different binaries target different flash partitions. If any load fails, the tool stops immediately without loading remaining files.