rp-rs/probe-run

Runs embedded programs just like native ones

probe-run is a custom Cargo runner that transparently runs Rust firmware on a

probe-run

Runs embedded programs just like native ones

NOTE: Upstream probe-run 0.3.0 now supports the RP2040! This fork is no longer required - just cargo install probe-run.

probe-run is a custom Cargo runner that transparently runs Rust firmware on a remote device.

probe-run is powered by probe-rs and thus supports as many devices and probes as probe-rs does.

Features

  • Acts as a Cargo runner, integrating into cargo run.
  • Displays program output streamed from the device via RTT.
  • Exits the firmware and prints a stack backtrace on breakpoints.

Installation

To install probe-run, use cargo install probe-run.

On Linux, you might have to install libudev and libusb from your package manager before installing probe-run.

Setup

1. Set the Cargo runner

The recommend way to use probe-run is to set as the Cargo runner of your application.

Add these two lines to your Cargo configuration file (.cargo/config.toml) and set the particular --chip value for your target. In this case it is nRF52840_xxAA for the nRF52840:

To list all supported chips run probe-run --list-chips.

1.1 Env variable

To support multiple devices, or permit overriding default behavior, you may prefer to:

  1. set the ${PROBE_RUN_CHIP} environment variable, and
  2. set runner (or CARGO_TARGET_${TARGET_ARCH}_RUNNER) to probe-run:

1.2 Multiple probes

If you have several probes connected, you can specify which one to use by adding the --probe option to the runner or setting the ${PROBE_RUN_PROBE} environment variable with a value containing either ${VID}:${PID} or ${VID}:${PID}:${SERIAL}:

To list all connected probes, run probe-run --list-probes.

2. Enable debug info

Next check that debug info is enabled for all profiles. If you are using the cortex-m-quickstart template then this is already the case. If not check or add these lines to Cargo.toml.

3. Look out for old dependencies

The cortex-m dependency must be version 0.6.3 or newer. Older versions are not supported. Check your Cargo.lock for old versions. Run cargo update to update the cortex-m dependency if an older one appears in Cargo.lock.

4. Run

You are all set. You can now run your firmware using cargo run. For example,

would output

Stack backtraces

When the device raises a hard fault exception, indicating e.g. a panic or a stack overflow, probe-run will print a backtrace and exit with a non-zero exit code.

This backtrace follows the format of the std backtraces you get from std::panic! but includes <exception entry> lines to indicate where an exception/interrupt occurred.

If we look at the return code emitted by this cargo run, we'll see that it is non-0:

⚠️ NOTE when you run your application with probe-run, the HardFault handler (default or user-defined) will NOT be executed.

Backtrace options

--backtrace

