testbench-debug

Testbench GDB Debugging

Remote GDB debugging of ESP32 devices through the testbench Pi. OpenOCD runs on the Pi, GDB connects from the container over TCP.

Architecture:

[Container]              [Pi (testbench)]           [ESP32]
  GDB ──── TCP :3333 ────── OpenOCD ──── USB JTAG ──────── CPU
                             (or)
                           OpenOCD ──── ESP-Prog ── JTAG pins

---

Three Approaches

Approach	Chips	Extra Hardware	Serial During Debug
USB JTAG (FR-024)	C3, S3 (native USB only)	None	Yes
Dual-USB (FR-025)	S3 (two USB connectors)	None	Yes + app USB
ESP-Prog (FR-026)	All ESP32 variants	ESP-Prog (~$15) + cable	Yes

---

Auto-Debug (Zero Config)

OpenOCD starts automatically when a device is plugged in or at boot. No API call needed.

How it works:

1. Device hotplugged → serial proxy starts → auto-detect tries OpenOCD configs
2. Chip identified via JTAG TAP ID → OpenOCD starts on the assigned GDB port
3. If USB JTAG fails (e.g. classic ESP32), falls back to ESP-Prog probe if available
4. GDB port reported in /api/devices response

Check debug status:

curl $TESTBENCH_URL/api/devices
# Look for: "debugging": true, "debug_chip": "esp32s3", "debug_gdb_port": 3335

Manual override (optional -- only needed to force-stop or force-start):

# Force stop (won't auto-restart until next hotplug)
curl -X POST $TESTBENCH_URL/api/debug/stop -d '{}'

# Force start with specific chip
curl -X POST $TESTBENCH_URL/api/debug/start \
  -d '{"chip": "esp32c3"}'

---

JTAG Reset (Preferred When Available)

When a debug session is active, the testbench automatically uses JTAG reset instead of DTR/RTS serial reset. This is transparent — the same /api/serial/reset API is used.

Why JTAG reset is better:

• No USB re-enumeration (device node stays stable)
• No flapping risk
• No 2-second boot delay
• Works even when serial port is unresponsive
• Can halt the CPU to stop boot loops