Debug Probes

Flash, erase, reset, halt and read memory through a J-Link or OpenOCD probe

Drive a debug probe from a cargo test: connect, flash firmware, reset or halt the target, and read its memory.

Debug nets are the one net type that does not talk to the box’s API on port 9000. They reach the box’s debug service on port 8765 instead.

Handle

use lager::LagerBox;

let lager = LagerBox::from_env()?;
let dbg = lager.debug("debug1");

The net’s saved record is fetched once on first use and cached on the handle. The cache is dropped whenever an operation fails, so a re-saved net is picked up on the next attempt rather than needing a new handle.

Methods

Method	Description
name()	The net name this handle addresses
connect()	Connect with defaults, starting a GDB server
connect_with()	Connect with explicit options
disconnect()	Disconnect, optionally leaving the gdbserver running
reset()	Reset the target, optionally halting it at the reset vector
halt()	Stop the core where it is, without a reset (OpenOCD)
erase(), erase_with()	Erase the target’s flash
erase_range(), erase_range_with()	Erase only part of the flash
flash()	Flash a file, inferring its type from the extension
flash_with()	Flash a file with FlashOptions
flash_bin()	Flash a raw binary at an explicit base address
flash_bytes(), flash_bytes_with()	Flash bytes already in memory
read_memory()	Read target memory
read_memory_no_reset()	Read target memory without the reset and halt a J-Link DA1469x read does first
info(), info_probed()	Device, architecture, probe, serial, backend
status(), status_probed()	Whether a gdbserver is running, and whether the target is attached

RTT streaming lives on the same handle and is covered in RTT.

Types

ConnectOptions

pub struct ConnectOptions {
    pub speed: Option<String>,          // "4000" (kHz) or "adaptive"
    pub force: bool,                    // start a fresh backend even if one is running
    pub halt: bool,                     // reset, then halt the target on connect
    pub gdb: bool,                      // start a GDB server
    pub jlink_script: Option<Vec<u8>>,  // .JLinkScript contents for this connection
    pub openocd_config: Option<Vec<u8>>, // a complete OpenOCD .cfg for this connection
    pub gdb_port: Option<u16>,          // the four port overrides replace the
    pub swo_port: Option<u16>,          // probe slot's default ports; SWO and
    pub telnet_port: Option<u16>,       // telnet are J-Link only
    pub rtt_telnet_port: Option<u16>,
}

Default sets gdb: true and everything else off, so connect() starts a GDB server. Build the struct with ..Default::default(), so a field added later does not break your code.

jlink_script and openocd_config replace a script saved on the net, for this connection only. An OpenOCD config must be complete and must select the adapter driver.

FirmwareKind

pub enum FirmwareKind { Hex, Elf, Bin }

FlashOptions

pub struct FlashOptions {
    pub verbose: bool,                  // J-Link Commander alone, with full output
    pub jlink_script: Option<Vec<u8>>,  // contents of a .JLinkScript
    pub require_evidence: Option<bool>, // Some(false) accepts unusual J-Link wording
}

Pass the script you connected with. Without one, the box uses the net’s saved script, and failing that a temp file holding the script of whichever J-Link net connected most recently.

EraseOptions

pub struct EraseOptions {
    pub speed: Option<String>,          // J-Link interface speed
    pub transport: Option<Transport>,   // Transport::Swd or Transport::Jtag
    pub require_evidence: Option<bool>,
}

FlashReport and EraseReport

flash() and its variants return a FlashReport:

Field	Meaning
output	The backend’s output, one entry per line
backend	"jlink" or "openocd"
programmed	Some(true) from box 0.51.0 or later; None from an older box

erase() and erase_range() return an EraseReport:

Field	Meaning
output	The backend’s output
backend	"jlink" or "openocd"; None from a box before 0.50.0
erase_range	The range the box erased, or None for a full-chip erase

An EraseRange carries start, end (inclusive), length, text, and source. source is "request", "script" or "default".

Method Reference

connect() -> Result<DebugConnection>

Connect using ConnectOptions::default().

