Guide · VS Code · preview · Windows

Debug, flash and monitor ESP32 in VS Code.

Coil debugs, flashes and monitors ESP32 boards over JTAG, from VS Code, Espressif-IDE or the command line, without OpenOCD (and in VS Code without GDB). This page covers the VS Code extension; Espressif-IDE and the command-line tools have their own pages.

Supported today

ChipProbeDebugFlashMonitor
ESP32-C6built-in USB-JTAG✓✓ JTAG, serial✓
ESP32-C3built-in USB-JTAG✓✓ JTAG, serial✓
ESP32-S3built-in USB-JTAG✓ both cores✓ JTAG, serial✓
ESP32 (classic)ESP-Prog (FTDI)✓ both cores✓ JTAG, serial✓ via the ESP-Prog

ESP-IDF projects (v5 and v6). Windows first; macOS is next.

01Install

  1. ESP-IDF. Install it with Espressif's installer (EIM). If ESP-IDF is missing, Coil's Setup view offers Install ESP-IDF, which runs EIM for you (and installs Git and Python if they're missing). Coil finds every ESP-IDF that EIM registered and uses the one your project was built with.
  2. The extension. Install Coil for ESP32 from the VS Code Marketplace: in VS Code, Extensions (Ctrl+Shift+X), search for Coil for ESP32, Install. Or from a terminal:
code --install-extension bluscape.coil

VS Code keeps it up to date. It contains everything: coil-dap, coil-gdb, coil-flash, coil-monitor, coil-check, coil-config and coil-new. No OpenOCD, no GDB, no C/C++ extension. No Marketplace access? Each release also has the extension as coil-<version>.vsix: Extensions → … → Install from VSIX.

  1. Open your ESP-IDF project folder in VS Code. Coil starts when the folder has an sdkconfig, a main/CMakeLists.txt or a build. No project yet? See New project.

New project

Coil: New Project (Command Palette, or the Setup view's title bar) asks four things: the chip (a connected board's comes first), a template, the name, and the folder to create it in. Then it opens the project. The same from the command line:

coil-new hello_world --chip esp32c6 --template hello
coil-new --list            # chips and templates
TemplateWhat main/main.c does
helloLogs the chip and a counter every second: something to build, flash and step through
blankAn empty app_main
wifi-stationConnects to a Wi-Fi network and logs its address. The network name and password are settings (Wi-Fi station in the Settings view, or coil-config set APP_WIFI_SSID=...)

The project has the files idf.py create-project makes (CMakeLists.txt, main/CMakeLists.txt, main/main.c) and also:

  • sdkconfig.defaults naming the chip (CONFIG_IDF_TARGET), so the first build needs no idf.py set-target. sdkconfig is made by that first build.
  • .gitignore for the build folder.
  • .vscode/launch.json with Coil's configurations; the first, picked by F5, flashes only when the code changed ("flash": "ifDifferent"). --no-vscode leaves it out.

Then build (Coil: Build), and press F5.

You can keep Espressif's ESP-IDF extension installed alongside Coil. Coil doesn't use it.

02First run: the Setup view

When the extension starts, it checks everything debugging, Flash and Monitor need, and only speaks up when something is wrong. The Setup view (Coil in the activity bar) lists each check:

  • Coil's tools: found, and which copy.
  • Project: an ESP-IDF project? Built? For a chip Coil supports?
  • ESP-IDF: found through EIM, and which version.
  • Debugger: coil-dap (default) or the GDB path.
  • Code completion: clangd set up for this build?
  • Each connected board: the USB-JTAG driver, whether another program holds the board (and which: OpenOCD, a GDB server, probe-rs…), whether it answers, and whether its chip matches the project.
  • ESP-Prog: FTDI's driver and D2XX library, whether the JTAG channel is free, and whether your board.h leaves the JTAG pins free.

Each problem has its fix one click away: Build, Install ESP-IDF, Install the USB-JTAG driver, Stop the program holding the board (after asking), Use Coil's debugger, Set Up Code Completion. Run Coil: Check Setup to check again at any time.

03Boards

  • Boards view: every connected board, with its chip, COM port and state (selected, debugging). Each row has Debug, Flash and Monitor buttons; expand it for the serial number, port, status and whether the project was built for that chip. Click a row to select the board.
  • Plug detection: while the view is open, boards you plug in or out appear within about a second.
  • Status bar: the selected board. Click it to pick another. With several boards connected, Coil picks the only one that matches the project's chip, and asks otherwise.

04Build, Flash and Monitor

Run them from the Command Palette (Coil: Build, Coil: Flash, Coil: Monitor, Coil: Build, Flash and Monitor), from the Boards view, or from its title bar. Ctrl+Shift+B builds (in an ESP-IDF project, in place of VS Code's Run Build Task; rebind it in Keyboard Shortcuts if you prefer another key).

Build

Once the project has been built (configured) once, Build runs ninja on the build directly: no ESP-IDF environment to load, 0.7 s when nothing changed. When CMake must re-run first (see After a CMake change below), only that step runs inside the ESP-IDF environment. The first build, and any build where this fails, runs idf.py build in a terminal, inside the ESP-IDF environment EIM registered for the project. Either way, there's no need to start VS Code from an ESP-IDF shell.

Faster builds (Windows): ESP-IDF regenerates its linker script with ldgen after every edit, which takes 13–31 s on Windows. Coil puts a cache in front of it (same output, about 1 s), so a one-line edit builds in about 2 s. Turn it off with coil.fastLinkerScript.

Source files

A component builds the files its main/CMakeLists.txt names in SRCS. A new .c file that isn't named there is left out, and the build fails at the link with undefined reference.

  • Coil: New Source File (Command Palette, or right-click a folder in the Explorer) creates the .c (.cpp and .S work too), and its header if you want one, and adds it to SRCS.
  • Build checks first: a source file the component doesn't name gets a warning with Add to CMakeLists.txt.
  • From the command line: coil-new add blink --header (a bare name goes in main/), and coil-new unlisted lists files the build leaves out.

A component that builds whole folders (SRC_DIRS) needs no list; Coil adds a new subfolder to SRC_DIRS and makes the next build re-run CMake so it finds the file.

Flash

On the ESP32-C6, the ESP32-C3, the ESP32-S3 and the classic ESP32 (through an ESP-Prog), Flash uses Coil's own flasher over JTAG:

  1. ninja builds the configured build directly (no ESP-IDF environment needed; 0.7 s when nothing changed).
  2. coil-flash writes what the build lists: bootloader, partition table, OTA data and app. It compares 64 KB chunks by MD5 on the chip and skips unchanged ones, sends the rest compressed, and verifies.

An app edit flashes in about 1.3 s on the C6 (idf.py flash: 4.6–6.5 s). On the S3 an edit writes only the changed chunks; a full 1.4 MB write takes about 11 s. Blank or erased chips work too.

After a CMake change (a CMakeLists.txt or sdkconfig changed, or the build was reconfigured elsewhere), CMake must run again before ninja can build. Coil notices (a 0.1 s check), runs just that step inside the ESP-IDF environment, and carries on with ninja (and, for Flash, coil-flash). The re-run itself is ESP-IDF's configure, 25–40 s, the same as with idf.py. If anything on this path fails, Flash builds again with idf.py build and flashes that.

Flash while debugging: if a Coil debug session holds the board, Flash ends it, flashes, and starts it again, stopped in app_main with the new code (about 2.7 s on the C6).

On other chips, Flash runs idf.py flash on the board's serial port.

Monitor

Coil's own serial monitor (coil-monitor), in a terminal, one per port:

  • Finds the board's serial port from its serial number.
  • Doesn't reset the chip when it opens.
  • Reconnects after resets and flashing.
  • Decodes panics into function at file:line lines you can click, using the project's ELF.
  • Typing goes to the board.

Monitor and the debugger work side by side: a reset during debugging is handled, and the session carries on.

Settings (sdkconfig)

Coil replaces menuconfig in VS Code, on coil-config (on the command line). Every change is checked first, and ESP-IDF's own Kconfig library writes sdkconfig, so the file is exactly what menuconfig would write.

  • Coil: Settings (sdkconfig) opens the Settings view:
    • Sections by task: Logging, Console and monitor, Flash and partitions, Memory and PSRAM, CPU and power, FreeRTOS, Watchdogs and crashes, Debugging and build, Wi-Fi, Bluetooth, Network, Security. Each has the options that matter most, with a short note on each.
    • Presets: Debug, Release (small), Release (fast) and Low power. Coil lists what a preset would change before applying it.
    • Changed by you: only the settings that differ from the default, with Reset on each.
    • All settings: every option in its menu, as menuconfig has them, hidden ones too if you ask.
    • Search over every option's title, CONFIG_ name and help, hidden ones included.
    • A hidden option is greyed out with what it needs ("needs CONFIG_ESP_INT_WDT (now n)") and, where one setting would show it, a button to turn that on. Security options that burn eFuses ask first.
    • After a change, Build applies it and Undo puts the previous sdkconfig back.
  • Coil: Change Setting… does the same from the Command Palette: pick an option (by title, CONFIG_ name or menu), then its value (y/n, a choice's options, or a number checked against its range).
  • ESP-IDF Config, in Coil's sidebar, lists the settings changed from the default (your sdkconfig, or Release's with Release selected), with Change and Reset on each row.
  • Hovers: hover a CONFIG_ name in sdkconfig, a defaults file or C/C++ code for its value, where it comes from, what it needs, its range and help, with Change and Reset links.
  • Checks: sdkconfig and sdkconfig.defaults* files get warnings where a line has no effect: an unknown or misspelt option, a value out of range, a hidden option and what it needs, an option another one selects, or a value sdkconfig overrides.

Debug and Release

The status bar shows the build profile, Debug or Release; click it (or Coil: Select Build Profile) to switch. Build, Flash, F5, Monitor and the Settings view follow it. Next to it are buttons for Settings, Full Clean, Build, Flash, Monitor, Debug, and Build, Flash and Monitor (on the selected board). Choose which ones show by ticking them in the Coil view's Status Bar Buttons (or the coil.statusBarButtons setting); Clean is there too, unticked. Espressif's ESP-IDF extension has a similar row that runs ESP-IDF's own tools (idf.py, OpenOCD); to hide it, right-click the status bar and untick its entries.

DebugRelease
Build folderbuild (coil.buildDir)build-release (coil.releaseBuildDir)
Settingsthe project's sdkconfigits own build-release/sdkconfig, made from sdkconfig.defaults and then sdkconfig.release
What it's forstepping through code: optimized for debugging, assertions and logs onshipping: optimized for size, assertions silent, warnings-only logging (what sdkconfig.release says)
  • Each profile keeps its own build, so switching doesn't rebuild everything, and changing a setting with Release selected changes only the Release sdkconfig.
  • sdkconfig.release comes with new projects. In an older project, create it (the same CONFIG_...= lines as sdkconfig.defaults); without it Release is built from sdkconfig.defaults alone. Its lines apply when build-release/sdkconfig is first made: to apply a change, delete that file and build, or change the setting in the Settings view.
  • Debugging a Release build works (F5 with Release selected), but the optimizer leaves less to see: variables are often "optimized out" and steps jump around.
  • Code completion keeps using the Debug build whatever the profile.
  • Coil: Release Image builds Release and merges bootloader, partition table and app into one file to write at address 0x0, named after the project, version and chip (blinky-v1.2-esp32c6.bin, in build-release). The version is ESP-IDF's: git describe, or PROJECT_VER; one ending in dirty means uncommitted changes. The selected profile is put back afterwards.
  • From the command line (what Coil runs):
idf.py -B build-release -D SDKCONFIG=build-release/sdkconfig -D "SDKCONFIG_DEFAULTS=sdkconfig.defaults;sdkconfig.release" build
idf.py -B build-release -D SDKCONFIG=build-release/sdkconfig merge-bin -o blinky-release.bin
coil-config --profile release get COMPILER_OPTIMIZATION_SIZE

Production security (Secure Boot, flash encryption) is in the Settings view's Security section. Turning those on burns eFuses on the chip and can't be undone; Coil asks first.

05Debugging

Start debugging with Run → Start Debugging (the F5 key), the green ▶ in Run and Debug, Coil: Debug, or a board's Debug button. No launch.json is needed; with one, Coil: Debug and a board's Debug button use its first Coil configuration. Coil resets the chip and stops in app_main, in about a second.

  • Breakpoints in source; hardware breakpoints for code in flash (8 on the C3, 4 on the C6, 2 on the S3). On the ESP32-S3, more go into flash: from the third on, Coil writes a break instruction into the app's code when the chip resets (at launch, or Restart), about 1.5 s for the first ones. A breakpoint added during a session shows "set at the next restart" until then. When the session ends, Coil writes the app back as it was (in the background, so stopping is instant) and the app restarts; if that is cut off (the board unplugged), the next debug session finishes it, or flash the build. Only the app partition's chunks that hold a breakpoint are rewritten (64 KB each, plus the one with the image's checksum and hash, which Coil keeps valid). Not with Secure Boot or flash encryption.
  • Stepping: over, into and out, including into and over inlined functions.
  • Call stack for every thread; on the S3 and ESP32 both cores are threads (core 1 appears once the app starts it).
  • Variables: Locals, Globals and Registers for every frame: structs, unions, arrays, bitfields, enums, pointers, strings and function pointers, printed as GDB prints them.
  • Watch, hover and the Debug Console: expressions, including casts and struct members.
  • Changing values in memory and in registers.
  • Data breakpoints ("Break on value change"): stop when a variable is written, read or accessed.
  • Memory view: VS Code's hex view of any address.
  • Restart resets the chip and stops in app_main again (0.6–0.8 s). Stop lets the firmware run on.

Checking the firmware: before debugging, Coil checks that the board runs the build you're debugging (the ELF's SHA-256, which ESP-IDF stores in the app). If another app is running, breakpoints would never stop; Coil says what the board runs and offers Flash.

The GDB path: set coil.debugAdapter to gdb to debug through ESP-IDF's GDB and Microsoft's C/C++ extension instead, with coil-gdb as the server. It's slower (about 11 s to start against 1 s) and needs the C/C++ extension.

06Launch configurations

Debugging needs no launch.json. To keep settings per project, add configurations to .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    { "type": "coil", "request": "launch", "name": "Coil: debug ESP32" },
    { "type": "coil", "request": "launch", "name": "Coil: debug (flash if changed)", "flash": "ifDifferent" },
    { "type": "coil", "request": "launch", "name": "Coil: flash and debug", "flash": true },
    { "type": "coil", "request": "launch", "name": "Coil: attach", "reset": false }
  ]
}

