Zephyr ESP — VSCode extension

Build, flash, monitor and debug Espressif SoCs running Zephyr RTOS directly from VSCode.

Features

• Activity Bar dashboard with one-click setup for Application, Board, Serial Port, OpenOCD, Zephyr SDK and Python venv.
• Status bar buttons for Build, Flash, Monitor, Debug and Run (Build + Flash + Monitor chained). Tooltips show the exact command that will execute with your current selections.
• Automatic tool detection: Zephyr SDK (via setting, env var or common install paths), Python venv, west, and openocd-esp32 (via setting, extension cache, ~/.espressif/tools, or /opt).
• Auto-download of openocd-esp32 matching the pinned version, with SHA-256 verification and a dedicated Downloads output channel. Covers all published variants (linux-amd64/arm64/armhf/armel, macos, macos-arm64, win32, win64).
• Board picker scans <app>/boards, every west module and the Zephyr tree for boards with an Espressif SoC.
• Debug via cortex-debug with openocd-esp32, the Zephyr SDK GDB toolchain, rtos: Zephyr for thread-aware debugging, and auto-downloaded SVD files for the Peripheral Viewer (C2, C3, C6, H2, S2, S3, P4, ESP32, P4).
• Export .vscode/ — palette command and Workspace-card button that write a cortex-debug launch.json, tasks.json and extensions.json pre-filled with the current selections, so the same debug flow keeps working if the extension is later uninstalled.
• Sysbuild aware — detects and prefers the app ELF under build/<app>/zephyr/ while skipping bootloader images (mcuboot, hostap_main, etc.).
• Debug thread info toggle — optional build flag -DCONFIG_DEBUG_THREAD_INFO=y enables Zephyr-thread-aware call stack in the debugger.

Requirements

• VSCode 1.90+
• Zephyr west workspace (app inside a folder containing .west/)
• Zephyr SDK with the RISC-V and/or Xtensa ESP32 toolchains installed
• A Python venv with west installed (set zephyrEsp.python.venv to its path if west is not on your PATH)
• marus25.cortex-debug — auto-installed as a dependency

Getting started

1. Open your Zephyr workspace folder (the one containing .west/ or a subfolder of it).
2. Click the Zephyr ESP icon in the Activity Bar.
3. Set:
   • Application — click Browse… and pick your app directory (the folder containing CMakeLists.txt with find_package(Zephyr)).
   • Board — pick from the dropdown.
   • Serial Port — the dropdown enumerates connected ports on Linux / macOS (/dev/tty*) and Windows (via registry).
   • OpenOCD — if not auto-detected, click Download on the OpenOCD card.
4. Click Build, Flash, Monitor, Debug or Run in the status bar (or on the dashboard).

Settings

Setting	Description
zephyrEsp.openocd.root	Explicit openocd-esp32 root (folder with bin/ and share/openocd/scripts). Leave empty to auto-detect.
zephyrEsp.openocd.autoUpdate	Silently download the pinned openocd-esp32 when missing.
zephyrEsp.openocd.platform	Override the auto-detected download platform.
zephyrEsp.sdk.root	Explicit Zephyr SDK root. Leave empty to auto-detect.
zephyrEsp.python.venv	Python venv that provides west. Its bin/ (or Scripts/ on Windows) is prepended to PATH.
zephyrEsp.west.path	Explicit path to the west binary. Overrides venv-derived lookup.
zephyrEsp.zephyrDir	Explicit Zephyr source tree (folder with Kconfig.zephyr). Overrides auto-detection from the west root.
zephyrEsp.boardRoots	Additional board root directories to scan for Espressif boards.

Commands

Command	Description
Zephyr ESP: Open Dashboard	Reveal the Activity Bar dashboard.
Zephyr ESP: Build	west build with the current board and options.
Zephyr ESP: Flash	west flash.
Zephyr ESP: Monitor	west espressif monitor with ELF symbols and selected port.
Zephyr ESP: Debug	Launch cortex-debug against openocd-esp32.
Zephyr ESP: Run (Build + Flash + Monitor)	Chain the three, stopping on first failure.
Zephyr ESP: Export .vscode/launch.json and tasks.json	Write a standalone cortex-debug configuration.
Zephyr ESP: Download/Update openocd-esp32	Explicitly re-download the pinned version.

Development

npm install
npm run build         # bundle src/ into dist/extension.js
npm run typecheck     # strict tsc check
npm run package       # produce a .vsix

Press F5 in VSCode to launch an Extension Development Host with the extension loaded.

License

Apache-2.0 — see LICENSE.