Esp32 Dev

ESP32 Development — Framework Selection

Platform Support

This skill supports Windows, Linux (Ubuntu), and macOS.

Overview

ESP32 supports two mainstream development frameworks:

Workflow

User asks for ESP32 development
  ↓
[Step 1] Detect OS → adapt terminal/port/script format
  ↓
[Step 2] Introduce both frameworks (IDF vs Arduino)
  ↓
[Step 3] Ask user: "Which framework do you prefer?"
          Option A: ESP-IDF (official, C, full control)
          Option B: Arduino (simpler, C++, rapid prototyping)
  ↓
[Step 4] Based on choice, invoke the sub-skill:
          IDF     → Skill("esp32-dev-idf")
          Arduino → Skill("esp32-dev-arduino")
  ↓
[Step 5] ⚡ RTOS Selection — list available RTOS with pros/cons,
          then ask user: "Which RTOS or bare metal?"
  ↓
[Step 6] ⚡ Ask user to connect device + power on
  ↓
[Step 7] Find serial port (platform-specific)
  ↓
[Step 8] Auto-detect chip model (esptool.py flash_id)
  ↓
[Step 9] The sub-skill handles:
          - Environment detection (check esp32_env.json)
          - Environment installation (if not already done)
          - Project initialization with detected chip + selected RTOS
          - Compile → Flash → Monitor workflow

RTOS Selection

When the user starts a new project or initializes an existing one, AI MUST present the RTOS options and ask for a decision.

Available RTOS for ESP32

Detailed Comparison

FreeRTOS (ESP-IDF 默认)

Zephyr

ThreadX (Azure RTOS)

NuttX

RT-Thread

Bare Metal (无 RTOS)

Selection Guide

AI 根据用户需求推荐 RTOS：

用户场景                                    推荐
─────────────────────────────────────────────────
快速原型 / 通用开发 / 学习 ESP32    →  FreeRTOS (默认，ESP-IDF 内置)
IoT 产品 / 多协议连接 / 安全认证     →  Zephyr
医疗 / 汽车 / 工业安全认证产品       →  ThreadX
移植 Linux 程序 / POSIX 兼容         →  NuttX
国产化要求 / 中文社区 / 组件丰富     →  RT-Thread
极致资源控制 / 简单传感器采集       →  Bare Metal

AI Action Pattern for RTOS Selection

1. When the user asks to create/initialize a project, AI MUST present the RTOS options table above BEFORE creating the project.
2. Ask the user: "Which RTOS do you want to use? (or bare metal)"
3. Based on choice:
   • FreeRTOS: Create a standard ESP-IDF app_main() project (default template)
   • Zephyr / ThreadX / NuttX / RT-Thread: Flag that this requires additional setup and ask user to confirm
   • Bare Metal: Create a minimal project without FreeRTOS (use app_main() only, no task creation)
4. Record the choice and proceed with project creation

Environment Detection

ALL path information is stored in esp32_env.json, located alongside the scripts in this skill's scripts/ directory.

When any sub-skill loads:

1. First check if esp32_env.json exists
2. If it exists, read idf_path, idf_tools_path, platform from it
3. If it does NOT exist, run the platform-appropriate env scanner
4. Use the recorded paths in all subsequent operations

The JSON structure:

{
  "idf_path": "D:\\esp32\\esp-idf",
  "idf_tools_path": "C:\\Users\\Administrator\\.espressif",
  "idf_python": "C:\\Python314\\python.exe",
  "idf_python_version": "Python 3.14.2",
  "idf_version": "v6.2",
  "platform": "windows",
  "timestamp": "2026-06-09"
}

Common paths to check:

• Windows: $USERPROFILE\esp\esp-idf, D:\esp32\esp-idf
• Linux: ~/esp/esp-idf, /opt/esp-idf
• macOS: ~/esp/esp-idf, /opt/esp-idf
• Toolchain default: $HOME/.espressif (all platforms)

Reusable Scripts

All scripts are in the scripts/ directory of this skill. Read and execute directly — do NOT regenerate.

Chip Auto-Detection

AI must use the esp32_chip_detect.ps1 script to auto-detect the chip model. Never guess.

# Find serial port first, then:
powershell -NoProfile -ExecutionPolicy Bypass -File "esp32_chip_detect.ps1" -port COMx