Picking one: open Run and Debug (Ctrl+Shift+D) and choose it in the dropdown next to the green ▶, or run Debug: Select and Start Debugging. Start Debugging (F5) then uses that configuration until you pick another. Coil: Debug and a board's Debug button always use the first Coil configuration in the file (on the board you clicked).

AttributeDefaultWhat it does
serialselected boardThe board's serial number (its MAC). With probe: "esp-prog", the ESP-Prog's USB serial number
probeUSB-JTAGesp-prog: debug through an ESP-Prog
khz10000With an ESP-Prog: the JTAG clock
buildDirbuildBuild folder (or the coil.buildDir setting)
resettruefalse: attach to the running firmware and halt where it is
stopAtapp_mainFunction to stop in after the reset; empty to run
flashfalsetrue: build and flash first, as Coil: Flash does. "ifDifferent": build, then flash only if the board doesn't run this build
adaptercoil.debugAdaptercoil (coil-dap) or gdb
gdbPathESP-IDF's GDBWith adapter: gdb: another GDB

Flash only when the code changed: "flash": "ifDifferent" builds, and when coil-dap attaches it compares the build with what the board runs (the ELF's SHA-256, which ESP-IDF stores in the app). If they match, the session starts without flashing; if not, it flashes over JTAG and starts. Restart then only resets. With adapter: "gdb" it always flashes, as true does.

When to use "flash": true: when the board might not be running your build, especially firmware with OTA updates (see Troubleshooting). It flashes and starts debugging straight away.

07ESP-Prog and the classic ESP32

Wire the ESP-Prog's JTAG header to the board and plug it in. The Boards view shows the chip behind it (ESP32 · ESP-Prog · COM11); Debug, Flash and Monitor work as for a USB-JTAG board.

  • Drivers: the ones Windows installs by itself (FTDI's own). Coil reaches the JTAG channel through FTDI's D2XX library and never changes drivers.
  • Channels: Debug and Flash use channel A (JTAG); Monitor uses channel B (the board's UART).
  • JTAG pins: GPIO12–15 on the ESP32. Your firmware must leave them alone; the Setup view checks your board.h.
  • Busy channel: OpenOCD or a serial terminal on channel A's COM port blocks it; the Setup view names the program.

08Code completion (clangd)

Coil: Set Up Code Completion (or the Setup view's row, or the one-time offer) sets up Espressif's clangd for your build: compiler flags tested against clangd, the C library's headers, .clangd, and the C/C++ extension's IntelliSense turned off for the project. It needs the clangd extension, which the Setup view offers to install. When the setup goes out of date (another ESP-IDF, target or build folder), the Setup view says so and fixes it in one click.

09Pin configurator and pin checker

In the browser, nothing installed and nothing uploaded:

  • Configurator: pick your exact module or chip (with the ordering code you use), assign pins and peripherals, and see conflicts as you click: strapping pins, flash and PSRAM pins, JTAG pins, ADC2 with Wi-Fi, input-only pins, a signal on two pins. Each warning explains itself and cites its source. Export a board.h that compiles with ESP-IDF, plus Markdown and CSV pinouts.
  • Pin checker: check an existing board.h against a chip or part, board variants included.
  • coil-check does the same on the command line for CI (exit code 1 on errors).

10Troubleshooting

"This build is for the ESP32-S3, but the board … is an ESP32-C6".

Debug and Flash refuse a board whose chip isn't the one the project is built for: nothing of the build would run there. Debug the project's board (the Boards view marks the others "not the project's chip"), or build the project for that chip.

"The ESP32-S3 started in download mode".

Debug refuses a chip that started in download mode: the ROM's flashing mode, entered when the BOOT pin (GPIO0; GPIO9 on the ESP32-C6 and C3) is low at power-up, or left set by a flashing tool. A reset from the debugger doesn't read the pins again, so the chip goes back into download mode every time and the app never runs; flashing doesn't help. Unplug the board and plug it back in, without holding BOOT.

Debugging doesn't stop in app_main.

The board is almost certainly running other firmware than the build you're debugging, so the breakpoint sits at an address that never runs. Usually Coil says so ("the board runs other firmware…") and offers Flash.

Firmware with OTA updates can switch its own boot slot. Flash writes the app to ota_0 and resets the OTA data so the next boot runs it, but firmware that updates itself may move the boot to ota_1 within seconds. From then on every reset, including the one each debug session and Restart start with, boots the other slot. Coil can't find this build's app description then; after 3 s without reaching app_main it warns that the board runs an app it can't identify and offers Flash. Flashing helps only until the firmware switches again, so debug with a "flash": true configuration, or turn off the automatic update in debug builds.

To see what's on the chip without changing it: coil-flash --serial <MAC> --dry-run <build folder> lists which parts differ from the build.

"Waiting for the chip to wake (light sleep?)", or "doesn't answer over USB-JTAG".

Firmware that uses light sleep turns off the chip's USB-JTAG while it sleeps: the board stays listed, but nothing answers until the chip wakes (its timer or a pin). Coil keeps trying for up to 20 s and halts the chip the moment it wakes; halted, it can't sleep again, so flashing and debugging carry on normally. A chip that sleeps longer than that: press RESET on the board (Coil catches it while it starts), or turn light sleep off in the builds you debug.

"No launch.json found. Use the 'ESP-IDF: Add vscode Configuration Folder' command."

This comes from Espressif's ESP-IDF extension (its ESP-IDF: Debug button), not from Coil. That button only starts ESP-IDF's own configurations. Debug with Start Debugging (F5), the Run and Debug view, or Coil: Debug.

The board is "in use by another program".

Another program has its JTAG interface open: OpenOCD, another debugger, or a debug session in another VS Code window. The Setup view names it and can stop it.

Flash took 30–40 s instead of 1–2 s.

CMake had to re-run first (see Flash). The next Flash is fast again.

ESP-IDF's GDB takes 2–9 s to start.

GDB path only: a Windows network-path lookup inside GDB. coil-dap, the default, doesn't use GDB.

An antivirus flags a Coil tool (coil-check.exe, coil-gdb.exe…).

Coil's tools aren't code-signed yet, so some antivirus programs (Avast's auto-sandbox, for example) and Windows SmartScreen are wary of them the first time they run. That's a reputation check on a new, unsigned program, not a detection. Allow the extension's bin folder in your antivirus, or report the file to its maker as a false positive.

Something else.

Coil: Show Log opens Coil's output channel, with every command it ran and each tool's messages.

Still stuck, or have an idea?

Open an issue on GitHub. Please include Coil's version, the chip, the probe (built-in USB-JTAG or ESP-Prog), your Windows version and what Coil printed. Check the log for anything private, such as server addresses or keys, before you paste it.

11Commands and settings

Commands

Command
Coil: DebugDebug the selected board, with the first Coil configuration in launch.json if there is one
Coil: New ProjectCreate an ESP-IDF project from a template and open it
Coil: New Source FileA .c (and header) listed in its component's CMakeLists.txt
Coil: Select Build ProfileDebug or Release (also the status bar)
Coil: Release ImageBuild Release and merge it into one image to write at 0x0
Coil: Build (Ctrl+Shift+B)ninja on a configured build; idf.py build the first time or if that fails
Coil: Cleanidf.py clean: delete what the build compiled (the build stays configured)
Coil: Full Cleanidf.py fullclean: delete the build folder (asks first; the next build configures from scratch)
Coil: FlashBuild and flash (Coil's flasher on the C6, C3, S3 and ESP32)
Coil: MonitorSerial monitor
Coil: Build, Flash and MonitorAll three
Coil: Select BoardPick the board to use
Coil: Refresh BoardsList the boards again
Coil: Check SetupRun the setup checks
Coil: Set Up Code Completion (clangd)Set up clangd for the build
Coil: Install ESP-IDFInstall ESP-IDF through EIM
Coil: Install the USB-JTAG DriverEspressif's USB-JTAG driver (asks for administrator rights)
Coil: Install ESP-IDF's USB Drivers (EIM)ESP-IDF's driver package through EIM
Coil: Stop the Program Holding the BoardStop the program that has the board open (asks first)
Coil: Use Coil's DebuggerSwitch coil.debugAdapter back to coil
Coil: Show LogCoil's output channel
Coil: Settings (sdkconfig)The Settings view: sections, presets, changed settings, all settings, search
Coil: Change Setting…Pick an option and a new value
Coil: Reset Setting to DefaultPut a setting you changed back to its default
Coil: Undo Last Settings ChangePut back the sdkconfig from before the last change

Settings

SettingDefault
coil.buildDirbuildThe Debug profile's build folder, relative to the workspace or absolute
coil.releaseBuildDirbuild-releaseThe Release profile's build folder
coil.debugAdaptercoilcoil (coil-dap) or gdb
coil.fastLinkerScripttrueCache ESP-IDF's linker-script generation
coil.idfActivationScriptEIM'sPowerShell script that sets up ESP-IDF for Build, Flash and Monitor
coil.statusBarButtonsall but CleanCoil's buttons on the status bar (also ticked in Status Bar Buttons)
coil.serverPathshippedPath to coil-gdb.exe
coil.gdbPathESP-IDF'sGDB for the GDB path