VS Code Setup¶

Configure Visual Studio Code for ESP-IDF development. This guide covers the ESP-IDF extension, C/C++ IntelliSense, and recommended settings for a smooth development experience.

Step 1 — Install VS Code¶

Download from code.visualstudio.com and install.

WindowsmacOSLinux

Download the User Installer (.exe)
Run the installer — check "Add to PATH"
Launch VS Code

Download the .zip archive
Extract and drag Visual Studio Code.app to Applications
Open from Launchpad or Applications

# Ubuntu/Debian — via .deb package
sudo apt-get install -y code

# Or via snap
sudo snap install code --classic

# Or download from https://code.visualstudio.com/

Step 2 — Install Required Extensions¶

Open VS Code and install these extensions:

Essential¶

Extension	ID	Purpose
ESP-IDF	`espressif.esp-idf-extension`	Build, flash, monitor, menuconfig — all from VS Code
C/C++	`ms-vscode.cpptools`	IntelliSense, debugging, code navigation

Recommended¶

Extension	ID	Purpose
CMake Tools	`ms-vscode.cmake-tools`	CMake configuration and build
Cortex-Debug	`marus25.cortex-debug`	ARM/RISC-V JTAG debugging
Serial Monitor	`ms-vscode.vscode-serial-monitor`	Serial port monitoring inside VS Code
Error Lens	`usernamehw.errorlens`	Inline error/warning display
GitLens	`eamodio.gitlens`	Git integration and blame

Install from the command line:

code --install-extension espressif.esp-idf-extension
code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools
code --install-extension marus25.cortex-debug
code --install-extension ms-vscode.vscode-serial-monitor

Step 3 — Configure the ESP-IDF Extension¶

Using Docker (Recommended for Workshop)Using Native Installation

Open VS Code
Press Ctrl+Shift+P (macOS: Cmd+Shift+P) → type ESP-IDF: Configure ESP-IDF Extension
Select USE EXISTING SETUP
Enter the path to your ESP-IDF directory:
Docker path: The extension will use the Docker container's ESP-IDF installation
Set the target to esp32s3
Set the serial port for your board

Docker integration

The ESP-IDF extension can detect and use ESP-IDF inside a Docker container. When you run build/flash/monitor commands from the extension, it executes them inside the container.

Open VS Code
Press Ctrl+Shift+P (macOS: Cmd+Shift+P) → type ESP-IDF: Configure ESP-IDF Extension
Select EXPRESS (fast setup) or ADVANCED (custom paths)
Enter the paths:
ESP-IDF path: ~/esp/esp-idf (or %USERPROFILE%\esp\esp-idf on Windows)
Tools path: ~/.espressif (default)
Set the target to esp32s3
Set the serial port for your board

Step 4 — Workspace Settings¶

Create a .vscode/settings.json in your project for optimal ESP-IDF development:

.vscode/settings.json

{
    "C_Cpp.default.compilerPath": "${env:IDF_TOOLS_PATH}/tools/xtensa-esp-elf/esp-14.2.0_20241119/xtensa-esp-elf/bin/xtensa-esp32s3-elf-gcc",
    "C_Cpp.default.intelliSenseMode": "gcc-x64",
    "C_Cpp.default.defines": [
        "ESP32S3",
        "__GNUC__",
        "CONFIG_IDF_TARGET_ESP32S3"
    ],
    "C_Cpp.default.includePath": [
        "${workspaceFolder}/**",
        "${env:IDF_PATH}/components/**"
    ],
    "files.associations": {
        "*.h": "c",
        "*.c": "c"
    },
    "editor.formatOnSave": true,
    "editor.tabSize": 4,
    "editor.insertSpaces": true,
    "files.trimTrailingWhitespace": true,
    "search.exclude": {
        "build/**": true
    }
}

IntelliSense configuration

The ESP-IDF extension auto-generates `c_cpp_properties.json` when you build the project. If IntelliSense isn't working, run a build first — the extension will create the correct configuration.

Step 5 — Useful Keyboard Shortcuts¶

Action	Windows/Linux	macOS
Command Palette	`Ctrl+Shift+P`	`Cmd+Shift+P`
Build project	`Ctrl+E B`	`Cmd+E B`
Flash project	`Ctrl+E D`	`Cmd+E D`
Open serial monitor	`Ctrl+E M`	`Cmd+E M`
Open menuconfig	`Ctrl+E G`	`Cmd+E G`
Quick open (files)	`Ctrl+P`	`Cmd+P`
Go to definition	`F12`	`F12`
Find all references	`Shift+F12`	`Shift+F12`
Toggle terminal	`Ctrl+` `\|`Cmd+

Step 6 — Debugging (Advanced)¶

If you have a JTAG debug probe, you can debug ESP-IDF firmware directly in VS Code.

Launch Configuration¶

Create .vscode/launch.json:

.vscode/launch.json

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "ESP-IDF Debug",
            "type": "cortex-debug",
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "executable": "${workspaceFolder}/build/projectname.elf",
            "servertype": "espidf",
            "device": "esp32s3",
            "configFiles": [
                "interface/ftdi/esp32_devkitj_v1.cfg",
                "target/esp32s3.cfg"
            ]
        }
    ]
}

JTAG required

Debugging requires a JTAG probe connected to the ESP32-S3's JTAG pins. The XIAO ESP32-S3 does not have a built-in JTAG interface — you'd need an external probe like ESP-Prog. This is not required for the workshop.

Troubleshooting¶

IntelliSense not working¶

Build the project at least once (idf.py build)
The ESP-IDF extension generates c_cpp_properties.json automatically
If still broken: Ctrl+Shift+P → C/C++: Reset IntelliSense Database

ESP-IDF extension commands not appearing¶

Ensure the extension is installed and enabled
Reload VS Code window: Ctrl+Shift+P → Developer: Reload Window
Check the extension's output panel for errors

Serial port not found¶

Connect the XIAO ESP32-S3 via USB-C
Install USB drivers if needed — see Prerequisites
Check the port: ls /dev/tty* (macOS/Linux) or Device Manager (Windows)

Build fails from VS Code but works in terminal¶

The ESP-IDF extension may not have the environment variables loaded. Run:

Ctrl+Shift+P → ESP-IDF: Configure ESP-IDF Extension → re-select your setup

Next Steps¶

Docker Setup → Docker Setup — Install Docker and Docker Compose
Hardware Kit → Hardware Kit — Reference for all workshop hardware