ESP32 Doctor — listing copy

English

Short description (card / search result)

Paste your serial log or error message and get a ranked fix list — cheapest test
first, each with a way to verify it worked. Covers upload failures, boot loops,
Guru Meditation panics, brownouts, PSRAM and partition problems, GPIO traps, and
WiFi.

Tagline

Three hours of debugging, in three minutes.

Full description

Embedded bugs waste hours because the symptom and the cause live in different
subsystems. A boot loop is usually a power problem. An upload failure is usually
a driver problem. A crash inside strlen() is usually a null pointer three
functions away. You end up searching for the wrong thing.

ESP32 Doctor takes whatever you have — a serial dump, a single error line, or
just "it keeps restarting" — and returns a diagnosis with a ranked list of fixes.
The ranking is by time to test, not by likelihood: a 25%-likely fix that is
one dropdown change beats a 60%-likely fix that needs a soldering iron. Every
step comes with a verification, so you change one thing at a time instead of
three.

What it handles

• Upload and flashing failures — Failed to connect to ESP32, Wrong boot mode detected, no COM port, timeouts, port-busy errors
• Boot loops and crashes — reset codes, Guru Meditation panics, task watchdog
  timeouts, stack canary trips, heap corruption
• Brownouts and power problems, including the ones that only appear once WiFi
  starts transmitting
• PSRAM not detected, OPI vs Quad mode, Sketch too big, partition schemes
• GPIO traps — strapping pins, flash-reserved pins, input-only pins with no
  internal pull-up, ADC2 dying under WiFi
• WiFi association failures and disconnect reason codes
• Arduino IDE, PlatformIO, and esptool configuration for specific modules

Supported targets

ESP32 (classic), ESP32-S3, ESP32-S2, ESP32-C3, and ESP8266, across Arduino IDE,
PlatformIO, and ESP-IDF projects.

What is included

• A deterministic log parser (Python, standard library only) that extracts reset
  causes, panic types, backtrace frames, and boot configuration — so nothing
  important gets skimmed past
• A per-module reference covering the quirks that produce symptoms no code
  review will explain: which suffix needs OPI PSRAM, which pins vanish when it
  does, which boards need the manual BOOT+RST dance every single upload
• Known-good board settings for the configurations that trip people up most

Answers in your language. Write in English, Traditional Chinese, Japanese, or
Spanish and the report comes back the same way, with error strings and menu paths
left in their original form so they stay searchable.

Example

Input

rst:0xc (SW_CPU_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
E (452) spiram: SPI RAM enabled but initialization failed. Bailing out.
Brownout detector was triggered
rst:0xc (SW_CPU_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)

Output (abridged)

Diagnosis — Two separate faults. The PSRAM initialisation failure points at
a mode mismatch (confidence: high — this exact message on an S3 is almost
always OPI vs Quad). The brownout is independent and points at the supply.
Three SW_CPU_RESET entries mean this is a boot loop, not a single crash.

1. Set PSRAM to OPI — ~10 seconds. Tools → PSRAM → OPI PSRAM. N16R8 and
N8R8 modules use octal PSRAM; Quad gives exactly this message.
✓ Verify: ESP.getPsramSize() returns a non-zero value.

2. Move to a rear USB port with a different cable — ~30 seconds. Brownouts
at WiFi transmit peaks are usually the cable or a hub.
✓ Verify: the brownout line stops appearing in the log.

3. …

Limitations

Hardware faults that need a multimeter or an oscilloscope cannot be diagnosed
from a log. This skill will tell you when you have reached that point and what to
measure, rather than guessing. It also cannot verify your specific board's
pinout — clone boards vary, and it will say which pins it is certain about.

繁體中文

簡短描述

貼上 serial log 或錯誤訊息，拿到一份依「最快能試」排序的排除清單，每一步都附驗證方式。涵蓋燒錄失敗、開機無限重啟、Guru Meditation 崩潰、電壓不足、PSRAM 與分割區設定、GPIO 陷阱與 WiFi 連線問題。

標語

三小時的除錯，變成三分鐘。

完整描述

韌體的問題之所以難，是因為症狀和成因通常不在同一層：無限重啟多半是供電，燒錄失敗多半是驅動，崩在 strlen() 裡多半是三層之外的 null pointer。你花的時間都在找錯的東西。

ESP32 Doctor 接受你手上任何形式的線索 —— 完整的 serial dump、一行錯誤訊息，或只是「它一直重開」—— 回給你一份診斷和排除清單。排序依據是測試成本而不是可能性：一個只要改下拉選單、25% 命中的方法，優先於一個要動烙鐵、60% 命中的方法。每一步都附上驗證方式，讓你一次只改一件事。

處理範圍

• 燒錄與上傳失敗 —— Failed to connect to ESP32、Wrong boot mode detected、
  抓不到 COM port、逾時、port 被佔用
• 開機重啟與崩潰 —— reset code、Guru Meditation panic、task watchdog、
  stack canary、heap 損毀
• 電壓不足（含只在 WiFi 開始發射後才出現的那種）
• PSRAM 抓不到、OPI 與 Quad 模式、Sketch too big、分割區配置
• GPIO 陷阱 —— strapping 腳位、被 flash 佔用的腳位、沒有內部上拉的
  input-only 腳位、WiFi 開啟後失效的 ADC2
• WiFi 連線失敗與 disconnect reason code
• Arduino IDE、PlatformIO、esptool 的模組對應設定

支援晶片：ESP32、ESP32-S3、ESP32-S2、ESP32-C3、ESP8266，涵蓋 Arduino IDE、
PlatformIO 與 ESP-IDF 專案。

內含

• log 解析器（Python，僅使用標準函式庫），自動抓出 reset 原因、panic 型別、
  backtrace 位址與開機設定，避免用眼睛掃過去漏掉關鍵行
• 各模組怪癖對照：哪個型號後綴必須選 OPI PSRAM、選了之後哪幾隻腳會消失、
  哪些板子每次上傳都得手動 BOOT+RST
• 最容易設錯的那幾組已知可用設定

用你的語言回答。 中文提問就中文回覆，錯誤訊息、腳位名稱與選單路徑保留原文，方便你直接拿去搜尋。

使用限制

需要三用電表或示波器才能確認的硬體故障，無法從 log 判斷。這個 Skill 會明確告訴你何時走到那一步、該量什麼，而不是硬猜。它也無法確認你手上板子的實際腳位 —— 清版差異很大，它會說明哪些腳位是它有把握的。