Embassy RP Skeleton

The Embassy RP Skeleton repository is a project template intended as a starting point for developing your own firmware for the rp2040 based on the embassy asynchronous embedded development framework for Rust.

It includes all of the knurling-rs tooling (defmt, defmt-rtt, panic-probe, flip-link, probe-run) to enhance the embedded development process.

The default cargo runner is configured as probe-run, so you can build, flash and run your firmware with output from the device via a probe-rs compatible debug probe with the command:

$ cargo run

If you want to use a different runner with your debugger (e.g., cargo-embed, probe-rs-debugger, etc.) or if you aren't using a debugger and want the runner to flash the firmware via USB (e.g., elf2uf2-rs, picotool, etc.) then see: Alternative Runners

Table of Contents

1. Requirements
2. Setup
   1. System Setup
   2. Probe Setup
   3. Hardware Setup
3. Usage
4. Appendix

Requirements

• Ubuntu
• Raspberry Pi Pico
• Debug Probe (or another Raspberry Pi Pico)
• Rust Toolchain (cargo, rustup)

Setup

System Setup

1. Install Rust and cargo using rustup

# Install `rustup` for Rust Toolchain
$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Install Cortex-M Target Toolchain Support for Rust

# Install `thumbv6m-none-eabi` Target for `rp2040`
$ rustup target add thumbv6m-none-eabi

3. Install probe-run

# Install Linux Dependencies
$ sudo apt install -y libusb-1.0-0-dev libudev-dev

# Install `probe-run`
$ cargo install probe-run

# (Optional) Install `udev` Rules and Reload
$ sudo curl https://probe.rs/files/69-probe-rs.rules -o /etc/udev/rules.d/69-probe-rs.rules
$ sudo udevadm control --reload
$ sudo udevadm trigger

# (Optional) Add User to `plugdev` Group
$ sudo usermod -aG plugdev $USER

4. Install flip-link

# Install `flip-link`
$ $ cargo install flip-link

Probe Setup

You can use a Raspberry Pi Pico as a CMSIS-DAP debug probe.

1. Download CMSIS-DAP debugger firmware DapperMime for the Raspberry Pi Pico
2. Boot the Raspberry Pi Pico in "Bootloader Mode" by holding the BOOTSEL button while plugging it in
3. Open the mounted Raspberry Pi Pico storage device
4. Copy the raspberry_pi_pico-DapperMime.uf2 onto the Raspberry Pi Pico
5. Firmware will be flashed to the Raspberry Pi Pico and it will disconnect

Any probe-rs compatible debug probe can be used with probe-run. For a short list of alternative compatible debug probes see: Alternative Debug Probes.

Hardware Setup

Connecting the Raspberry Pi Pico Debug Probe

The diagram below shows the wiring loom between Raspberry Pi Pico A (left) and Raspberry Pi Pico B (right), configuring Raspberry Pi Pico A as a debug probe.

The connections shown in the diagram above are listed below.

Pico A GND -> Pico B GND
Pico A GP2 -> Pico B SWCLK
Pico A GP3 -> Pico B SWDIO
Pico A GP4/UART1 TX -> Pico B GP1/UART0 RX
Pico A GP5/UART1 RX -> Pico B GP0/UART0 TX
Pico A VSYS -> Pico B VSYS

For more information on connecting the two Raspberry Pi Picos, the wiring loom between them and its connections, see the section Appendix A > Wiring Loom in: Getting Started with Raspberry Pi Pico

Raspberry Pi Pico Dev Board

Alternatively, a custom printed Raspberry Pi Pico Dev Board can be used to enhance development, which includes:

• Debug Probe Host (Raspberry Pi Pico)
• Detachable Target (Raspberry Pi Pico)
• Serial Interface
• Reset Button
• Breakout Pins
• Selection of VSys or VBus Power Sources

The custom printed Raspberry Pi Pico Dev board is shown below:

For more information on printing your own custom Raspberry Pi Pico Dev Board, see: Raspberry Pi Pico Dev Board

Usage

Running

To run the firmware in debug mode:

$ cargo run

To run the firmware in release mode:

$ cargo run --release

Logging

To change the default defmt log level, see .cargo/config.toml:

[env]
DEFMT_LOG = "trace"

You can also set the log level inline:

$ DEFMT_LOG=debug cargo run
$ DEFMT_LOG=error cargo run --release

Appendix

Documentation

• Raspberry Pi Pico
• Rust
• Cargo
• Rustup
• Embassy
• Knurling-RS defmt
• Knurling-RS flip-link
• Knurling-RS probe-run
• Probe-RS cargo-embed
• Probe-RS probe-rs-debugger
• Raspberry Pi Pico elf2uf2
• Raspberry Pi Pico picotool
• CMSIS-DAP Firmware DapperMime

Resources

• Rust Embedded Book
• Awesome Embedded Rust
• Getting Started with Raspberry Pi Pico
• Ferrous Systems Embedded Training
• Ferrous Systems Embedded Teaching Material
• RP-RS App Template
• RP-RS Alternative Debug Probes
• RP-RS Alternative Runners
• Knurling-RS App Template
• Probe-RS Probe Setup
• Raspberry Pi Pico Dev Board