Debug

Control debugger operations for embedded development including flashing, GDB server management, memory access, and RTT logging.

Syntax

lager debug [OPTIONS] [NET_NAME] COMMAND [ARGS]...

Global Options

Option	Description
`--box TEXT`	Lagerbox name or IP address
`--help`	Show help message and exit

Commands

Command	Description
`gdbserver`	Start JLinkGDBServer for debugging
`disconnect`	Stop JLinkGDBServer
`flash`	Flash firmware to target
`reset`	Reset target device
`erase`	Erase all flash memory
`memrd`	Read memory from target
`status`	Show debug net status
`health`	Check debug service health

Command Reference

`gdbserver`

Start JLinkGDBServer for remote debugging. This is the primary command to establish a debug connection.

lager debug [NET_NAME] gdbserver [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP
--force / --no-force - Force new connection (default: reuse existing)
--halt / --no-halt - Halt device when connecting (default: no-halt)
--speed KHZ - SWD/JTAG speed in kHz (e.g., 100, 4000) or “adaptive”
--quiet - Suppress informational messages
--json - Output results in JSON format
--rtt - Automatically stream RTT logs after starting GDB server
--rtt-reset - Reset device then stream RTT (captures boot sequence)
--reset - Reset device after starting GDB server
--gdb-port PORT - GDB server port (default: 2331)

Examples:

# Start GDB server on default debug net
lager debug gdbserver --box my-lager-box

# Start GDB server on specific net with halt
lager debug debug1 gdbserver --box my-lager-box --halt

# Start GDB server and stream RTT logs
lager debug gdbserver --box my-lager-box --rtt

# Capture boot sequence via RTT
lager debug gdbserver --box my-lager-box --rtt-reset

# Use custom speed and port
lager debug gdbserver --box my-lager-box --speed 4000 --gdb-port 3333

Connecting with GDB:

# After starting gdbserver, connect with:
arm-none-eabi-gdb firmware.elf -ex 'target remote 100.91.127.26:2331'

`disconnect`

Stop JLinkGDBServer and free debug resources.

lager debug [NET_NAME] disconnect [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP
--keep-server - Keep JLinkGDBServer running for external connections

Examples:

# Stop GDB server completely
lager debug disconnect --box my-lager-box

# Disconnect but keep server running
lager debug disconnect --box my-lager-box --keep-server

`flash`

Flash firmware to target. Supports Intel HEX, ELF, and binary file formats.

lager debug [NET_NAME] flash [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP
--hex FILE - Path to Intel HEX file
--elf FILE - Path to ELF executable
--bin ADDRESS FILE - Path to binary file with load address
--verbose - Show detailed J-Link output
--force-reconnect - Force clean reconnect before flash
--erase - Erase all flash before flashing (ensures clean state)
--halt / --no-halt - Halt device after flashing (default: no-halt)

Examples:

# Flash Intel HEX file
lager debug flash --hex build/firmware.hex --box my-lager-box

# Flash ELF file
lager debug flash --elf build/firmware.elf --box my-lager-box

# Flash binary with base address
lager debug flash --bin 0x08000000 build/firmware.bin --box my-lager-box

# Flash with full erase first (recommended for RTT)
lager debug flash --hex build/firmware.hex --erase --box my-lager-box

# Flash and halt for debugging
lager debug flash --elf build/firmware.elf --halt --box my-lager-box

# Verbose output for troubleshooting
lager debug flash --hex build/firmware.hex --verbose --box my-lager-box

`reset`

Reset the target device.

lager debug [NET_NAME] reset [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP
--halt / --no-halt - Halt after reset (default: no-halt)
--force-reconnect - Force clean reconnect before reset

Examples:

# Reset and run
lager debug reset --box my-lager-box

# Reset and halt (for debugging)
lager debug reset --halt --box my-lager-box

# Force clean state before reset
lager debug reset --force-reconnect --box my-lager-box

`erase`

Erase all flash memory on target. This is a destructive operation.

lager debug [NET_NAME] erase [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP
--speed KHZ - SWD/JTAG speed in kHz (default: 4000)
--yes - Skip confirmation prompt
--quiet - Suppress warning messages
--json - Output results in JSON format
--halt / --no-halt - Halt after erase (default: no-halt)

Examples:

# Erase with confirmation prompt
lager debug erase --box my-lager-box

# Erase without confirmation
lager debug erase --box my-lager-box --yes

# Erase and halt afterward
lager debug erase --box my-lager-box --yes --halt

`memrd`

Read memory from the target device.

lager debug [NET_NAME] memrd START_ADDR LENGTH [OPTIONS]

Arguments:

START_ADDR - Starting memory address (e.g., 0x20000000)
LENGTH - Number of bytes to read

Options:

--box TEXT - Lagerbox name or IP
--json - Output results in JSON format
--halt / --no-halt - Halt device during read (default: no-halt)

Examples:

# Read 16 bytes of SRAM
lager debug memrd 0x20000000 16 --box my-lager-box

# Read with device halted (more reliable)
lager debug memrd 0x20000000 64 --halt --box my-lager-box

# Output as JSON
lager debug memrd 0x08000000 32 --json --box my-lager-box

Output:

0x20000000:	0x00	0x01	0x02	0x03	0x04	0x05	0x06	0x07
0x20000008:	0x08	0x09	0x0a	0x0b	0x0c	0x0d	0x0e	0x0f

`status`

Show debug net status and configuration information.

lager debug [NET_NAME] status [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP

Examples:

lager debug status --box my-lager-box
lager debug debug1 status --box my-lager-box

Output:

Debug Net Information:
  Name: debug1
  Device Type: STM32F407VG
  Architecture: ARM Cortex-M4
  Probe: J-Link
  Connected: True

`health`

Check debug service health and resource usage.

lager debug [NET_NAME] health [OPTIONS]

Options:

--box TEXT - Lagerbox name or IP
--verbose - Show detailed health information

Examples:

# Basic health check
lager debug health --box my-lager-box

# Detailed health information
lager debug health --box my-lager-box --verbose

Output (verbose):

Debug Service Health:
  Status: healthy
  Version: 1.2.0
  Uptime: 2.5 days (216000s)
  J-Link Running: True
  J-Link PID: 12345
  GDB Controllers Cached: 1
  Active Connections: 1

Listing Debug Nets

When invoked with only --box and no subcommand, lists all debug nets on the Lager Box:

lager debug --box my-lager-box

Output:

Name    Net Type  Instrument  Channel      Address
debug1  debug     J-Link      STM32F407VG  USB::001::002
debug2  debug     CMSIS-DAP   nRF52840     USB::001::003

RTT (Real-Time Transfer) Logging

RTT provides low-latency logging over the debug probe. Use the --rtt or --rtt-reset flags with gdbserver:

# Stream RTT after connecting
lager debug gdbserver --box my-lager-box --rtt

# Reset device and capture boot messages
lager debug gdbserver --box my-lager-box --rtt-reset

# Pipe to defmt-print for formatted output
lager debug gdbserver --box my-lager-box --rtt | defmt-print -e firmware.elf

Typical Workflows

Development Cycle

# Flash and debug
lager debug flash --elf build/app.elf --box my-lager-box
lager debug gdbserver --box my-lager-box --halt

# In another terminal, connect GDB
arm-none-eabi-gdb build/app.elf -ex 'target remote 100.91.127.26:2331'

RTT Debugging

# Flash with erase for clean RTT state
lager debug flash --elf build/app.elf --erase --box my-lager-box

# Start GDB server and stream RTT with boot capture
lager debug gdbserver --box my-lager-box --rtt-reset

Memory Inspection

# Halt device and read memory
lager debug gdbserver --box my-lager-box --halt
lager debug memrd 0x20000000 256 --box my-lager-box

Clean Up

# Stop debug session
lager debug disconnect --box my-lager-box

# Full chip erase before new project
lager debug erase --box my-lager-box --yes

Supported Debug Probes

Probe	Backend	Notes
J-Link	JLinkGDBServer	Full feature support, RTT
J-Link Plus	JLinkGDBServer	Full feature support, RTT
CMSIS-DAP	pyOCD	Open source, wide device support
ST-Link	pyOCD	STM32 devices
Flasher ARM	JLinkGDBServer	Production programming

Notes

Debug nets are created with lager nets create <name> debug <device_type> <address>
The system auto-connects when needed for commands like flash and reset
Use --erase before flashing for clean RTT initialization
RTT streaming requires the device to have RTT support in firmware
Memory reads are more reliable with --halt to pause the CPU
Use lager debug health --verbose to diagnose connection issues

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

Syntax

Global Options

Commands

Command Reference

`gdbserver`

`disconnect`

`flash`

`reset`

`erase`

`memrd`

`status`

`health`

Listing Debug Nets

RTT (Real-Time Transfer) Logging

Typical Workflows

Development Cycle

RTT Debugging

Memory Inspection

Clean Up

Supported Debug Probes

Notes

Lager Box Management

Configuration

Power & Simulation

Measurement

I/O & Communication

Development

Utilities

​Syntax

​Global Options

​Commands

​Command Reference

​gdbserver

​disconnect

​flash

​reset

​erase

​memrd

​status

​health

​Listing Debug Nets

​RTT (Real-Time Transfer) Logging

​Typical Workflows

​Development Cycle

​RTT Debugging

​Memory Inspection

​Clean Up

​Supported Debug Probes

​Notes

Syntax

Global Options

Commands

Command Reference

`gdbserver`

`disconnect`

`flash`

`reset`

`erase`

`memrd`

`status`

`health`

Listing Debug Nets

RTT (Real-Time Transfer) Logging

Typical Workflows

Development Cycle

RTT Debugging

Memory Inspection

Clean Up

Supported Debug Probes

Notes