ESP32-Firmware

ESP32-Firmware (PlatformIO: Arduino zuerst, ESP-IDF bei Bedarf)

Lade auch embedded-c-cpp für Codierungsstandards, Architektur, Unit-Tests und allgemeines Debugging. Dieses Skill enthält die ESP32-spezifischen Teile.

Zuerst: Projekt identifizieren

Finden	Wo	Warum es wichtig ist
Exakter Chip und Modul (ESP32-WROOM-32E, ESP32-S3-WROOM-1-N16R8, ESP32-C3-MINI-1...)	platformio.ini board =, Benutzer, Board-Siebdruck	Cores, Pins, PSRAM, USB, ADC unterscheiden sich stark zwischen Varianten
Framework	framework = arduino, espidf oder arduino, espidf	API und Konfigurationsmodell
Arduino-Core-Version (2.x oder 3.x)	Build-Log-Zeile framework-arduinoespressif32 @ x.y.z, platform =-Zeile oder ESP_ARDUINO_VERSION_MAJOR	Mehrere APIs haben sich in 3.x geändert (LEDC, Timer) – Code, der für die falsche Version geschrieben wurde, kompiliert nicht
Flash-/PSRAM-Größe	Modulname (N16R8 = 16 MB Flash, 8 MB oktales PSRAM), board_upload.flash_size	Partitionen, Speicherplatzierung
Board-Verdrahtung	Benutzer/Schaltplan	Strapping-Pins und Pins, die von Flash/PSRAM/USB/LEDs verwendet werden, vermeiden

Wenn die Variante unbekannt ist und die Aufgabe Pins, Peripherie, Strom oder Speicher betrifft, finde sie heraus, bevor du Code schreibst – ein Pin, der auf einem S3 in Ordnung ist, kann einen klassischen ESP32 am Booten hindern.

Arduino oder ESP-IDF?

Bei Arduino bleiben (Standard)	Zu ESP-IDF wechseln (in PlatformIO: framework = espidf) oder Arduino + IDF (framework = arduino, espidf)
Prototypen und die meisten Produkte	sdkconfig-Optionen ändern müssen, die der vorkompilierte Arduino-Core nicht freigibt (Rollback-OTA, Secure Boot, Flash-Verschlüsselung, PM Auto Light-Sleep, Core-Dump-to-Flash, FreeRTOS-Einstellungen)
Viele Bibliotheken verfügbar	Neueste IDF-Funktionen, strenge Kontrolle von Speicher/Leistung
Schnelle Iteration	Produktionshärtung

Arduino auf ESP32 läuft bereits auf FreeRTOS + ESP-IDF, daher funktionieren IDF-APIs (esp_*, xTaskCreatePinnedToCore, nvs_*, esp_sleep_*, heap_caps_*) aus Arduino-Code. „Arduino als IDF-Komponente“ (arduino, espidf) behält Arduino-Bibliotheken und fügt sdkconfig-Kontrolle hinzu – der übliche Migrationspfad.

Setup, platformio.ini-Vorlagen und die API-Änderungen von 2.x vs. 3.x: references/platformio-setup.md.

Regeln, die die klassischen ESP32-Fehler verhindern

