You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Marc Poulhiès a578d1b0dc WIP: very early ICDI hack 12 months ago
.github Make FTDI an opt-in feature 1 year ago
.vscode Add lot's of debugging logging 2 years ago
cli Use AsRef and AsMut to give access to the Probe from the 1 year ago
doc Add the probe-rs-cli-util to the release list 1 year ago
gdb-server Prepare release 0.9.0 1 year ago
probe-rs WIP: very early ICDI hack 12 months ago
probe-rs-cli-util Prepare release 0.9.0 1 year ago
probe-rs-t2rust Improve target gen 1 year ago
.gitignore First draft of the config structure for cmsis pack based flashing configuration (#86) 2 years ago
CHANGELOG.md Fix links in changelog to point to working compare views 1 year ago
CONTRIBUTING.md Create CONTRIBUTING.md 3 years ago
Cargo.toml Create helper library for CLI applications 1 year ago
LICENSE-APACHE Create LICENSE-APACHE 2 years ago
LICENSE-MIT Create LICENSE-MIT 2 years ago
README.md Add link to vcpkg crate documentation in readme 1 year ago
RESOURCES.md Fix size of erased sectors in progress bar 2 years ago

README.md

probe-rs

a modern, embedded debugging toolkit, written in Rust

crates.io documentation Actions Status chat

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.

Functionality

As of version 0.6.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

Downloading a file

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

GDB

We provide a GDB stub so you can use all your usual tools. You can find it here and you can also use it from within cargo-flash with the --gdb flag.

VSCode

We are implementing Microsoft DAP. This makes embedded debugging via probe-rs available in moden code editors implementing the standard, such as VSCode.

Usage Examples

Halting the attached chip

use probe_rs::Probe;

fn main() -> Result<(), probe_rs::Error> {
    // Get a list of all available debug probes.
    let probes = Probe::list_all();

    // Use the first probe found.
    let probe = probes[0].open()?;

    // Attach to a chip.
    let mut session = probe.attach("nrf52")?;

    // Select a core.
    let mut core = session.core(0)?;

    // Halt the attached core.
    core.halt(std::time::Duration::from_millis(300))?;

    Ok(())
}

Reading from RAM

use probe_rs::{MemoryInterface, Session};

fn main() -> Result<(), probe_rs::Error> {
    // Attach to a chip.
    let mut session = Session::auto_attach("nrf52")?;

    // Select a core.
    let mut core = session.core(0)?;

    // Read a block of 50 32 bit words.
    let mut buff = [0u32; 50];
    core.read_32(0x2000_0000, &mut buff)?;

    // Read a single 32 bit word.
    let word = core.read_word_32(0x2000_0000)?;

    // Writing is just as simple.
    let buff = [0u32; 50];
    core.write_32(0x2000_0000, &buff)?;

    // of course we can also write 8bit words.
    let buff = [0u8; 50];
    core.write_8(0x2000_0000, &buff)?;

    Ok(())
}

FAQ

I need help!

Don't hesitate to file an issue, ask questions on Matrix, or contact @Yatekii via e-mail.

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

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-dev libusb-1.0 libftdi1-dev

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.

Sponsors

Technokrat

Acknowledgements

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!

License

Licensed under either of

Contributing

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.