let conn = dbg.connect()?;
if let Some(gdb) = &conn.gdb_server {
    println!("gdb on {:?}, RTT telnet on {:?}", gdb.gdb_port, gdb.rtt_telnet_port);
}

Returns: DebugConnection, carrying the device, probe, serial, backend, and a GdbServer with the ports that were opened. On a J-Link these come back as gdb 2331, SWO 2332, telnet 2333 and RTT telnet 9090. tcl_port is OpenOCD-only and is None on a J-Link, just as swo_port is J-Link-only.

connect_with(opts: &ConnectOptions) -> Result<DebugConnection>

Connect with explicit options.

use lager::ConnectOptions;

dbg.connect_with(&ConnectOptions {
    speed: Some("4000".into()),
    halt: true,
    ..Default::default()
})?;

halt: true resets the target and then halts it. On a part that executes in place out of QSPI, that reset runs the bootloader again. To stop the core without a reset, use halt().

disconnect(keep_running: bool) -> Result<()>

Disconnect. Pass true to leave the gdbserver up for an external GDB client to attach to; pass false to tear it down.

reset(halt: bool) -> Result<DebugOutput>

Reset the target. halt: true leaves it stopped at the reset vector.

Returns: a DebugOutput with the probe’s output lines and the backend.

halt() -> Result<DebugOutput>

Stop the core where it is. halt() sends OpenOCD’s bare halt, so nRESET stays untouched. Use it on a part that executes in place out of QSPI, where a reset runs the bootloader again.

halt() requires box software 0.60.0 or later and an OpenOCD net:

• The crate reads the debug service’s features first. A box without halt fails with Error::UnsupportedByBox, and nothing reaches the probe.
• A J-Link net fails with Error::Box and HTTP 400. J-Link has no halt-in-place primitive, so connect with a halt-first .JLinkScript instead.
• A net with no running debugger fails with Error::Box and No debugger connection found.

erase() -> Result<EraseReport>

Erase the target’s flash: the whole chip, or the part family’s default range on parts where the box defines one (DA1469x, nRF5340). The report says which range the box erased.

On a J-Link probe, or on a DA1469x target, erase() drops the debugger connection. The next read_memory() fails with Error::Box and No debugger connection found. flash re-establishes on its own, so an erase-then-flash sequence works, but an erase-then-read does not — call connect() again first. On an OpenOCD probe with any other target, the OpenOCD daemon stays up after the erase.

erase_range(start: u64, size: u64) -> Result<EraseReport>

Erase only size bytes of flash, starting at start.

let report = dbg.erase_range(0x1600_0000, 0x2000)?;
println!("{:?}", report.erase_range.map(|r| r.text));

erase_range() requires box software 0.50.0 or later. An older box ignores the range and erases the whole chip. So the crate reads the debug service’s features first, and fails with Error::UnsupportedByBox before anything is erased. The box refuses a range outside what it can erase on the part with HTTP 400.

flash(firmware_path) -> Result<FlashReport>

Flash a file, inferring the type from its extension: .hex, .elf or .bin. An unrecognized extension is Error::Config.

A flash that programmed nothing fails with Error::FlashFailed, which carries the box’s verdict line and the backend’s output. Box software 0.51.0 and later reports this. An older box reports no verdict, and programmed is None.

A .bin is flashed at 0x08000000, the STM32 application base. On any other family that address is wrong, and the call still returns Ok. This was verified on an nRF5340: flash() of a .bin succeeded while flash at 0x0 stayed erased. This is a silent wrong result, not an error. Off STM32, use flash_bin() with the correct base address.

flash_bin(firmware_path, address: u32) -> Result<FlashReport>

Flash a raw binary at an explicit base address. This is the correct call for any target whose application does not start at 0x08000000.

dbg.flash_bin("target/app.bin", 0x0000_0000)?;   // nRF5340 application core

flash_bytes(contents: &[u8], kind: FirmwareKind, address: Option<u32>) -> Result<FlashReport>

Flash bytes you already hold, without writing them to a file first. address is used only for FirmwareKind::Bin and defaults to 0x08000000.