The --backtrace flag is optional and can get passed the following values:

  • --backtrace=always - forced backtrace (if you'd like to see a backtrace at the end of successful program run)
  • --backtrace=never - suppresed backtrace
  • --backtrace=auto - default, shows a backtrace if the program panics or the stack overflows

Run it like this (example for a forced backtrace):

--backtrace-limit

The --backtrace-limit flag is optional and defaults to 50. It is possible to set any number.

--backtrace-limit=0 is accepted and means "no limit".

To show a shortened backtrace showing 5 frames, run:

Note: if --backtrace=never is set, setting --backtrace-limit has no effect.

Troubleshooting

probe-run --list-probes says "No devices were found."

Apart from a faulty connection between your computer and the target device, this could be caused by several things:

[Linux only] udev rules haven't been set

In order for probe-run to find the device you'd like to run your code on, your system needs permission to access the device as a non-root user.

In order to grant these permissions, you'll need to add a new set of udev rules.

To learn how to do this for the nRF52840 Development Kit, check out the installation instructions in our embedded training materials.

No external or on-board debugger present

To use probe-run you need a "probe" (also known as "debugger") that sits between your PC and the microcontroller.

Most development boards, especially the bigger ones, have a probe "on-board": If the product description of your board mentions something like a J-Link or ST-Link on-board debugger you're good to go. With these boards, all you need to do is connect your PC to the dev board using a USB cable you are all set to use probe-run!

If this is not the case for your board, check in the datasheet if it exposes exposes SWD or JTAG pins. If they are exposed, you can connect a "stand alone" probe device to the microcontroller and then connect the probe to your PC via USB. Some examples of stand alone probes are: the ST-Link and the J-Link.

Note that this may involve some soldering if your board does not come with a pre-attached header to plug your debugger into.

Error: RTT up channel 0 not found

This may instead present as Error: RTT control block not found in target memory.

Your code, or a library you're using (e.g. RTIC) might be putting your CPU to sleep when idle. You can verify that this is the problem by busy looping instead of sleeping. When using RTIC, this can be achieved by adding an idle handler to your app:

Assuming you'd like to still sleep in order to save power, you need to configure your microcontroller so that RTT can still be handled even when the CPU is sleeping. How to do this varies between microcontrollers.

On an STM32G0 running RTIC it can be done by amending your init function to set the dmaen bit on RCC.ahbenr. e.g.:

defmt version mismatch

end-user

Follow the instructions in the error message to resolve the mismatch.

developer

If you are hacking around with probe-run, you can disable the version check by setting the PROBE_RUN_IGNORE_VERSION environment variable to true or 1 at runtime.

Developer Information

running your locally modified probe-run

For easier copy-paste-ability, here's an example how to try out your local probe_run modifications.

running snapshot tests

To check whether your change has altered probe-run in unexpected ways, please run the snapshot tests in tests before opening a PR if at all possible.

You can do so by connecting a nrf52840 Development Kit and running

Support Us

probe-run is part of the Knurling project, Ferrous Systems' effort at improving tooling used to develop for embedded systems.

If you think that our work is useful, consider sponsoring it via GitHub Sponsors.

License

Licensed under either of

  • Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)

  • MIT license (LICENSE-MIT or #404)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

Information - Updated Feb 13, 2022

Stars: 3
Forks: 0
Issues: 0

Repositories & Extras

macOS/iOS Security framework for Rust

MIT license (LICENSE-MIT or

macOS/iOS Security framework for Rust

A fast and flexible CSV reader and writer for Rust, with support for Serde

Dual-licensed under MIT or the If you're new to Rust, the

A fast and flexible CSV reader and writer for Rust, with support for Serde

OpenGliderNetwork client for Rust based on actix

MIT license (LICENSE-MIT or

OpenGliderNetwork client for Rust based on actix

Threshold Secret Sharing

Efficient pure-Rust library for MIT license (LICENSE-MIT or

Threshold Secret Sharing

iCalendar in Rust

Please double check the MIT license (LICENSE-MIT or issues or comprehensive pull requests are welcome!

iCalendar in Rust

Rust library for low-level abstraction of MIPS32 processors

This project is licensed under the terms of the MIT license

Rust library for low-level abstraction of MIPS32 processors

A pure Rust library for reading/writing Windows

A pure Rust library for reading/writing License

A pure Rust library for reading/writing Windows

A Rust wrapper library for smealum's ctrulib

A Rust wrapper library for smealum's LICENSE-APACHE, COPYRIGHT for details

A Rust wrapper library for smealum's ctrulib

A 'Space Invader' clone made with rust and made for the terminal

Inspired by Apache License (Version 2

A 'Space Invader' clone made with rust and made for the terminal

oxidebpf is a permissive licensed Rust library for managing eBPF programs

The motivation behind oxidebpf is to create a permissive licensed Rust library

oxidebpf is a permissive licensed Rust library for managing eBPF programs

rust-actix-react-web-starter

A bare Rust web app that uses Diesel and License

rust-actix-react-web-starter
Facebook Instagram Twitter GitHub Dribbble
Privacy