1. Quickstart
2. Requirements
3. Installation of development dependencies
4. Project Creation
5. Running
6. Alternative runners
7. Notes on using rp2040_boot2
8. Feature flags
9. Roadmap
10. Contributing
11. Code of conduct
12. License
13. Contact

This quickstart assumes that you've got a Raspberry Pi Pico (the first-generation version containing the RP2040 MCU) as well as a Raspberry Pi Debug Probe and will flash the Pico with probe-rs.

Note: you don't have to use this setup. It's just the most common and well-supported setup. See the rest of the README for instructions on setting up different hardware or software.

1. Connect your Raspberry Pi Pico and Debug Probe to your development host.

2. Set up cargo generate:

   cargo install cargo-generate
   

3. Start your project by copying this template:

   cargo generate rp-rs/rp2040-project-template
   

4. Install the cross-compilation toolchain:

   rustup target install thumbv6m-none-eabi
   

5. Install stack overflow protection:

   cargo install flip-link
   

6. Install the flashing tools:

   cargo install --locked probe-rs-tools
   

7. Flash the debug build of the blinky app to your Pico:

   cargo run
   

• 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.

• (by default) A probe-rs installation

• A probe-rs compatible probe

  You can use a second Pico as a CMSIS-DAP debug probe. Details on other supported debug probes can be found in debug_probes.md

rustup target install thumbv6m-none-eabi
cargo install flip-link
# Installs the probe-rs tools, including probe-rs run, our recommended default runner
cargo install --locked probe-rs-tools

If you want to use picotool instead, install a picotool binary for your system.

If you get the error binary `cargo-embed` already exists during installation of probe-rs, run cargo uninstall cargo-embed to uninstall your older version of cargo-embed before trying again.

Using cargo-generate

cargo generate --git https://github.com/rp-rs/rp2040-project-template

Follow the wizard 🪄 and enjoy your new project.

Downloading as a zip file or using GitHub's template support

Obtain a copy of the code, either by downloading this repository as a zip file or using GitHub's template feature, then apply the following:

• Remove debug_probes.md.
• Remove the cargo-generate directory.
• Remove/edit README.md.
• If using vscode update .vscode/launch.json; Else: remove this file.
• Edit Cargo.toml & adjust according to your project (especially its name).
• Edit .cargo/config.toml to select your favorite runner.

For a debug build

cargo run

For a release build

cargo run --release

If you do not specify a DEFMT_LOG level, it will be set to debug. That means println!(""), info!("") and debug!("") statements will be printed. If you wish to override this, you can change it in .cargo/config.toml

[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:

Linux/MacOS/unix

export DEFMT_LOG=trace

Setting the DEFMT_LOG level for the current session
for bash

export DEFMT_LOG=trace

Windows

Windows users can only override DEFMT_LOG through config.toml or by setting the environment variable as a separate step before calling cargo run

• cmd

set DEFMT_LOG=trace

• powershell

$Env:DEFMT_LOG = trace

cargo run

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:

• cargo embed This is basically a more configurable version of probe-rs run, our default runner. See the cargo-embed tool docs page for more information.

  Step 1 - Install cargo-embed. This is part of the probe-rs tools:

  cargo install --locked probe-rs-tools
  

  Step 2 - Update settings in Embed.toml

  • The defaults are to flash, reset, and start a defmt logging session You can find all the settings and their meanings in the probe-rs repo

  Step 3 - Use the command cargo embed, which will compile the code, flash the device and start running the configuration specified in Embed.toml

  cargo embed --release
  

• probe-rs-debugger Step 1 - Install Visual Studio Code from https://code.visualstudio.com/

  Step 2 - Install probe-rs

  cargo install --locked probe-rs-tools
  

  Step 3 - Open this project in VSCode

  Step 4 - Install debugger for probe-rs via the VSCode extensions menu (View > Extensions)

  Step 5 - Launch a debug session by choosing Run>Start Debugging (or press F5)

• Loading over USB with Picotool
  Step 1 - Install a picotool binary for your system.

  Step 2 - Modify .cargo/config to change the default runner

  [target.`cfg(all(target-arch = "arm", target_os = "none"))`]
  runner = "picotool load --update --verify --execute -t elf"
  

  The all-Arm wildcard 'cfg(all(target_arch = "arm", target_os = "none"))' is used by default in the template files, but may also be replaced by thumbv6m-none-eabi.

  Step 3 - Boot your RP2040 into "USB Bootloader mode", typically by rebooting whilst holding some kind of "Boot Select" button.

  Step 4 - Use cargo run, which will compile the code and start the specified 'runner'. As the 'runner' is picotool, it will use the PICOBOOT interface over USB to flash your RP2040.

  cargo run --release
  

The second-stage boot loader must be written to the .boot2 section. That is usually handled by the board support package (e.g.rp-pico). If you don't use one, you should initialize the boot loader manually. This can be done by adding the following to the beginning of main.rs:

use rp2040_boot2;
#[link_section = ".boot2"]
#[used]
pub static BOOT_LOADER: [u8; 256] = rp2040_boot2::BOOT_LOADER_W25Q080;

There are several feature flags in rp2040-hal. If you want to enable some of them, uncomment the rp2040-hal dependency in Cargo.toml and add the desired feature flags there. For example, to enable ROM functions for f64 math using the feature rom-v2-intrinsics:

rp2040-hal = { version="0.10", features=["rt", "critical-section-impl", "rom-v2-intrinsics"] }