Diagnose

lager diagnose <net> --box <box> [--type <role>] is a single-shot diagnosis for a misbehaving instrument net. It collapses the manual debug workflow (lsof, dmesg, bare pyvisa probes, hardware-service introspection) into one CLI call that returns an actionable classification — host-side, instrument-wedged, or healthy.

Introduced in lager 0.20.0 for USB-TMC (pyvisa) instruments. Extended in 0.28.3 to diagnose debug nets (SEGGER J-Link, and a basic OpenOCD/ST-Link path) — see Debug nets (J-Link) below.

Syntax

lager diagnose NET [OPTIONS]

Options

Option	Description
`--box BOX`	Lagerbox name or IP address (uses the default box if omitted)
`--type ROLE`	Net role. Defaults to `auto`, which looks up the net’s role from the box’s saved nets. Pass an explicit role (`battery`, `power-supply`, `scope`, `debug`, `usb`, `adc`, …) to override, or to diagnose a net that isn’t saved. A `debug` net routes to the J-Link path.

NET is the name of the net to diagnose (e.g. battery1, supply1).

Usage

# Diagnose a net, auto-detecting its role from saved nets
lager diagnose battery1 --box my-lager-box

# Override the role explicitly
lager diagnose battery1 --box my-lager-box --type battery

The command queries three box-side endpoints in parallel and prints a section for each, followed by a one-line classification with the next step.

Output sections

USB (host-side)

From GET /diagnose/usb on box port 9000. Reports:

enumerated — does the device show up on the host’s USB bus?
sysfs — kernel sysfs path (e.g. /sys/bus/usb/devices/1-4).
device — /dev/bus/usb/BBB/DDD path used by lsof/fuser.
usbtmc — whether the usbtmc kernel module is loaded (and therefore racing libusb for interface 0).
lsof — command(pid) list of processes holding the USB device file.
dmesg tail — last few USB / usbtmc kernel messages.

VISA (instrument-side)

From GET /diagnose/visa on box port 9000. Opens a fresh pyvisa session and queries *IDN? with a short timeout. Skips the open (with a clear note) if the hardware service already holds a shared session for this address — collisions would either hang or return garbage. Reports:

idn — the IDN string if the instrument answered.
elapsed — wall-clock ms.
error / error_class — classified as busy, nodev, timeout, or other.
skipped — set when the hardware service holds the address.

Dispatcher (hw_service in-process)

From GET /diagnose/dispatcher on hardware-service port 8080. Reports the in-process state for this address:

cached_session — whether the shared pyvisa session pool has it.
cached_drivers — driver instances cached against this address.
shared_pool — total pool size.

Classifications

The decision tree, in order (first match wins):

Classification	Trigger
`HOST-SIDE: usbtmc kernel module loaded`	the `usbtmc` kernel module is bound (run `lager update` to install the blacklist)
`HOST-SIDE: USB device claimed by multiple processes`	VISA `busy` and two or more holders in `lsof`
`HOST-SIDE: USB device busy`	VISA `busy` with a single holder
`TRANSIENT: device disappeared from USB`	VISA `nodev` (re-enumeration)
`INSTRUMENT WEDGED`	VISA `timeout` — enumerates and opens, but won’t answer `*IDN?`
`NOT ENUMERATED`	the device does not show up on USB (check power/cable)
`HEALTHY`	`*IDN?` returned (IDN string shown)
`HEALTHY (shared session)`	the open was skipped because hw_service holds an active session
`TRANSIENT: enumerated as USB-TMC but fresh open failed`	USB-TMC class but the fresh pyvisa open failed
`NOT USB-TMC`	a vendor-SDK instrument (LabJack/LJM, Picoscope, Acroname, …), not pyvisa
`UNCLEAR`	fallback — review the per-section output

Sample session

$ lager diagnose battery1 --box my-lager-box
lager diagnose — my-lager-box → battery1
  NetType: battery    address: USB0::0x05E6::0x2281::4518305::INSTR

== USB (host-side) ==
   enumerated:   True
   usbtmc kmod:  not loaded (good)
   lsof:         no holders

== VISA (instrument-side) ==
   idn:          KEITHLEY INSTRUMENTS,MODEL 2281S-20-6,4518305,01.08b
   elapsed:      429 ms

== Dispatcher (hw_service in-process) ==
   cached_session:  False
   shared_pool:     0 entry/entries

Classification: HEALTHY — IDN: KEITHLEY INSTRUMENTS,MODEL 2281S-20-6,4518305,01.08b

A wedged instrument surfaces clearly so you stop trying software-only recoveries:

Classification: INSTRUMENT WEDGED: device enumerates and accepts session open,
but won't respond to *IDN?. The instrument firmware is stuck — a mains-side
power-cycle of the instrument itself is required.

Vendor-SDK instruments (LabJack, Picoscope, Acroname) don’t go through pyvisa, so lager diagnose points you at the role-specific command instead of returning a misleading UNCLEAR.

Debug nets (J-Link)

