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:

powershell

// 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.

powershell

& '<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:

powershell

// 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:

powershell

& '<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).