This template is intended as a starting point for developing your own firmware based on the rp2040-hal.
It includes all of the
knurling-rs tooling as showcased in https://github.com/knurling-rs/app-template (
flip-link) to make development as easy as possible.
probe-run is configured as the default runner, so you can start your program as easy as
cargo run --release
If you aren't using a debugger, check out alternative runners for other options
The standard Rust tooling (cargo, rustup) which you can install from https://rustup.rs/
Toolchain support for the cortex-m0+ processors in the rp2040 (thumbv6m-none-eabi)
flip-link - this allows you to detect stack-overflows on the first core, which is the only supported target for now.
probe-run. Upstream support for RP2040 was added with version 0.3.1.
A CMSIS-DAP probe. (J-Link and other probes will not work with probe-run)
You can use a second Pico as a CMSIS-DAP debug probe by installing the following firmware on it: https://github.com/majbthrd/DapperMime/releases/download/20210225/raspberry_pi_pico-DapperMime.uf2
More details on supported debug probes can be found in debug_probes.md
rustup target install thumbv6m-none-eabi cargo install flip-link # This is our suggested default 'runner' cargo install probe-run # If you want to use elf2uf2-rs instead of probe-run, instead do... cargo install elf2uf2-rs --locked
For a debug build
For a release build
cargo run --release
If you do not specify a DEFMT_LOG level, it will be set to
debug!("") statements will be printed.
If you wish to override this, you can change it in
[env] DEFMT_LOG = "off"
You can also set this inline (on Linux/MacOS)
DEFMT_LOG=trace cargo run
or set the environment variable so that it applies to every
cargo run call that follows:
Setting the DEFMT_LOG level for the current session
Windows users can only override DEFMT_LOG through
or by setting the environment variable as a separate step before calling
$Env:DEFMT_LOG = trace
If you don't have a debug probe or if you want to do interactive debugging you can set up an alternative runner for cargo.
Some of the options for your
runner are listed below:
Loading a UF2 over USB
Step 1 - Install
$ cargo install elf2uf2-rs --locked
Step 2 - Make sure your .cargo/config contains the following
[target.thumbv6m-none-eabi] runner = "elf2uf2-rs -d"
thumbv6m-none-eabi target may be replaced by the all-Arm wildcard
'cfg(all(target_arch = "arm", target_os = "none"))'.
Step 3 - Boot your RP2040 into "USB Bootloader mode", typically by rebooting whilst holding some kind of "Boot Select" button. On Linux, you will also need to 'mount' the device, like you would a USB Thumb Drive.
Step 4 - Use
cargo run, which will compile the code and started the
specified 'runner'. As the 'runner' is the elf2uf2-rs tool, it will build a UF2
file and copy it to your RP2040.
$ cargo run --release --example pico_pwm_blink
Loading with picotool
As ELF files produced by compiling Rust code are completely compatible with ELF files produced by compiling C or C++ code, you can also use the Raspberry Pi tool picotool. The only thing to be aware of is that picotool expects your ELF files to have a
.elf extension, and
by default Rust does not give the ELF files any extension. You can fix this by
simply renaming the file.
This means you can't easily use it as a cargo runner - yet.
Also of note is that the special
pico-sdk macros which hide
information in the ELF file in a way that
picotool info can read it out, are
not supported in Rust. An alternative is TBC.
NOTE These packages are under active development. As such, it is likely to remain volatile until a 1.0.0 release.
See the open issues for a list of proposed features (and known issues).
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
The steps are:
git checkout -b feature/AmazingFeature)
git commit -m 'Add some AmazingFeature')
git push origin feature/AmazingFeature)
The contents of this repository are dual-licensed under the MIT OR Apache
2.0 License. That means you can chose either the MIT licence or the
Apache-2.0 licence when you re-use this code. See
APACHE2.0 for more
information on each specific licence.
Any submissions to this project (e.g. as Pull Requests) must be made available under these terms.
Raise an issue: https://github.com/rp-rs/rp2040-project-template/issues Chat to us on Matrix: #rp-rs:matrix.org