Project template for rp2040-hal

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-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 (or want to use cargo-embed/probe-rs-debugger), check out alternative runners for other options

Requirements
Installation of development dependencies
Running
Alternative runners
Notes on using rp2040_boot2
Roadmap
Contributing
Code of conduct
License
Contact

Requirements

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. Details on other supported debug probes can be found in debug_probes.md

Installation of development dependencies

rustup target install thumbv6m-none-eabi
cargo install flip-link
# This is our suggested default 'runner'
cargo install probe-run --locked
# If you want to use elf2uf2-rs instead of probe-run, instead do...
cargo install elf2uf2-rs --locked
# If you want to use any of the probe-rs tools (probe-rs run, cargo-embed, probe-rs-debugger)
cargo install probe-rs --features=cli --locked

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.

Running

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

set DEFMT_LOG=trace

powershell

$Env:DEFMT_LOG = trace

cargo run

Alternative runners

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
Step 1 - Install cargo-embed. This is part of the probe-rs crate:
```
$ cargo install probe-rs --features=cli --locked
```
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 probe-rs --features=cli --locked
```
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)
probe-rs run Step 1 - Install probe-rs:
```
$ cargo install probe-rs --features=cli --locked
```
Step 2 - Make sure your .cargo/config contains the following
```
[target.thumbv6m-none-eabi]
runner = "probe-rs run --chip RP2040 --protocol swd"
```
Step 3 - Use cargo run, which will compile the code and start the specified 'runner'. As the 'runner' is cargo embed, it will flash the device and start running immediately
```
$ cargo run --release
```
Loading a UF2 over USB
Step 1 - Install elf2uf2-rs:
```
$ cargo install elf2uf2-rs --locked
```
Step 2 - Make sure your .cargo/config contains the following
```
[target.thumbv6m-none-eabi]
runner = "elf2uf2-rs -d"
```
The 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 start 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
```
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.

Notes on using rp2040_boot2

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;

Roadmap

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

Contributing

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!

Code of Conduct

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.

License

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.

Contact

Raise an issue: https://github.com/rp-rs/rp2040-project-template/issues Chat to us on Matrix: #rp-rs:matrix.org

pscott31/rkb