probe-rs

The probe-rs project provides several CLI tools for different workflows:

• probe-rs run: The preferred tool for most users. Flashes firmware, resets the target, and streams RTT/defmt output/panics. Works as a Cargo runner.
• cargo-flash: A cargo subcommand used to download a compiled Rust program or an arbitrary ELF file onto a target device without extra features.
• cargo-embed: Provides an extended debugging experience including support for GDB, RTT, and configuration files. Note: This tool is expected to be phased out in favor of probe-rs run.

On Linux, you can drive SWD directly from the host using the probe-rs-linux plugin via two backends. Use the --probe flag with a synthetic selector to specify the hardware interface.

• linuxgpiod: Bit-bangs SWD over the GPIO character-device interface (/dev/gpiochipN).
• linuxspidevswd: Emulates SWD over a spidev bus (requires tying MOSI and MISO together via a resistor).

Note: probe-rs list only exposes explicit /dev/spidev_swd* udev links for safety.

# bit-banged GPIO
probe-rs run --probe 0:0:gpiochip1,swclk=26,swdio=25,srst=38 ...

# spidev
probe-rs info --probe 0:0:/dev/spidev0.0

After cross-compiling and copying the binary to the Pi, you can run it directly or as a remote server. To run as a server, create a server config TOML file on the Pi and execute ./probe-rs serve. You can then connect from a host PC using the --host flag.

# On the Pi, run as a server:
./probe-rs serve

# From your PC, check connection:
probe-rs --host ws://pi-zero-w.local:3000 --token "token" info \
    --protocol swd --speed 1000 --probe "0:0:/dev/spidev0.0"

# From your PC, run a binary:
probe-rs --host ws://pi-zero-w.local:3000 --token "token" run hello_world.elf \
    --protocol swd --chip STM32F439ZITx --speed 1000 --log-file ./temp_probers_log

To use Linux-specific probe drivers (bit-banged SWD over GPIO or SWD over spidev) in your own Rust application, add probe-rs-linux to your Cargo.toml and call register_plugin() at the start of your program.

[dependencies]
probe-rs-linux = <current version>

fn main() {
    probe_rs_linux::register_plugin();

    // ... rest of the code
}

When attaching to an ARM target using probe-rs, the process follows a specific sequence depending on whether the user requests an attachment under reset.

Standard Attachment (No Reset):

1. Setup Debug Port.
2. Unlock debug device.
3. Start debug core.
4. Result: Attachment complete, but the core state is unknown.

Attachment Under Reset:

1. Assert hardware reset.
2. Setup Debug Port.
3. Unlock debug device.
4. Start debug core.
5. Set Reset Catch.
6. Deassert hardware reset.
7. Wait for the core to be halted.
8. Clear Reset Catch.
9. Result: Attachment complete with the core in a halted state.

Use cross to build probe-rs-tools with the remote feature for different Raspberry Pi architectures.

# pi1, pi-zero
cross build -p probe-rs-tools --target arm-unknown-linux-gnueabihf --release --features remote

# pi3, pi4, pi5
cross build -p probe-rs-tools --target aarch64-unknown-linux-gnu   --release --features remote

# copy the resulting binary to the Pi
scp target/arm-unknown-linux-gnueabihf/release/probe-rs pi-zero-w:~/

For regular testing of multiple boards, create a directory containing .toml configuration files for each board. Each .toml file must define the chip, the probe selector, and optionally a binary for flashing tests.

Required fields:

• chip: The target chip identifier.
• probe_selector: The unique identifier for the probe.

Optional fields:

• flash_test_binary: An ELF format binary used to test flashing. This must be specified as an absolute path.

# Test description for Microbit v1
chip = "nrf51822_xxAB"

probe_selector = "0d28:0204:9900360150494e4500492002000000600000000097969901"

# Optional binary (ELF format), used to test flashing. Needs to be specified as an absolute path.
flash_test_binary = "/absolute/path/to/gpio_hal_blinky"

The linuxspidevswd driver emulates SWD over an SPI bus by tying PICO and POCI together through a series resistor. To select the device, use a synthetic selector where the serial portion is the spidev path (e.g., /dev/spidev0.0). The VID:PID portion is ignored.

probe-rs info --probe 0:0:/dev/spidev0.0

To run tests for all boards defined in a specific directory, use the --dut-definitions flag with the path to your configuration folder.

cargo run -- --dut-definitions <dut_dir>

The linuxgpiod driver bit-bangs SWD over the Linux GPIO character-device interface (/dev/gpiochipN). Use a synthetic selector in the format 0:0:<gpiochip>,swclk=<offset>,swdio=<offset>[,srst=<offset>]. The <gpiochip> can be the name (e.g., gpiochip1), the path (/dev/gpiochip1), or just the index (1). The VID:PID portion is ignored.

probe-rs run --probe 0:0:gpiochip1,swclk=26,swdio=25,srst=38 \
    --chip STM32F439ZITx hello_world.elf

To enable metadata autodetect, you must ensure the probe-rs.x linker script is included. The recommended method is using a build.rs file. An older, non-recommended method involves configuring .cargo/config.toml.

// Recommended: via build.rs
println!("cargo:rustc-link-arg-bins=-Tprobe-rs.x");

# Older way (not recommended): via .cargo/config.toml
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
rustflags = [
  "-C", "link-arg=-Tprobe-rs.x",
]