Detection failure troubleshooting (in order):

1. Ensure the device is in download mode (hold BOOT + tap EN on ESP32 boards)
2. For ESP32-S3 with built-in USB-JTAG, the port may change when entering download mode (e.g. COM11 → COM12)
3. Check USB cable is a data cable (not charge-only)
4. On Windows, check Device Manager → Ports for the correct COM number
5. Try lowering baud rate: --baud 115200
6. If auto-detect fails after multiple attempts — ask the user for the chip model directly
7. If the user provides the chip model, specify it with --chip esp32s3 to speed up detection

Chip Selection Guide

USB-JTAG Debugging (ESP32-S3/C3/C6/C2/H2)

Hardware

ESP32-S3/C3/C6/C2/H2 have built-in USB-JTAG via GPIO19 (USB_D-) + GPIO20 (USB_D+). No external hardware required. The same USB cable used for flashing also provides JTAG debugging.

The USB composite device enumerates with multiple interfaces:

• MI_00 → USB Serial (COM port for flashing/logging), uses usbser driver
• MI_02 → USB JTAG (debug interface), needs libusb-win32 driver on Windows

Windows Driver Setup (CRITICAL)

On Windows, the JTAG interface MUST use libusb-win32 driver, NOT WinUSB.

Use Zadig (https://zadig.akeo.ie/) to replace the driver:

1. Open Zadig → Options → List All Devices (must be checked!)
2. In the dropdown, find entries with USB ID 303A:1001
3. Select Interface 2 (MI_02) — the one with current driver "WINUSB"
4. Replace with libusb-win32 (not WinUSB, not libusbK)
5. Click Replace Driver

IMPORTANT: Only replace the driver for MI_02 (JTAG interface). Do NOT touch MI_00 (COM port, usbser driver) or the parent composite device (usbccgp driver).

Verification: After replacement, the device service should show libusb0:

Get-PnpDevice | Where-Object { $_.FriendlyName -like '*JTAG*' }

Launch OpenOCD + GDB

# Terminal 1 — OpenOCD (stays running)
idf.py openocd
# or:
powershell -NoProfile -ExecutionPolicy Bypass -File "idf_openocd.ps1" -project_path <path>

# Terminal 2 — GDB (interactive)
idf.py gdb
# or:
xtensa-esp32s3-elf-gdb build/<project>.elf
(gdb) target remote :3333
(gdb) mon reset halt

Debugger Compatibility

Common Pitfalls

Windows

1. MSYSTEM Detection: Must use PowerShell via script files, NOT Git Bash directly
2. ESP32-S3 USB-JTAG driver: Must replace WinUSB with libusb-win32 via Zadig
3. Port changes in download mode: ESP32-S3 may enumerate as different COM port when entering download mode
4. Cross-drive create-project bug: idf.py create-project -path fails when IDF is on a different drive than project. Create project structure manually instead.
5. Proxy Duplicate Keys: Clear *proxy* vars before .ps1

Linux

1. Serial permission: sudo usermod -a -G dialout $USER (re-login required)
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 version: ESP-IDF v5.x/v6.x requires Python 3.8+ (tested up to 3.14)
2. Missing submodules: git submodule update --init --recursive (required after git clone without --recursive)
3. Data cable: Some USB cables are charge-only — use a proper data cable
4. Submodule checkout: After git submodule update --init, may need --force --checkout for full file checkout
5. Build directory conflicts: If set-target fails, manually delete build/ and sdkconfig before retrying
6. idf.py openocd requires project dir: Must run from project directory, not IDF root

Skill Hierarchy

esp32-dev (entry point — this file)
├── esp32-dev-idf    → ESP-IDF framework setup + project lifecycle
├── esp32-dev-arduino → Arduino framework setup + project lifecycle
└── esp32-debug      → Debug workflow (serial log + JTAG/GDB)

Division of responsibility:

• esp32-dev: Framework selection, OS detection, shared knowledge (chip detection, USB-JTAG, scripts reference)
• esp32-dev-idf: IDF-specific installation, project creation, compile/flash/monitor
• esp32-dev-arduino: Arduino-specific installation, project creation, compile/flash
• esp32-debug: Systematic debug workflow — problem understanding → code analysis → debug method selection → root cause analysis → report