esp-idf-target-management

name	ESP-IDF Target Management
description	Verify and manage the IDF build target (esp32, esp32s3, etc.) to avoid chip mismatch errors and wasted rebuild cycles

ESP-IDF Target Management

When to Use

• Before any idf.py build or idf.py flash command
• After running idf.py fullclean (which wipes the target setting)
• When flashing fails with "Wrong chip argument"
• When switching between different ESP32 variants

Step 1: Check Current Target

Before building, always verify the current target:

// turbo
$cmakeCache = "build\CMakeCache.txt"
if (Test-Path $cmakeCache) {
    $target = (Select-String "IDF_TARGET:INTERNAL=(.+)" $cmakeCache).Matches.Groups[1].Value
    Write-Host "Current IDF target: $target"
} else {
    Write-Host "WARNING: No CMakeCache.txt found - target is not set. Run set-target first."
}

Step 2: Set Target (Only If Needed)

Only run set-target if the target is wrong or unset. Note: set-target internally runs fullclean — it will wipe the entire build directory.

& '<profile>'; idf.py set-target esp32s3

CRITICAL: set-target output is very long. The terminal will show the fullclean portion first, then a CMake configure. The truncated output may only show fullclean — this does NOT mean it failed. Always verify by checking CMakeCache.txt afterward.

Step 3: Verify Target Was Set

After set-target completes, confirm the target before proceeding:

// turbo
$cmakeCache = "build\CMakeCache.txt"
if (Test-Path $cmakeCache) {
    $target = (Select-String "IDF_TARGET:INTERNAL=(.+)" $cmakeCache).Matches.Groups[1].Value
    if ($target -eq "esp32s3") {
        Write-Host "Target confirmed: $target"
    } else {
        Write-Host "ERROR: Target is '$target', expected 'esp32s3'"
    }
} else {
    Write-Host "ERROR: CMakeCache.txt not found after set-target"
}

Step 4: Build and Flash

Only proceed with build+flash after target is confirmed:

& '<profile>'; idf.py build flash monitor

Common Gotchas

Problem	Cause	Fix
"Wrong chip argument" on flash	Binary built for esp32 but device is esp32s3	Run set-target esp32s3 then rebuild
set-target appears to only run fullclean	Truncated terminal output — configure ran but wasn't shown	Check build/CMakeCache.txt for IDF_TARGET
Target resets to esp32 after fullclean	fullclean removes the target setting file	Always run set-target after fullclean
COM port locked during flash	Previous idf.py monitor still holding the port	Kill the previous terminal/process first

Quick Reference: Project Default Target

This project targets esp32s3 (Waveshare ESP32-S3-Touch-AMOLED-1.8).