Skip to main content

Tutorial Project: ESP32 Hello World in VS Code (ESP-IDF Extension, Windows)

Purpose​

Help a beginner go from zero → working ESP32 firmware using the official ESP-IDF workflow inside VS Code (Windows).

You will learn:

  • How to install VS Code + ESP-IDF extension
  • How to install ESP-IDF tools on Windows
  • How to create a project using the extension’s templates
  • How to configure a project using menuconfig
  • How to build, flash, and monitor
  • Essential terminal commands (idf.py, cleaning, set-target, etc.)

Scope​

  • Windows 10/11
  • ESP32 family (ESP32, ESP32‑S3, ESP32‑C3, etc.) using ESP-IDF

Prerequisites (hardware)​

  • An ESP32 dev board
  • USB data cable
  • A Windows PC with admin rights

Resources (official)​

Part A — Install VS Code + ESP-IDF Extension (Windows)

A1) Install VS Code​

  1. Download VS Code:
  2. Install with defaults.
  3. After install, open VS Code once.

A2) Install the ESP-IDF Extension​

  1. In VS Code: Extensions (Ctrl+Shift+X)
  2. Search: “Espressif IDF”
  3. Install Espressif IDF extension.

A3) Install ESP-IDF Tools (via the extension)​

The extension can install the toolchain and ESP-IDF for you.

  1. Open command palette: Ctrl+Shift+P
  2. Run:
    • ESP-IDF: Configure ESP-IDF extension
  3. Choose the recommended option (usually:
    • Express install for beginners
    • installs ESP-IDF + Python + Git + toolchain + CMake/Ninja)
  4. Select an install directory (keep it short, no spaces if possible), examples:
    • C:\Espressif\
  5. Let it finish.

Common Windows driver note​

If the board doesn’t show up as a COM port, you may need a USB‑UART driver:

  • CP210x (Silicon Labs) or CH340 (WCH)
  • Check Device Manager → Ports (COM & LPT)

Part B — Create “Hello World” Project (Template)

B1) Start a new project from a template​

  1. Ctrl+Shift+P → run:
    • ESP-IDF: New Project
  2. Choose:
    • Project template: hello_world (recommended)
  3. Choose a location, e.g.:
    • D:\esp32\hello_world_vscode\
  4. Open the folder when prompted.

B2) Select your target chip (important)​

In the bottom status bar you’ll see ESP-IDF controls.

  1. Ctrl+Shift+P → run:
    • ESP-IDF: Set Espressif Device Target
  2. Pick your chip:
    • esp32 / esp32s3 / esp32c3 etc.

This sets the correct defaults and avoids build errors.

B3) Select the serial port​

  1. Plug in the board
  2. Ctrl+Shift+P → run:
    • ESP-IDF: Select Port to Use
  3. Pick something like COM3, COM7, etc.

Part C — Build, Flash, Monitor (VS Code + Terminal)

C1) Build (compile)​

You can build either via the extension UI buttons or the terminal.

Option 1: VS Code extension buttons​

  • Click Build (often a hammer icon or command palette action)

Option 2: Terminal (idf.py)​

Open the ESP-IDF terminal in VS Code:

  • Ctrl+Shift+P → ESP-IDF: Open ESP-IDF Terminal

Then run:

idf.py build

C2) Flash (upload firmware)​

idf.py -p COM7 flash

Replace COM7 with your port.

C3) Monitor (serial logs)​

idf.py -p COM7 monitor

Exit monitor​

  • Press: Ctrl+] (common default)

C4) One-command workflow​

idf.py -p COM7 flash monitor

Part D — Using Templates Correctly (repeatable projects)

When creating new projects, always prefer templates instead of copying random folders.

  1. New project from template (hello_world / blink / wifi examples)
  2. Set target (esp32/esp32s3/esp32c3)
  3. Run idf.py build
  4. Commit to Git (optional but recommended)

Where templates come from​

ESP-IDF ships example projects. The VS Code extension surfaces them via New Project.

Part E — Configuration with menuconfig

menuconfig is the standard ESP-IDF configuration UI.

E1) Open menuconfig​

From ESP-IDF terminal:

idf.py menuconfig

E2) What to change (beginner essentials)​

Exact options vary by target, but these are common.

Serial flasher / monitor baud rate​

  • Increase monitor baud (e.g., 115200 → 921600) if stable
  • Keep at 115200 if you see garbage logs

Flash size / flash mode​

  • Ensure flash size matches your board (common: 4MB, 8MB, 16MB)
  • Wrong flash size can cause boot loops or OTA issues later

Partition table​

  • Default is fine for hello_world
  • Later you’ll choose custom partition tables for OTA, large storage, etc.

Wi‑Fi settings (when using Wi‑Fi examples)​

  • Some examples read SSID/PASS from menuconfig

E3) Save and exit​

  • Use the menu to Save and exit.
  • This writes settings to sdkconfig.

E4) Rebuild after config changes​

idf.py build

Part F — Essential ESP-IDF Terminal Commands (cheat sheet)

Run these inside the project folder.

Build / Flash / Monitor​

idf.py build
idf.py -p COM7 flash
idf.py -p COM7 monitor
idf.py -p COM7 flash monitor

Clean builds​

idf.py clean
idf.py fullclean
  • clean: removes build artifacts
  • fullclean: removes more state (useful when switching targets)

Set/confirm target​

idf.py set-target esp32

Reconfigure​

idf.py reconfigure

Show size information​

idf.py size
idf.py size-components

Erase flash (careful)​

idf.py -p COM7 erase-flash

Part G — Common Troubleshooting (Windows)

G1) COM port not visible​

  • Try a different USB cable (must be data)
  • Check Device Manager
  • Install CP210x/CH340 driver

G2) Permission / port busy​

  • Close other serial monitors (Arduino Serial Monitor, PuTTY, etc.)
  • Unplug/replug USB

G3) Build fails after changing chip​

  • Ensure you ran set-target and then fullclean:
idf.py set-target esp32s3
idf.py fullclean
idf.py build

G4) Garbage output in monitor​

  • Wrong baud rate: set monitor to 115200
  • Check the board’s boot mode and reset sequence

Deliverable Checklist (for learners)

  • VS Code installed
  • ESP-IDF extension installed
  • ESP-IDF tools installed successfully
  • hello_world project created from template
  • Target selected correctly
  • Build succeeds
  • Flash succeeds
  • Monitor shows “Hello world!” logs
  • Opened and used menuconfig

Changelog​

  • 2026-02-14: Initial tutorial created.