Esp32 Dev Idf

ESP32 Development with ESP-IDF (Official)

Platform Detection

AI must first detect the OS, then adapt commands:

Environment Detection

ALL paths come from esp32_env.json located alongside the scripts in this skill's scripts/ directory. If this file does not exist, run esp32_env_scan.ps1 (Windows) or the bash equivalent (Linux/macOS).

The JSON contains:

{
  "idf_path": "<detected IDF path>",
  "idf_tools_path": "<detected or chosen toolchain path>",
  "idf_python": "<python executable path>",
  "idf_python_version": "Python x.y.z",
  "idf_version": "<detected IDF version>",
  "platform": "windows|linux|macos"
}

Common installation paths (check these first):

• Windows: $USERPROFILE\esp\esp-idf, D:\esp32\esp-idf
• Linux: ~/esp/esp-idf, /opt/esp-idf
• macOS: ~/esp/esp-idf, /opt/esp-idf

CRITICAL: Windows Terminal Restrictions

ESP-IDF on Windows does NOT support MSYS2 / Git Bash / MINGW64.

if 'MSYSTEM' in os.environ:  # MSYSTEM=MINGW64 set by Git Bash
    fatal('MSys/Mingw is not supported.')

Root causes: MSYS2 path translation (C:\path → /c/path) breaks native Windows tools.

Windows: Always use PowerShell. From Git Bash, execute via .ps1 script files:

powershell -NoProfile -ExecutionPolicy Bypass -File "script.ps1"

Every .ps1 script must clear MSYSTEM:

[Environment]::SetEnvironmentVariable("MSYSTEM", $null, "Process")
[Environment]::SetEnvironmentVariable("MSYS2_PATH", $null, "Process")

Linux/macOS: Use bash/sh directly — no restrictions.

Environment Setup

Linux (Ubuntu) — System Prerequisites

sudo apt-get update
sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \
    cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0
sudo usermod -a -G dialout $USER   # serial port access (re-login required)

macOS — System Prerequisites

brew install cmake ninja ccache dfu-util python3

Windows — No system prerequisites (install.ps1 handles everything)

All Platforms — Clone ESP-IDF

git clone --recursive https://github.com/espressif/esp-idf.git <idf_path>
cd <idf_path>

If cloned without --recursive, the .gitmodules are initialized but files are NOT checked out. You MUST run both commands:

git submodule update --init --recursive
git submodule update --force --checkout --recursive   # if files still missing

Symptoms of missing submodule files: CMake errors like Include directory '.../lwip/lwip/src/include' is not a directory.

Install Toolchain

Windows install wrapper script pattern (for running from Git Bash):

# install_wrapper.ps1
[Environment]::SetEnvironmentVariable("MSYSTEM", $null, "Process")
$env:MSYSTEM = $null
& "D:\esp32\esp-idf\install.ps1"

Then: powershell -NoProfile -ExecutionPolicy Bypass -File "install_wrapper.ps1"

Python Version Compatibility

• ESP-IDF v5.x: Python 3.8–3.12
• ESP-IDF v6.x: Python 3.8+ (tested with 3.14)
• If Python is too new, install an older version or check detect_python.sh for the supported range

Export Environment (every terminal session)

Record Environment

After installation, run esp32_env_scan (platform-specific script in scripts/) to record paths to esp32_env.json.

AI Action Pattern

1. Detect OS from context (uname, $OSTYPE, etc.)
2. Read esp32_env.json → get idf_path, idf_tools_path, idf_version
3. Read the relevant script from scripts/ folder (.ps1 for Windows, .sh for Linux/macOS)
4. Customize paths and execute using the platform-appropriate method
5. On Windows: always route commands through .ps1 scripts that clear MSYSTEM first

Project Lifecycle

Before Creating a Project

Ask the user to:

1. Connect ESP32 to computer via USB cable
2. Ensure the board is powered on
3. Find the serial port:
   • Windows: powershell -NoProfile -Command "[System.IO.Ports.SerialPort]::GetPortNames()"
   • Linux: ls /dev/ttyUSB* or ls /dev/ttyACM*
   • macOS: ls /dev/cu.usbserial* or ls /dev/cu.wchusbserial*

Auto-Detect Chip Model

# Via the reusable script (Windows):
powershell -NoProfile -ExecutionPolicy Bypass -File "esp32_chip_detect.ps1" -port COMx

# Or manually:
esptool --port <PORT> flash-id

Typical output:

Detecting chip type... ESP32-S3
Chip is ESP32-S3 (revision v0.2)

Never guess the chip model — always auto-detect. If detection fails:

• Check USB cable (some are charge-only)
• Try different port (ESP32-S3 may enumerate differently in download mode)
• Hold BOOT + tap EN, then retry
• Try lower baud rate: --baud 115200 --before no-reset
• If all else fails — ask the user directly

