Guide · Espressif-IDE · preview · Windows

Debug ESP32 from Espressif-IDE.

Espressif-IDE can debug through coil-gdb in place of OpenOCD. This page covers installing Coil without VS Code, and the one field to change in the IDE's debug configuration.

01Install

Coil's Windows installer (Coil-Setup-<version>.exe, from Coil's releases) sets this up without VS Code. It puts Coil's programs in %LOCALAPPDATA%\Programs\Coil\bin (and on your PATH), and looks for Espressif-IDE, ESP-IDF, Espressif's installer (EIM), Git and ESP-IDF's USB drivers. It offers to install whatever is missing or older than the newest release: Espressif-IDE from Espressif's downloads, ESP-IDF through EIM (with Git through winget when it's missing), and the drivers (Windows asks for administrator rights). Each runs in its own window. It can also check once a week for newer releases of Coil, Espressif-IDE, EIM and ESP-IDF and show a notification (Start menu: Check for Coil updates checks now). To update, run the newest installer.

02The debug configuration

Espressif-IDE (4.2) can debug through coil-gdb instead of OpenOCD, with its own ESP-IDF GDB OpenOCD Debugging configuration and ESP-IDF's GDB. coil-gdb understands the OpenOCD command line the IDE passes, so the IDE starts and stops it like OpenOCD:

  1. In Run → Debug Configurations, duplicate the project's ESP-IDF GDB OpenOCD Debugging configuration and name the copy, say, "… (Coil)".
  2. Debugger tab: leave Start OpenOCD locally ticked and set Executable path to coil-gdb.exe (Browse…; with the installer it's %LOCALAPPDATA%\Programs\Coil\bin\coil-gdb.exe, with the VS Code extension it's in the extension's bin folder). Leave Config options as they are: coil-gdb takes the chip from the board file there (board/esp32s3-builtin.cfg) and uses the one connected board with that chip. With several, add --serial <MAC> (or OpenOCD's -c "adapter serial <MAC>"); for an ESP-Prog, Espressif's ESP-Prog board files already select it.
  3. Startup tab: nothing to change. Flash every time with application binaries puts OpenOCD's mon program_esp lines in the initialization commands, one per part of the build; coil-gdb flashes the whole build they come from once, with Coil's flasher (only changed 64 KB chunks are written), and skips the rest. Untick it to debug what's on the board without flashing. Enable ARM semihosting can stay; coil-gdb ignores it.
  4. Debug. The chip is reset and stops in app_main (the configuration's Set breakpoint at). Breakpoints, stepping, variables and both S3 cores work as with any GDB server. The IDE stops coil-gdb when the session ends.

03What the board runs

When a session doesn't flash, coil-gdb's console says what the board runs (the board runs my-app 1.2, built Nov 10 2026 12:35:57), at the first stop, so you can check it against your build, and warns when the board runs no app it can find for this build (another OTA slot's, or none). If app_main never comes, press Suspend to see it. Not flashing a build the IDE just made is the usual reason a session never stops in app_main.

04Starting coil-gdb yourself

To run coil-gdb yourself instead (coil-gdb --serial <MAC> in a terminal; it keeps running between sessions), untick Start OpenOCD locally and connect to Remote Target localhost, port 3333.

05Espressif-IDE and VS Code

A board can be held by one debugger at a time: end the Espressif-IDE session before debugging the same board from VS Code.