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 call 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`	Lager Box 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. If the hardware service already holds a shared session for this address, it skips the open and says so. A collision will 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)
`REACHABLE`	`*IDN?` returned (IDN string shown)
`REACHABLE (hw_service has an active 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: REACHABLE — IDN: KEITHLEY INSTRUMENTS,MODEL 2281S-20-6,4518305,01.08b. USB, the VISA session and *IDN? are all good. This does not exercise the instrument's function (e.g. whether a supply will actually enable its output).

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. Then it walks the debug stack outside-in: software → USB → probe-visible → gdbserver → target connect. That order means 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 alive, 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).

USB hub nets

A usb net is not a USB-TMC instrument, so lager diagnose sends it to the box’s /diagnose/usbhub check instead of the VISA probe. The check reports what the kernel sees, whether the vendor SDK finds the hub’s serial number, and whether the driver opens the hub. The verdicts, in order (first match wins):

Classification	Trigger
`UNCLEAR — this box does not serve /diagnose/usbhub`	the box is too old for the hub check. Update the box
`Could not reach the USB hub diagnose endpoint`	the request timed out or failed. This says nothing about the box version
`NOT ENUMERATED`	the kernel does not see the hub. Check its upstream cable and port power
`NOT SUPPORTED`	the SDK scan and the driver open are skipped for this hub vendor. This is not a fault
`BUSY`	something else is driving the hub. Run the check again when it is idle
`HUB WEDGED (electrical)`	the kernel sees the hub, but its vendor SDK does not. A restart of the box services does not help
`HUB CLAIMED`	the SDK sees the hub, but the open failed and another process holds it
`HUB WILL NOT OPEN`	the SDK sees the hub, and the open failed with no holder
`REACHABLE`	the hub opened and closed cleanly. This tests the path to the hub, not the DUT on a port
`UNCLEAR`	fallback. Review the section and run the check again

Backwards compatibility

Against a pre-0.20 box, each endpoint returns 404. The CLI then notes that the section is unavailable, because the box can 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

Security

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

USB hub nets

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

​USB hub nets

​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

USB hub nets

Backwards compatibility

See Also