SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsesp32-debug

esp32-debug

Deployment & operations

View repository

Updated 10-15 21:48

About this skill

ESP32 Debug (crash and reset troubleshooting)

For debugging, first distinguish "software crash or hardware cause", then choose the method. The method matrix and commands are all from the baseline (high confidence);Wiring, frequency, and board-level parameters are all marked "subject to actual measurement with the board and probe device", no fabrication.

Determine Task Type

  1. Device randomly reboots/unexpectedly resets: first classify the reset cause (watchdog/panic/power loss) → crash-triage decision tree → Workflow B.
  2. Existing panic scene: interpret backtrace + extract coredump → Workflow A.
  3. Want breakpoint/single-step debugging: method matrix choose JTAG/OpenOCD or GDB stub → Workflow C + jtag-openocd。
  4. Suspect hardware (power supply/cold solder joint): after software methods are exhausted → refusal route fw-hil-testing(Hand-off table).

Prerequisites / Preflight

idf.py --version
idf.py monitor -p <PORT>   # 基线观察通道：先看住现场再谈别的
  1. Chip model: classic ESP32 has no built-in USB-Serial/JTAG, requires an external adapter (such as ESP-Prog) for JTAG; does not support SWD (high confidence in baseline). For built-in interface status of S-series chips, verify at runtime per official chip documentation.
  2. What you have on hand: serial cable (almost always present) / JTAG probe (ESP-Prog class) / whether the device is on hand and whether it can be reproduced.
  3. coredump destination configuration: flash (data/coredump partition) or UART—determines the extraction method (see method matrix).
  4. Whether the crash scene has already been overwritten by a subsequent reboot (if coredump is not configured, the evidence is gone).

Offline Baseline

  • ESP-IDF baseline = v6.1(as of walkthrough 2026-09-02, not automatically updated); debugging methods are cited from baseline §10 (official jtag-debugging and core_dump documentation, high confidence).
  • Dedicated documentation page URL for GDB stub: not captured in baseline (UNVERIFIED)—only state that "runtime GDB stub exists (CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME)", do not cite a specific documentation page.
  • Board-level wiring/JTAG frequency: official pages were not captured per board,subject to actual measurement with the board and probe device。

Contracts (device contracts)

  1. JTAG facts: OpenOCD is installed with IDF,openocd -f board/xxx.cfg; classic ESP32 uses JTAG,does not support SWD; supports flashing and GDB debugging via JTAG.
  2. Coredump facts: automatically saved on panic; destination flash (data/coredump partition) or UART; for analysis use idf.py coredump-info / coredump-debug。
  3. Do not fabricate board-level parameters: JTAG wiring pins, TCK frequency, on-board test points—cite official board documentation or actual measurement, choose one of the two.
  4. Reproduction experiments may repeatedly trigger crashes/reboots: for field devices, back up field logs and coredump first, then act.

Debugging method matrix (high confidence in baseline)

Method Prerequisite What you can get When to choose
idf.py monitor Serial cable Boot log, panic scene banner and backtrace, reset reason line Always the first step
Coredump (flash or UART) Partition/configuration in place Crash scene archive, post-mortem idf.py coredump-info/coredump-debug symbolic analysis Scene cannot be watched in real time, random crashes
JTAG/OpenOCD + GDB ESP-Prog class probe Breakpoints, single-step, real-time variables Reproduce stable logic issues
Runtime GDB stub CONFIG_ESP_SYSTEM_GDBSTUB_RUNTIME Serial GDB debugging without JTAG hardware A stopgap when no probe is available
VS Code official extension Extension environment Graphical interface for the above capabilities (build/flash/monitor/debug) Team-preferred IDE

For setup details, read jtag-openocd(wiring/frequency are marked "subject to actual measurement on the board and probe").

Crash handling flow

复现/等待崩溃
  -> idf.py monitor 观察现场：panic 回溯（哪些任务/哪层代码）
  -> 若已配置 coredump：提取存档
     -> idf.py coredump-info        # 概览：崩溃任务、寄存器、栈
     -> idf.py coredump-debug       # 进 GDB 做符号化调试
  -> 定位到代码位置 -> 修复 -> 回归验证

Reset cause classification and localization table → crash-triage: watchdog reset, panic, and power loss/supply—three categories, each with different criteria and evidence chains.

