This is a fork of rp2040-project-template but setup for WSL2 on VSCode, using USB pass through for WSL, since many of the tools for both embedded Rust development and Pico debugging do not work on plain Windows.
To setup;
- Ensure you have setup 2 Picos with one in the picoprobe configuration
- Flash the (leftmost) Pico with the picoprobe firmware from the Raspberry Pi site.
- Ensure VSCode is installed.
- Ensure WSL2 is installed.
- With the WSL2 terminal open, install the toolchain:
- Install Rust:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh- It may be worth update existing Rust installations:
rustup update
- It may be worth update existing Rust installations:
- Install gdb-multiarch:
sudo apt install git gdb-multiarch - Install followinf dependancies:
sudo apt install automake autoconf build-essential texinfo libtool libftdi-dev libusb-1.0-0-dev - Install OpenOCD for Raspberry Pi;
- Clone the source:
git clone https://github.com/raspberrypi/openocd.git --branch picoprobe --depth=1 - Cd into the source folder:
cd openocd - Run:
./bootstrap - Then run:
./configure --disable-werror --enable-ftdi --enable-sysfsgpio --enable-bcm2835gpio --enable-picoprobe - Build the sources:
make -j4 - Now install:
sudo make install - Verify the installation:
openocd -v
- Clone the source:
- Install minicom:
sudo apt install minicom
- Install Rust:
- Install WSL2 USB passthrough;
- Once installed, in a PowerShell running as admin, attach the Picoprob bus id.
- Back in the WSL2 terminal;
- Get the Picoprobes vender and product id via:
usb-devices - Make/open a file in:
/etc/udev/rules.d/99-openocd.rules- Add the following lines
# Raspberry Pi Picoprobe ATTRS{idVendor}=="[vendor id from above]", ATTRS{idProduct}=="[product id from above]", MODE:="0666"
- Add the following lines
- Apply the udev rules to your running system:
sudo udevadm trigger - Install Rust build dependancies;
rustup target install thumbv6m-none-eabicargo install probe-runcargo install flip-link
- Clone and build this template;
- Clone the repo:
git clone https://github.com/jasonalexander-ja/PicoRustWSL.git - Cd into the repo:
cd PicoRustWSL - Open in code:
code . - In a WSL terminal, build the repo:
cargo build
- Clone the repo:
- In a new WSL terminal, run OpenOCD;
- The official documentation states to run
openocd -f interface/picoprobe.cfg -f target/rp2040.cfg -s tcl - I have found better luck using
openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -s tcl -c "adapter speed 5000" - I found that if OpenOCD cannot find the picoprobe, runnign as sudo tends to fix this:
sudo openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -s tcl -c "adapter speed 5000"
- The official documentation states to run
- In VSCode, you should now be able to
F5debug to upload code and set breakpoints.
- Get the Picoprobes vender and product id via:
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 (defmt, defmt-rtt, panic-probe, flip-link) to make development as easy as possible.
probe-rs is configured as the default runner, so yo
8000
u can start your program as easy as
cargo run --releaseIf you aren't using a debugger (or want to use other debugging configurations), 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.
-
(by default) A
probe-rsinstallation -
A
probe-rscompatible probeYou 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 probe-rs --features=cli --locked
# If you want to use elf2uf2-rs instead, do...
cargo install elf2uf2-rs --lockedIf 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.
For a debug build
cargo runFor a release build
cargo run --releaseIf 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 runor set the environment variable so that it applies to every cargo run call that follows:
export DEFMT_LOG=traceSetting the DEFMT_LOG level for the current session
for bash
export DEFMT_LOG=traceWindows 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 = tracecargo runIf 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 embedThis is basically a more configurable version ofprobe-rs run, our default runner. See thecargo-embedtool docs page for more information.Step 1 - Install
cargo-embed. This is part of theprobe-rstools:$ cargo install probe-rs --features=cli --lockedStep 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 probe-rs --features=cli --lockedStep 3 - Open this project in VSCode
Step 4 - Install
debugger for probe-rsvia the VSCode extensions menu (View > Extensions)Step 5 - Launch a debug session by choosing
Run>Start Debugging(or press F5) -
Loading a UF2 over USB
Step 1 - Installelf2uf2-rs:$ cargo install elf2uf2-rs --lockedStep 2 - Modify
.cargo/configto change the default runner[target.`cfg(all(target-arch = "arm", target_os = "none"))`] runner = "elf2uf2-rs -d"
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 bythumbv6m-none-eabi.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 start the specified 'runner'. As the 'runner' is theelf2uf2-rstool, it will build a UF2 file and copy it to your RP2040.$ cargo run --release -
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.elfextension, 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 infocan read it out, are not supported in Rust. An alternative is TBC.
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.9", features=["rt", "critical-section-impl", "rom-v2-intrinsics"] }
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:
- Fork the Project by clicking the 'Fork' button at the top of the page.
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Make some changes to the code or documentation.
- Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Feature Branch (
git push origin feature/AmazingFeature) - Create a New Pull Request
- An admin will review the Pull Request and discuss any changes that may be required.
- Once everyone is happy, the Pull Request can be merged by an admin, and your work is part of our project!
Contribution to this crate is organized under the terms of the Rust Code of Conduct, and the maintainer of this crate, the rp-rs team, promises to intervene to uphold that code of conduct.
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 MIT or 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