Project Template for rp235x-hal

The main branch is for debugging rust programs on the rp2350 using the raspberry pi debugger using probe-rs. This allows for automatic flashing and line-by-line debugging in vscode.
Also allows for defmt to be used for logging.

'probe-rs' is the primary runner for this template. It allows for line-by-line debugging and automatic flashing without needing to hold down BOOTSEL.
This is the recommended way to run the code. picotool is also available as a runner so every time you want to flash, you will need to plug in the Pico 2 while holding down BOOTSEL, or some other means of getting there.

This means that once your ready to debug/flash, it's as easy as

cargo run

for debugging or

cargo run --release

for release builds

and if you use vscode, you can just press the debug button and you're ready to go!

Cargo Generate (Recommended)

To use this template, you can (should) use cargo generate.
This also renames all instances of rp2040-project-template to the name you provide, including the vscode workspace files. This makes it effortless to start a new project with this template.
To install cargo generate, run

cargo install cargo-generate

Then to generate a new project, run

cargo generate --git https://github.com/Navelwriter/rp2350-rust-template.git

if you want to use the picotool runner, run

cargo generate --git https://github.com/Navelwriter/rp2350-rust-template.git --branch picotool-reset

Then it's as easy as entering the name of your project and you're ready to go!

If you have the picoprobe, or "debugprobe" as it's called now, connected properly to the Pico 2, you can start debugging right away in vscode.

Features

• defmt logging

Note

If using picotool branch: To use defmt, you need to run the following command in the terminal during a debug session

nc localhost 8765 | defmt-print -e target/thumbv8m*/debug/yuh

This will allow you to see the logs in real-time.

Remember that defmt is only available in debug builds so you will need to have an active debug session, it defaults to halt on the main() entry so you can just enter the command right after pressing the debug button in vscode.

There is a log macro that you can use to log messages easily.

log!(info, "Hello, world!");
log!(warn, "This is a warning");
log!(error, "This is an error");

If you want to log a value, you can just use it the normal way in rust

let x = 5;
log!(info, "The value of x is {}", x);

If you run

cargo build --release

You will see that the log messages are not present in the binary. This is because defmt is only available in debug builds.

• flip-link This is a tool that allows you to detect stack overflows in your code. It's a great tool to have in your toolbelt. This just "works" after you you install it through cargo and is compiled. It will automatically detect stack overflows and halt the program. You can then use the backtrace to see where the overflow happened.

Branches:

There are two branches in this repo: Main and picotool-reset

• Main(HIGHLY RECOMMENDED)" This is identical functionality to rp-rs/rp2040-project-template, but uses the probe-rs runner instead of the picotool runner. This is the recommended way to run the code as it allows for line-by-line debugging and seamless flashing.
• picotool-reset: This is based on the Multicore FIFO example. This uses both cores, but instead of a blocking wait in core1, it simply polls core1 to see if it's done. This allows for the Pico 2 to act as a USB device that picotool can recognize, and with a port of usbd-picotool-reset, am able to reboot the pico into BOOTSEL mode using only the command line.

Requirements

• The standard Rust tooling (cargo, rustup) which you can install from https://rustup.rs/
• cargo-generate
• Toolchain support for the cortex-m33 processors in the rp2350 (thumbv8m.main-none-eabihf)
• Debug tool for the rp2350 (picoprobe) here
• Picotool(optional) and SDK for the rp2350. Both are easy to install through install script in Appendix B here
• flip-link - this allows you to detect stack-overflows on the first core, which is the only supported target for now.
• Raspberry Pi Pico 2
• openocd, install with sudo apt-get openocd
• VSCode with Cortex-Debugger extension (if picotool)

probe-rs specific requirements

• Follow installation instructions here
• Add udev rules for the debug probe (Linux only):

sudo curl -fsSL https://raw.githubusercontent.com/probe-rs/probe-rs/master/udev/99-probe-rs.rules | sudo tee /etc/udev/rules.d/99-probe-rs.rules
sudo udevadm control --reload
sudo udevadm trigger

• Raspberry Pi debug probe
• VSCode Extensions:
  • probe-rs
  • rust
  • USBIP Connect (optional, but recommended for WSL)

Installation

rustup target install thumbv8m.main-none-eabihf
cargo install flip-link
cargo install cargo-generate

cargo generate --git https://github.com/Navelwriter/rp2350-rust-template.git

For probe-rs branch

cargo generate --git https://github.com/Navelwriter/rp2350-rust-template.git --branch probe-rs

Running

Plug in the Pico 2 in BOOTSEL mode if you're using picotool.\

For line-by-line debugging in vscode, you can just press the debug button in vscode.
To build a debug build

cargo run

For a release build

cargo run --release