Capability Boundaries + Hand-off

User Intent Skill
Confirmed to be a power supply/power design/hardware issue hand-off：fw-hil-testing(on-target hardware-in-the-loop verification; this Skill does not draw hardware conclusions)
Firmware rollout after fix esp32-ota
Task/watchdog-related concurrency design issues esp32-freertos
Project configuration (coredump partition table, etc.) esp32-idf
Crashes caused by peripheral drivers esp32-peripherals

refusal boundary: this Skill does not output the conclusion "this is a power supply problem"—the software side can only provide "hardware suspicion evidence"; the final determination must be based on real-device measurement (fw-hil-testing).

Workflow A — panic scene handling

  1. idf.py monitor Capture the scene: record the panic banner and backtrace verbatim (archive first, then analyze).
  2. Interpret the backtrace: the task and call hierarchy where the crash occurred; backtrace addresses must match the current firmware version—backtraces from inconsistent firmware are untrustworthy.
  3. If coredump is configured → idf.py coredump-info overview → idf.py coredump-debug symbolize into GDB.
  4. After fixing, reproduce and verify along the original path; when reproduction conditions are unavailable, explicitly state "not reproduced/verified" and do not claim it is fixed.

Workflow B — random reboot troubleshooting (reset cause classification)

  1. Classify according to the crash-triage decision tree: first obtain reset cause evidence from the serial boot log, then determine the software/hardware direction.
  2. Software direction: panic → Workflow A; watchdog → check long-blocking tasks/interrupt-disabled duration (concurrency details → esp32-freertos）。
  3. Hardware suspicion (power loss/reset pin glitches): collect evidence (correlation between reboot timing and load, etc.) → hand-off fw-hil-testing actual measurement for final determination.
  4. For random issues: add logging instrumentation + enable coredump archiving, etc., to reproduce; do not make evidence-free guesses.

Workflow C — JTAG/OpenOCD setup

  1. Check the probe and target board (Contracts: classic ESP32 requires external JTAG; SWD is not supported).
  2. Wiring and frequency: consult official board documentation or measure (jtag-openocd, do not fabricate).
  3. Startup:openocd -f board/<目标板>.cfg(cfg names are subject to the actual list in the OpenOCD scripts directory installed with IDF).
  4. GDB connect for debugging; flashing via JTAG is also possible. When breakpoint behaves abnormally, suspect frequency/wiring first, then the toolchain.

Validation Gates

  1. panic case: backtrace localizes to a specific code line; after fixing, the same path no longer crashes on reproduction.
  2. coredump chain: artificially trigger a crash → coredump-info can read the crashing task and stack → coredump-debug can symbolize.
  3. Correct classification: a reboot with a known cause (e.g., an artificially triggered watchdog scenario) is correctly classified by the decision tree.
  4. JTAG chain: verify breakpoint hit, single-step, and variable inspection once each.
  5. No real device/no scene: all conclusions are marked Build Verification Only / Pending HIL。

Pitfalls

  1. Do notAttribute "random restarts" to software or hardware without classification—first go through the reset reason decision tree.
  2. Don'tassign SWD debugging tasks to the classic ESP32—it does not support SWD, use JTAG.
  3. Don'tmake up JTAG wiring/TCK frequency/board cfg names—check the official docs or measure it yourself (Pending HIL).
  4. Don'tuse an ELF of a different version from the target device to symbolize a coredump—the addresses won't match and all conclusions will be wrong.
  5. Don'tchase random crashes in a product without coredump configured—the evidence has long been overwritten by the next restart; configure it first, then wait for the crash to recur.
  6. Don'tjump straight to a "power supply problem" conclusion—after providing the suspect evidence, hand-off fw-hil-testing measurement to reach a definitive conclusion.
  7. Don'tcite a "dedicated documentation page" for the GDB stub—the baseline was not captured (UNVERIFIED), state only the Kconfig facts.

Official Sources

Privacy

coredumps and serial logs may contain network credentials, device identifiers, and user data: redact before sharing/archiving; this Skill does not collect or send diagnostic data externally; before sending a diagnostic package externally (e.g., reporting an issue to an upstream component), user confirmation is required and sensitive content must be cleaned up.