rp2040-project-template

The second-stage bootloader must be placed in the .boot2 section. While most Board Support Packages (BSPs) like rp-pico handle this, you can manually initialize it in your main.rs if you are not using a BSP:

use rp2040_boot2;

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

This guide assumes you are using a Raspberry Pi Pico and a Raspberry Pi Debug Probe with probe-rs.

1. Connect your Pico and Debug Probe to your host.
2. Install cargo-generate: cargo install cargo-generate.
3. Create project: cargo generate rp-rs/rp2040-project-template.
4. Install target: rustup target install thumbv6m-none-eabi.
5. Install stack protection: cargo install flip-link.
6. Install flashing tools: cargo install --locked probe-rs-tools.
7. Flash and run: cargo run.

# Step-by-step setup
cargo install cargo-generate
cargo generate rp-rs/rp2040-project-template
rustup target install thumbv6m-none-eabi
cargo install flip-link
cargo install --locked probe-rs-tools
cargo run

You can initialize a new project using cargo-generate or by manual download.

Using cargo-generate (Recommended)

Run the following command and follow the interactive wizard:

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

Manual Download/GitHub Template

If downloading as a ZIP or using GitHub's template feature, you must perform these cleanup steps:

• Remove debug_probes.md and the cargo-generate directory.
• Edit/remove README.md.
• Update .vscode/launch.json (if using VSCode) or remove it.
• Edit Cargo.toml to set your project name.
• Edit .cargo/config.toml to select your preferred runner.

Use cargo run for debug builds and cargo run --release for release builds.

By default, the DEFMT_LOG level is set to debug. You can override this to control logging verbosity (e.g., trace, info, off).

Overriding DEFMT_LOG

• Via .cargo/config.toml (Permanent):

  [env]
  DEFMT_LOG = "off"

• Inline (Linux/MacOS): DEFMT_LOG=trace cargo run
• Environment Variable (Linux/MacOS): export DEFMT_LOG=trace
• Environment Variable (Windows CMD): set DEFMT_LOG=trace
• Environment Variable (Windows PowerShell): $Env:DEFMT_LOG = trace

# Example: running with trace logging on Linux/MacOS
DEFMT_LOG=trace cargo run

To use the template's default development environment, install the following tools:

• Target: thumbv6m-none-eabi (for Cortex-M0+).
• Stack Overflow Protection: flip-link.
• Flashing/Debugging: probe-rs-tools (includes probe-rs run).

If you encounter the error binary 'cargo-embed' already exists during probe-rs-tools installation, uninstall your existing version first with cargo uninstall cargo-embed.

rustup target install thumbv6m-none-eabi
cargo install flip-link
cargo install --locked probe-rs-tools

To enable specific features in rp2040-hal (such as rom-v2-intrinsics for f64 math), uncomment the dependency in your Cargo.toml and add the desired flags:

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

The firmware entrypoint uses the #[entry] macro from the Board Support Package (BSP) to define the main execution loop. To initialize the hardware, you must take ownership of the pac::Peripherals and pac::CorePeripherals, initialize the Watchdog and Sio, and configure the system clocks using init_clocks_and_plls based on your board's external crystal frequency.

#[entry]
fn main() -> ! {
    let mut pac = pac::Peripherals::take().unwrap();
    let core = pac::CorePeripherals::take().unwrap();
    let mut watchdog = Watchdog::new(pac.WATCHDOG);
    let sio = Sio::new(pac.SIO);

    let external_xtal_freq_hz = 12_000_000u32;
    let clocks = init_clocks_and_plls(
        external_xtal_freq_hz,
        pac.XOSC,
        pac.CLOCKS,
        pac.PLL_SYS,
        pac.PLL_USB,
        &mut pac.RESETS,
        &mut watchdog,
    ).ok().unwrap();

    // ...
}

To target a different board, change the BSP alias in your main.rs file. Ensure the corresponding BSP crate is included in your Cargo.toml.

Example for switching from Raspberry Pi Pico to SparkFun Pro Micro RP2040:

// Use Raspberry Pi Pico
use rp_pico as bsp;

// OR use SparkFun Pro Micro RP2040
// use sparkfun_pro_micro_rp2040 as bsp;

The following hardware devices are compatible with this project for CMSIS-DAP debugging. Use these as alternatives if you do not wish to use a Raspberry Pi Pico as a probe.

- Raspberry Pi Pico (via debugprobe firmware)
- WeAct MiniF4
- HS-Probe
- ST-LINK v2 clone (requires dap42 firmware)
- LPC-Link2
- MCU-Link
- DAPLink

Access hardware pins by initializing the bsp::Pins struct. This requires the IO_BANK0, PADS_BANK0, and sio.gpio_bank0 peripherals, along with a mutable reference to pac.RESETS. Once initialized, you can access specific pins (like pins.led) and convert them into specific modes, such as a push-pull output using .into_push_pull_output().

let pins = bsp::Pins::new(
    pac.IO_BANK0,
    pac.PADS_BANK0,
    sio.gpio_bank0,
    &mut pac.RESETS,
);

let mut led_pin = pins.led.into_push_pull_output();