1. Pins: Niemals Flash-Pins (GPIO6–11 auf ESP32), PSRAM-Pins (16/17 auf WROVER; 33–37 auf S3-Oktal-PSRAM-Modulen) oder USB-Pins bei Verwendung von USB verwenden; Strapping-Pins (ESP32: 0, 2, 5, 12, 15) nur mit Vorsicht behandeln – GPIO12 bootet bei High-Pegel bei 3,3-V-Flash-Modulen nicht. ADC2 funktioniert bei eingeschaltetem WLAN nicht (klassischer ESP32): ADC1-Pins verwenden. Vollständige Tabellen pro Variante: references/pins-and-variants.md.
2. loop() oder eine Task nicht für immer blockieren: Lange while-Schleifen ohne delay()/vTaskDelay() lösen den Task-Watchdog aus; while (WiFi.status() != WL_CONNECTED) benötigt ein Timeout.
3. ISRs: Mit IRAM_ATTR markieren, winzig halten, kein Serial.print, kein delay, keine WLAN-Aufrufe; Arbeit an eine Task delegieren (Queue / Task-Notification / Flag). Gemeinsame Variablen volatile + kritischer Abschnitt (portENTER_CRITICAL_ISR-Spinlock – der ESP32 ist Dual-Core).
4. Task-Stacks sind in Bytes in ESP-IDF/Arduino (anders als Vanilla-FreeRTOS in Wörtern). Mit uxTaskGetStackHighWaterMark(NULL) (Bytes) messen. Arduino loop() hat standardmäßig 8 KB (SET_LOOP_TASK_STACK_SIZE(16 * 1024); zum Ändern).
5. Stromversorgung: WLAN TX zieht ~300–500 mA Spitzen. „Brownout detector was triggered“ bedeutet, die Stromversorgung zu reparieren (Regler, Stützkondensator, Kabel) – den Brownout-Detektor nicht deaktivieren.
6. Heap: String-Verkettung in Schleifen und häufiges new/malloc vermeiden (Fragmentierung über Tage); vorab zuweisen. ESP.getFreeHeap() / heap_caps_get_minimum_free_size(MALLOC_CAP_8BIT) über die Zeit prüfen.
7. NVS/Flash-Verschleiß: Preferences/NVS nicht bei jeder Schleifeniteration schreiben; bei Änderung mit Ratenbegrenzung schreiben.
8. Irreversible Vorgänge: eFuse-Brennen, Secure Boot, Flash-Verschlüsselung im Release-Modus sind dauerhaft. Niemals espefuse.py burn_* ausführen, diese in sdkconfig aktivieren oder erase_flash auf einem Gerät mit Daten ohne explizite Benutzerbestätigung durchführen.

Build, Upload, Monitor (PlatformIO)

pio run -e <env>                       # bauen
pio run -e <env> -t upload             # über USB/Seriell flashen
pio device monitor -e <env>            # Serieller Monitor (verwendet monitor_speed / monitor_filters)
pio run -e <env> -t upload -t monitor  # beides
pio run -e <env> -t uploadfs           # data/-Ordner als LittleFS/SPIFFS-Image hochladen
pio run -e <env> -t erase              # gesamten Flash löschen (fragt zuerst: löscht NVS/WLAN-Zugangsdaten)
pio run -e <env> -t menuconfig         # nur ESP-IDF / arduino+espidf
pio test -e native                     # Host-Unit-Tests (siehe embedded-c-cpp)

Upload schlägt fehl mit „Failed to connect / Wrong boot mode detected“ → BOOT (GPIO0 / GPIO9 auf C3) gedrückt halten, EN/RST antippen, BOOT loslassen; prüfen, ob das Kabel Daten überträgt; jeden anderen seriellen Monitor schließen, der den Port belegt. Bestätigen, dass das Board angeschlossen ist und welcher Port vor dem Hochladen verwendet wird (pio device list).

Wenn es abstürzt oder neu startet

Einfügbarer serieller Output ist der wichtigste Beweis. Aktiviere monitor_filters = esp32_exception_decoder und build_type = debug, damit Backtraces in Datei:Zeile dekodiert werden. Siehe dann references/panics-and-debug.md für: Guru-Meditation-Typen (LoadProhibited, StoreProhibited, IllegalInstruction, Load/Store-Zugriffsfehler auf RISC-V), Stack-Canary, Task-/Interrupt-Watchdog, rst:-Codes, Brownout, Boot-Schleifen, JTAG-Debugging (debug_tool = esp-builtin auf S3/C3/C6).

Referenzdateien

Datei	Lesen, wenn
references/platformio-setup.md	Erstellen/Reparieren von platformio.ini, Auswahl der Plattform/Core-Version, API-Änderungen Arduino 2.x→3.x, PSRAM, USB-CDC-Seriell, Partitionen & Dateisystem, Verwenden von ESP-IDF in PlatformIO, sdkconfig
references/pins-and-variants.md	Auswählen oder Überprüfen von Pins, Vergleichen von ESP32/S2/S3/C3/C6, ADC, Touch, Deep-Sleep-Weckpins
references/rtos-memory-power.md	Tasks, Cores, ISRs, Queues, Watchdog, Stack/Heap/PSRAM, IRAM, Deep/Light Sleep, Batterie
references/panics-and-debug.md	Jeglicher Absturz, Reset, Watchdog, Brownout, Boot-Schleife, Upload-Fehler, JTAG-Debug, Core-Dumps, Reset-Grund
references/connectivity-ota-security.md	Wi-Fi/BLE-Robustheit, NVS/Preferences, OTA-Updates und Rollback, Secure Boot / Flash-Verschlüsselungsentscheidungen