a modern, embedded debugging toolkit, written in Rust
The goal of this library is to provide a toolset to interact with a variety of embedded MCUs and debug probes.
Similar projects like OpenOCD, PyOCD, Segger Toolset, ST Tooling, etc. exist. They all implement the GDB protocol and their own protocol on top of it to enable GDB to communicate with the debug probe. Only Segger provides a closed source DLL which you can use for talking to the JLink.
This project gets rid of the GDB layer and provides a direct interface to the debug probe, which then enables other software to use its debug functionality.
The end goal of this project is to have a complete library toolset to enable other tools to communicate with embedded targets.
As of version 0.10.0 this library can
- connect to a DAPLink, STLink or JLink
- talk to ARM and Risc-V cores via SWD or JTAG
- read and write arbitrary memory of the target
- halt, run, step, breakpoint and much more the core
- download ELF, BIN and IHEX binaries using standard CMSIS-Pack flash algorithms to ARM cores
- provide debug information about the target state (stacktrace, stackframe, etc.)
To see what new functionality was added have a look at the CHANGELOG
If you think probe-rs makes your embedded journey more enjoyable or even earns you money, please consider supporting the project on Github Sponsors for better support and more features.
In addition to being a library, probe-rs also includes a suite of tools which can be used for flashing and debugging.
After installing the necessary prerequisites, the tools can be installed using
See the website for a more detailed guide.
cargo-flash utility can be used as a cargo subcommand to download a compiled Rust program onto a target device. It can also be used to download arbitrary ELF files that might come out of a C/C++ compiler. Have a look at cargo-flash for more information.
If you are looking for a more extended debugging experience, please have a look at cargo-embed which provides support for GDB, RTT, and config files.
We have implemented the Microsoft DAP protocol. This makes embedded debugging via probe-rs available in modern code editors implementing the standard, such as VSCode. Please see the website for more information.
Halting the attached chip
Reading from RAM
I need help!
How can I help?
Please have a look at the issues or open one if you feel that something is needed.
Any contributions are very welcome!
Also have a look at CONTRIBUTING.md.
Our company needs feature X and would pay for its development
Please reach out to @Yatekii
Building requires Rust and Cargo which can be installed using rustup. probe-rs also depends on libusb and libftdi. On linux these can be installed with your package manager:
# Ubuntu > sudo apt install -y libusb-1.0-0-dev libftdi1-dev libudev-dev libssl-dev # Fedora > sudo dnf install -y libusbx-devel libftdi-devel libudev-devel openssl-devel
On Windows you can use vcpkg:
# dynamic linking 64-bit > vcpkg install libftdi1:x64-windows libusb:x64-windows > set VCPKGRS_DYNAMIC=1 # static linking 64-bit > vcpkg install libftdi1:x64-windows-static-md libusb:x64-windows-static-md
See the vcpkg crate documentation for more information about configuring vcpkg with rust.
Writing new flash algorithms
If there is no CMSIS-Pack with a flash algorithm available, it is necessary to write a target definition and a flash algorithm by oneself.
You can use our template for writing an algorithm. Please follow the instructions in the
README.md in that repo.
In early stages of this library, we profited invaluably from the pyOCD code to understand how flashing works. Also it's always a good reference to cross check how ARM specific things work. So, a big thank you to the team behind pyOCD!
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 http://opensource.org/licenses/MIT) at your option.
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 dual licensed as above, without any additional terms or conditions.