Create Project

WARNING: idf.py create-project -path may fail when IDF and the project are on different drives (Windows os.rename cross-drive error). In that case, create the project structure manually:

Manual project creation:

project_root/
├── CMakeLists.txt           # Top-level build file
├── main/
│   ├── CMakeLists.txt
│   └── main.c
└── .gitignore

CMakeLists.txt (root):

cmake_minimum_required(VERSION 3.16)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
project(my_project)

main/CMakeLists.txt:

idf_component_register(SRCS "main.c"
                    INCLUDE_DIRS ".")

main/main.c:

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_system.h"
#include "esp_log.h"

static const char *TAG = "main";

void app_main(void)
{
    ESP_LOGI(TAG, "ESP32 initialized!");
    ESP_LOGI(TAG, "IDF version: %s", esp_get_idf_version());
    ESP_LOGI(TAG, "Chip: %s with %d cores", CONFIG_IDF_TARGET, portNUM_PROCESSORS);

    while (1) {
        ESP_LOGI(TAG, "Hello, ESP32! Tick: %lu", xTaskGetTickCount());
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

.gitignore:

build/
sdkconfig
sdkconfig.old
*.pyc
__pycache__/

Set Chip Target

idf.py set-target esp32s3    # esp32, esp32s3, esp32c3, esp32c6, etc.

If set-target fails, check for stale build state:

rm -rf build/          # or: powershell Remove-Item -Recurse -Force build/
rm -f sdkconfig.old     # remove old sdkconfig backups

Build

idf.py build

Flash

# Windows
idf.py -p COM3 flash

# Linux
idf.py -p /dev/ttyUSB0 flash

# macOS
idf.py -p /dev/cu.usbserial-1234 flash

Monitor

idf.py -p <PORT> monitor     # Ctrl+] to exit on all platforms

All-in-One

idf.py -p <PORT> build flash monitor

Key IDF Commands

Project Structure

my_project/
├── CMakeLists.txt          # Top-level build file
├── sdkconfig               # Generated by set-target / menuconfig
├── main/
│   ├── CMakeLists.txt
│   └── main.c
├── components/             # Custom components (optional)
├── build/                  # Build artifacts (gitignored)
│   ├── my_project.bin      # Flashable binary
│   ├── my_project.elf      # ELF with debug symbols
│   ├── bootloader/         # Second-stage bootloader
│   └── partition_table/    # Partition table binary
└── .gitignore

Chip Selection Guide

JTAG Debugging

Debugger Compatibility

ESP32-S3/C3/C6/C2 do NOT need an external debugger — built-in USB-Serial-JTAG works over the same USB cable used for flashing.

USB-JTAG Windows Driver Setup

On Windows, the JTAG interface (MI_02) must use libusb-win32 driver via Zadig (https://zadig.akeo.ie/). See the parent esp32-dev skill for detailed steps.

JTAG Pinout (External)

Launch Debug (All Platforms)

# Terminal 1: Start OpenOCD
idf.py openocd
# Note: must be run from a project directory, NOT IDF root

# Terminal 2: Start GDB
idf.py gdb

GDB Commands

Quick Debug (ESP32-S3/C3/C6 USB-JTAG)

idf.py openocd                    # Terminal 1
idf.py gdb                        # Terminal 2

Common Pitfalls

Windows

1. MSYSTEM Detection: Must use PowerShell via script files
2. USB-JTAG driver: Replace WinUSB with libusb-win32 via Zadig for MI_02 interface
3. COM Port: Use PowerShell [System.IO.Ports.SerialPort]::GetPortNames() to list
4. BOOT+EN: Hold BOOT, tap EN to enter download mode for flashing
5. ESP32-S3 port switching: The COM port number may change when the chip enters download mode
6. Cross-drive create-project: idf.py create-project -path fails when IDF is on different drive — create manually

Linux

1. Serial permission: sudo usermod -a -G dialout $USER (re-login)
2. Port busy: sudo chmod 666 /dev/ttyUSB0 if permission denied
3. Missing libs: sudo apt install libusb-1.0-0

macOS

1. Serial driver: CP210x/CH340 may need driver install
2. Port format: /dev/cu.usbserial-*, not /dev/tty.*

All Platforms

1. Python: ESP-IDF v5.x/v6.x requires Python 3.8+ (tested up to 3.14 on v6.2)
2. Missing venv: "module 'rich' not found" → re-run install script
3. Cable: Use data cable (some are charge-only)
4. Submodule fail: git submodule update --init --recursive then --force --checkout
5. Stale build dir: Delete build/ and sdkconfig before re-running set-target
6. idf.py openocd location: Must run from a project directory, NOT from IDF root