read_memory(address: u64, length: usize) -> Result<Vec<u8>>

Read length bytes from the target starting at address.

let vectors = dbg.read_memory(0x0000_0000, 8)?;
let initial_sp = u32::from_le_bytes(vectors[0..4].try_into().unwrap());

Requires a live connection: without one it fails with Error::Box and No debugger connection found. On a J-Link net with a DA1469x target, the box resets and halts the target before it reads. Other targets, and OpenOCD nets, do not reset for a read.

read_memory_no_reset(address: u64, length: usize) -> Result<Vec<u8>>

Read target memory without the reset and halt that read_memory() does first on a J-Link DA1469x target. A running target keeps running. A box that predates this option ignores it, and reads as read_memory() does.

info(), status(), info_probed() and status_probed()

info() reports the device, architecture, probe, serial and backend, plus whether a connection is live. status() reports the gdbserver: whether one is active, its pid, and the probe serial. Both work without connecting first.

let i = dbg.info()?;
println!("{:?} ({:?}) via {:?}", i.device, i.arch, i.backend);
// nRF5340_xxAA_APP (armv8-m.main) via jlink

Both carry two fields from box software 0.44.0 and later. An older box leaves them None.

Field	Meaning
gdbserver_running	Whether a gdbserver or daemon runs for this probe
target_attached	Whether the target answers through the probe

From info() and status(), target_attached is None unless the box already knows that the attach failed. info_probed() and status_probed() read the target to settle it, which takes about a second longer.

Examples

Flash and verify

use lager::LagerBox;

let lager = LagerBox::from_env()?;
let dbg = lager.debug("debug1");

dbg.connect()?;
dbg.erase()?;
dbg.flash_bin("target/app.bin", 0x0)?;

// erase() dropped the connection; flash_bin() brought it back, but be explicit.
dbg.connect()?;
let image = std::fs::read("target/app.bin").expect("firmware image");
let readback = dbg.read_memory(0x0, image.len().min(1024))?;
assert_eq!(&readback[..], &image[..readback.len()], "flash verify failed");

dbg.reset(false)?;
dbg.disconnect(false)?;

Stop a running target and inspect it

dbg.connect()?;
dbg.halt()?;   // no reset: the core stops where it is
let state = dbg.read_memory(0x2000_0000, 64)?;   // OpenOCD does not reset for a read

Leave a gdbserver up for an interactive session

dbg.connect()?;
let conn = dbg.info()?;
println!("attach with: target remote localhost:2331  ({:?})", conn.device);
dbg.disconnect(true)?;   // keep_running: the server survives

Supported Hardware

Probe	Backend	Notes
SEGGER J-Link and Flasher	jlink	SWO port available; no TCL port
ST-LINK v2 / v2-1 / v3	openocd	TCL port available; no SWO port
RP2040 Picoprobe	openocd
Atmel EDBG, DAPLink	openocd

Notes

• Timeout budgets are per operation and match the CLI:
  • connect 30 s
  • flash 180 s
  • erase 120 s
  • memory read 30 s
  • 10 s for reset, halt, info, status and disconnect
• Net resolution requires the debug role. A net that exists with another role gives net 'adc1' exists but is not a debug net. A name that does not exist gives debug net 'nosuch' not found on this box.
• The debug service does not use the same success envelope as the port-9000 API. A 200 is success; anything else is an error carrying the service’s message.
• Another operation can hold the probe longer than the box waits. The box then answers HTTP 503, and the crate returns Error::ProbeBusy. Retry when the other operation is done.
• A net configured with allow_destructive: false refuses erase() and flash() with HTTP 403, which the crate returns as Error::SafetyRefused. See Client and Box.
• The box-level calls debug_service_health(), debug_service_health_detailed() and debug_service_status() read the debug service’s version and features, its operating state and warnings, and every connection it tracks.
• For register access, memory writes and other GDB packets the typed API does not cover, use debug_tunnel(). The crate’s debug_tunnel example shows how.
• Async note: AsyncDebugNet provides everything here, including RTT.