A debug net isn’t USB-TMC, so the pyvisa *IDN? probe above can’t reach it. When the net’s role is debug (auto-detected, or forced with --type debug), lager diagnose takes a J-Link-aware path instead: it fetches the same host-side USB section plus a dedicated /diagnose/jlink endpoint and walks the debug stack outside-in — software → USB → probe-visible → gdbserver → target connect — so the most specific actionable fault wins.

lager diagnose swd1 --box lab-lager-box            # auto-detects the debug role
lager diagnose swd1 --box lab-lager-box --type debug

J-Link / debug probe section

In addition to the USB (host-side) section, a debug net prints a J-Link / debug probe section reporting:

backend — the probe backend (jlink, or an OpenOCD/ST-Link backend).
jlink software — whether the SEGGER J-Link tools are installed on the box.
probe enum — does the probe show up on the host’s USB bus?
probe visible — does JLinkExe actually enumerate the probe (with the emulator product/serial list)?
holders — command(pid) of any process holding the probe (usually a stale gdbserver).
gdbserver — whether a J-Link gdbserver is running, its PID, and whether its logfile looks healthy.
connect — the result of a target-connect probe: connect_ok, an error class, VTref (target reference voltage), and the detected core. The raw JLinkExe output is shown when the failure can’t be classified.

A SEGGER probe gets the full stack above. A non-J-Link OpenOCD/ST-Link probe reports a lighter openocd-basic section (backend, probe enumeration, and gdbserver state) — deep target diagnosis is J-Link-only for now.

Debug classifications

Classification	Trigger
`HEALTHY: J-Link connected to <device>`	target connect succeeded (core, and VTref when J-Link reports it)
`HEALTHY: J-Link gdbserver running`	a gdbserver is up, listening, and its log is clean (active debug session)
`J-LINK SOFTWARE MISSING on box`	the SEGGER J-Link tools aren’t installed (`lager update` installs them)
`PROBE NOT ON USB`	the probe isn’t enumerated — check cable, probe power, upstream hub port
`PROBE CLAIMED`	probe is on USB but `JLinkExe` can’t see it because another process holds it (usually a stale gdbserver — `lager debug <net> disconnect`)
`PROBE WEDGED`	probe is on USB but `JLinkExe` enumeration is empty — power-cycle the probe
`GDBSERVER WEDGED`	server process is up but its log shows a target-connection failure
`TARGET UNPOWERED`	probe is fine but VTref is too low — the target board has no power on the debug header (or VTref isn’t wired)
`TARGET LOCKED`	debug access is blocked by readout/IDCODE/AP protection — a mass-erase/unlock is required (e.g. `nrfjprog --recover`)
`DEVICE NAME`	`JLinkExe` rejected the configured device — fix the net’s device/MCU field
`NO TARGET COMMS`	probe + target power OK but SWD/JTAG connect failed — check SWDIO/SWCLK wiring, nRST pull-up, SWD-vs-JTAG, try a lower speed
`INCONCLUSIVE` / `UNCLEAR`	connect probe was skipped or returned an unrecognized class — review the section output and rerun

Sample debug session

$ lager diagnose swd1 --box lab-lager-box --type debug
lager diagnose — lab-lager-box → swd1
  NetType: debug    address: 50105878

== USB (host-side) ==
   enumerated:   True
   usbtmc kmod:  not loaded (good)
   lsof:         no holders

== J-Link / debug probe ==
   backend:        jlink
   jlink software: installed
   probe enum:     True
   probe visible:  True  (emus: J-Link/50105878)
   holders:        none
   gdbserver:      running=False pid=None log_ok=None
   connect:        ok=True class=ok VTref=3.300V core=Cortex-M4

Classification: HEALTHY: J-Link connected to NRF52840_XXAA (Cortex-M4, VTref=3.300V).

A locked target surfaces clearly so you reach for the right recovery:

Classification: TARGET LOCKED: debug access is blocked by readout/IDCODE/AP
protection. A mass-erase/unlock is required (e.g. `nrfjprog --recover` for nRF,
or the vendor unlock flow).

Backwards compatibility

Against a pre-0.20 box, each endpoint returns 404 and the CLI notes that the section is unavailable (the box may be on a lager < 0.20 image). The remaining sections still run — lager diagnose is useful against an older box, just less informative.

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Options

Usage

Output sections

USB (host-side)

VISA (instrument-side)

Dispatcher (hw_service in-process)

Classifications

Sample session

Debug nets (J-Link)

J-Link / debug probe section

Debug classifications

Sample debug session

Backwards compatibility

See Also

​Syntax

​Options

​Usage

​Output sections

​USB (host-side)

​VISA (instrument-side)

​Dispatcher (hw_service in-process)

​Classifications

​Sample session

​Debug nets (J-Link)

​J-Link / debug probe section

​Debug classifications

​Sample debug session

​Backwards compatibility

​See Also

Syntax

Options

Usage

Output sections

USB (host-side)

VISA (instrument-side)

Dispatcher (hw_service in-process)

Classifications

Sample session

Debug nets (J-Link)

J-Link / debug probe section

Debug classifications

Sample debug session

Backwards compatibility

See Also