ESP32-S3 Custom 5MB OTA Partition Setup Guide for Arduino IDE 2.x¶

Prerequisites¶

Arduino IDE 2.x installed
ESP32-S3 board with 16MB flash

Step 1: Install ESP32 Board Package¶

Open Arduino IDE 2.x
Go to File → Preferences

In "Additional board manager URLs" add:

https://espressif.github.io/arduino-esp32/package_esp32_index.json

Go to Tools → Board → Boards Manager
Search for "ESP32" and install "esp32 by Espressif Systems"
Select your ESP32-S3 board: Tools → Board → ESP32 Arduino → Your ESP32-S3 variant

Step 2: Clear Arduino Cache¶

Important: Clear Arduino cache to avoid conflicts:

rm -rf ~/Library/Caches/arduino

Step 3: Create Custom Partition Table¶

Open Terminal and navigate to your sketch folder:
```
cd /Users/joeceo/Documents/Arduino/Xregulator
```

Create partitions.csv file using Terminal cat command:

cat > partitions.csv << 'EOF'
# Name, Type, SubType, Offset, Size, Flags
nvs, data, nvs, 0x9000, 0x5000,
otadata, data, ota, 0xe000, 0x2000,
app0, app, ota_0, 0x10000, 0x500000,
app1, app, ota_1, 0x510000, 0x500000,
spiffs, data, spiffs, 0xa10000, 0x5D0000,
coredump, data, coredump, 0xFF0000, 0x40000,
EOF

Verify the file was created:

cat /Users/joeceo/Documents/Arduino/Xregulator/partitions.csv

Step 4: Configure Arduino IDE for Custom Partitions¶

Tools → Programmer → esptool (select esptool as programmer)
Important: Any partition scheme selected in Tools → Partition Scheme will be ignored when partitions.csv exists in sketch folder

Step 5: Clear Cache and Upload¶

Clear Arduino cache again before upload:
```
rm -rf ~/Library/Caches/arduino
```
Upload your sketch using the regular Upload button

Step 6: Verify Success¶

Upload this verification sketch:

#include "esp_partition.h"

void setup() {
  Serial.begin(115200);
  delay(2000);
  Serial.println("=== Partition Table ===");

  esp_partition_iterator_t it = esp_partition_find(ESP_PARTITION_TYPE_APP, ESP_PARTITION_SUBTYPE_ANY, NULL);
  while (it != NULL) {
    const esp_partition_t* part = esp_partition_get(it);
    Serial.printf("APP: %s at 0x%x, size: %d MB\n", 
                  part->label, part->address, part->size/1024/1024);
    it = esp_partition_next(it);
  }
  esp_partition_iterator_release(it);
}

void loop() {}

Expected output:

APP: app0 at 0x10000, size: 5 MB
APP: app1 at 0x510000, size: 5 MB

Key Points¶

✅ partitions.csv in sketch folder automatically overrides all IDE partition settings
✅ Clear Arduino cache frequently to avoid stale cached partition tables
✅ Always use Terminal cat command to create partitions.csv

Important Note About Compilation Messages¶

Why compilation messages caused confusion: Arduino IDE's compilation output shows flash erase ranges that may be smaller than your full partition size (e.g., erasing 1.38MB instead of 5MB). This is normal optimization behavior - Arduino only erases the flash area needed for your current application, not the entire partition. Your 5MB partitions are still correctly configured and available for OTA updates.

Troubleshooting¶

If you get boot errors:

Clear cache:
```
rm -rf ~/Library/Caches/arduino
```

Complete erase (if needed):

find ~/Library/Arduino15/packages/esp32/tools -name "esptool.py" -exec python3 {} --chip esp32s3 --port /dev/cu.usbserial-* erase_flash \;

Then upload normally using Upload button

Cache Clearing Schedule¶

Clear Arduino cache: - ✅ Before creating partitions.csv - ✅ Before uploading - ✅ Whenever you get unexpected partition behavior - ✅ After any ESP32 platform updates

Command to remember:

rm -rf ~/Library/Caches/arduino