Development Container Setup

This template uses containerized development with VS Code Dev Containers and GitHub Codespaces for consistent ESP-IDF development environment.

Development Options

Alternative: Local Dev Container

  • Uses Docker container with ESP-IDF v5.4.1 pre-installed

  • Requires Docker Desktop and VS Code with Dev Containers extension

Note

This template focuses on Codespaces workflow. Local dev container support is provided but not officially supported.

Warning

Native Windows (without a container) is not supported. The ESP-IDF toolchain relies on a Linux shell environment and has known conflicts with Windows PATH conventions. All development must run inside a container (GitHub Codespaces or local Dev Container via Docker). Running idf.py natively on Windows will not work.

Using the Dev Container

In GitHub Codespaces

  1. Go to your GitHub repository

  2. Click “Code” → “Codespaces” → “Create codespace”

  3. Container will automatically build with ESP-IDF ready

  4. Extensions (ESP-IDF, ESP-IDF Web) will be pre-installed

Local Development with Docker

Recommended: Clone repository into container volume for best performance (like Codespaces):

  1. Install VS Code and the Dev Containers extension

  2. Ensure Docker Desktop is running

  3. In VS Code: Press F1 → Type “Dev Containers: Clone Repository in Container Volume…”

  4. Enter repository URL (GitHub/GitLab/etc.)

  5. Select branch to clone

  6. Container builds automatically with full ESP-IDF environment

Alternative: Open existing local clone in container:

  1. Clone repository to your local machine

  2. Open the project in VS Code

  3. VS Code will prompt: “Reopen in Container” → Click Yes

  4. Container builds and mounts your local files

Tip

Container volume cloning is faster! File I/O performance is significantly better when the repository lives in a Docker volume rather than being bind-mounted from the host filesystem.

Container Features

  • ESP-IDF v5.4.1: Latest stable version pre-configured

  • Pre-configured VS Code: ESP-IDF extension settings ready

  • Web Serial Support: ESP-IDF Web extension for Codespaces flashing/monitoring

  • Port forwarding: HTTP server (80, 443) and development ports

  • Privileged mode: USB device access for flashing (local Docker only)

Build Commands in Container

# Standard ESP-IDF commands work directly
idf.py build
idf.py flash monitor
idf.py menuconfig

# Container has ESP-IDF environment pre-loaded
# No need to run export.sh or install.sh

Hardware Flashing

  • Local Docker: Hardware connected to host is accessible in container

  • Codespaces: Use ESP-IDF Web extension for WebSerial/WebUSB flashing

  • Mixed workflow: Build in container, flash on host if needed

Windows USB Device Setup (Local Dev Container Only)

For Windows users running the dev container locally (not needed for Codespaces):

Quick Setup: Run tools/attach-esp32.ps1 as Administrator - script automatically finds and attaches your ESP32.

Manual Setup (if script doesn’t work):

  1. Install usbipd-win: winget install usbipd

  2. Find device: usbipd list (look for USB-SERIAL CH340)

  3. Bind device: usbipd bind --busid <BUSID>

  4. Attach to container: usbipd attach --wsl --busid <BUSID>

Note

GitHub Codespaces handles USB through browser serial interface - no manual setup needed.

Benefits

✅ Consistent environments across Windows, macOS, Linux, Codespaces

✅ No ESP-IDF setup required for new team members

✅ Isolated dependencies - container changes don’t affect host system

✅ Easy onboarding - clone repo, open in VS Code, start coding

✅ Your existing setup unchanged - host workflow still works

Container Configuration

The dev container is configured in .devcontainer/devcontainer.json:

  • Base image: espressif/idf:v5.4.1

  • VS Code extensions automatically installed

  • Port forwarding for web development

  • Git configuration inherited from host

Troubleshooting

Issue: Container fails to build

  • Solution: Check Docker Desktop is running and has sufficient resources (4GB+ RAM recommended)

Issue: ESP32 device not visible in container

  • Solution: For local Docker, ensure USB device is attached using usbipd (Windows) or passed through (Linux/macOS)

Issue: Extensions not installed

  • Solution: Reload window (Ctrl+Shift+P → “Developer: Reload Window”) or manually install from marketplace

Issue: Slow build times

  • Solution: Dev container caches ESP-IDF, but first build always takes longer. Subsequent builds are faster.