ESP32 Firmware (PlatformIO)

Firmware ESP32 (PlatformIO : Arduino d'abord, ESP-IDF si nécessaire)

Chargez également embedded-c-cpp pour les standards de codage, l'architecture, les tests unitaires et le débogage général. Cette compétence contient les parties spécifiques à l'ESP32.

D'abord, identifier le projet

Trouvez	Où	Pourquoi c'est important
Puce et module exacts (ESP32-WROOM-32E, ESP32-S3-WROOM-1-N16R8, ESP32-C3-MINI-1...)	platformio.ini board =, utilisateur, sérigraphie de la carte	Cœurs, broches, PSRAM, USB, ADC diffèrent beaucoup entre variantes
Framework	framework = arduino, espidf, ou arduino, espidf	Modèle d'API et de configuration
Version du core Arduino (2.x ou 3.x)	Ligne du log de build framework-arduinoespressif32 @ x.y.z, ligne platform =, ou ESP_ARDUINO_VERSION_MAJOR	Plusieurs APIs ont changé en 3.x (LEDC, timers) — du code écrit pour la mauvaise version ne compilera pas
Taille flash / PSRAM	nom du module (N16R8 = 16 Mo flash, 8 Mo PSRAM octal), board_upload.flash_size	Partitions, placement mémoire
Câblage de la carte	utilisateur / schéma	Éviter les broches de strapping et celles utilisées par flash/PSRAM/USB/LEDs

Si la variante est inconnue et que la tâche touche aux broches, périphériques, alimentation ou mémoire, trouvez-la avant d'écrire du code — une broche qui fonctionne sur un S3 peut empêcher un ESP32 classique de démarrer.

Arduino ou ESP-IDF ?

Restez avec Arduino (par défaut)	Passez à ESP-IDF (dans PlatformIO : framework = espidf) ou Arduino + IDF (framework = arduino, espidf)
Prototypes et la plupart des produits	Besoin de modifier les options sdkconfig que le core précompilé d'Arduino n'expose pas (OTA rollback, secure boot, flash encryption, PM auto light-sleep, core-dump-to-flash, paramètres FreeRTOS)
Beaucoup de bibliothèques disponibles	Dernières fonctionnalités IDF, contrôle fin de la mémoire/performance
Itération rapide	Durcissement pour la production

Arduino sur ESP32 fonctionne déjà sur FreeRTOS + ESP-IDF, donc les APIs IDF (esp_*, xTaskCreatePinnedToCore, nvs_*, esp_sleep_*, heap_caps_*) sont utilisables depuis du code Arduino. "Arduino as IDF component" (arduino, espidf) conserve les bibliothèques Arduino et ajoute le contrôle de sdkconfig — c'est la voie de migration habituelle.

Configuration, modèles platformio.ini et modifications d'API 2.x vs 3.x : references/platformio-setup.md.

Règles qui évitent les échecs classiques de l'ESP32

1. Broches : n'utilisez jamais les broches flash (GPIO6–11 sur ESP32), les broches PSRAM (16/17 sur WROVER ; 33–37 sur modules S3 à PSRAM octal) ou les broches USB lorsqu'on utilise l'USB ; traitez les broches de strapping (ESP32 : 0, 2, 5, 12, 15) comme "uniquement avec précaution" — GPIO12 tirée haut au boot empêche les modules flash 3,3 V de démarrer. L'ADC2 ne fonctionne pas lorsque le Wi-Fi est activé (ESP32 classique) : utilisez les broches ADC1. Tableaux complets par variante : references/pins-and-variants.md.
2. Ne bloquez pas loop() ou une tâche pour toujours : les longues boucles while sans delay()/vTaskDelay() déclenchent le watchdog de tâche ; while (WiFi.status() != WL_CONNECTED) doit avoir un timeout.
3. ISR : marquez IRAM_ATTR, gardez-les minuscules, pas de Serial.print, pas de delay, pas d'appels Wi-Fi ; déléguez le travail à une tâche (file d'attente / notification de tâche / drapeau). Variables partagées volatile + section critique (portENTER_CRITICAL_ISR spinlock — l'ESP32 est dual-core).
4. Les piles de tâches sont en octets dans ESP-IDF/Arduino (contrairement aux mots du FreeRTOS standard). Mesurez avec uxTaskGetStackHighWaterMark(NULL) (octets). La pile de loop() Arduino fait 8 Ko par défaut (SET_LOOP_TASK_STACK_SIZE(16 * 1024); pour changer).
5. Alimentation : la transmission Wi-Fi tire des pics de ~300–500 mA. "Brownout detector was triggered" signifie qu'il faut corriger l'alimentation (régulateur, condensateur de découplage, câble) — ne désactivez pas le détecteur de brownout.
6. Heap : évitez la concaténation de String dans des boucles et les new/malloc fréquents (fragmentation au fil des jours) ; préallouez. Vérifiez ESP.getFreeHeap() / heap_caps_get_minimum_free_size(MALLOC_CAP_8BIT) au fil du temps.
7. Usure NVS/flash : n'écrivez pas Preferences/NVS à chaque itération de boucle ; écrivez uniquement lors d'un changement, avec limitation de débit.
8. Opérations irréversibles : le grillage d'eFuse, le secure boot, le chiffrement de la flash en mode release sont permanents. N'exécutez jamais espefuse.py burn_*, n'activez pas ces options dans sdkconfig, et n'exécutez pas erase_flash sur un appareil contenant des données, sans confirmation explicite de l'utilisateur.

Build, upload, moniteur (PlatformIO)

pio run -e <env>                       # build
pio run -e <env> -t upload             # flash par USB/série
pio device monitor -e <env>            # moniteur série (utilise monitor_speed / monitor_filters)
pio run -e <env> -t upload -t monitor  # les deux
pio run -e <env> -t uploadfs           # upload du dossier data/ en tant qu'image LittleFS/SPIFFS
pio run -e <env> -t erase              # efface toute la flash (demande d'abord : efface NVS/infos Wi-Fi)
pio run -e <env> -t menuconfig         # ESP-IDF / arduino+espidf uniquement
pio test -e native                     # tests unitaires hôte (voir embedded-c-cpp)

L'upload échoue avec "Failed to connect / Wrong boot mode detected" → maintenez BOOT (GPIO0 / GPIO9 sur C3), appuyez sur EN/RST, relâchez BOOT ; vérifiez que le câble transporte les données ; fermez toute autre fenêtre de moniteur série qui occupe le port. Confirmez que la carte est connectée et quel port avant d'uploader (pio device list).

En cas de crash ou redémarrage

La sortie série que l'utilisateur peut coller est l'élément de preuve clé. Activez monitor_filters = esp32_exception_decoder et build_type = debug pour que les backtraces soient décodées en fichier:ligne. Consultez ensuite references/panics-and-debug.md pour : les types Guru Meditation (LoadProhibited, StoreProhibited, IllegalInstruction, défaut d'accès Load/Store sur RISC-V), le stack canary, le watchdog de tâche/interruption, les codes rst:, le brownout, les boot loops, le débogage JTAG (debug_tool = esp-builtin sur S3/C3/C6).

Fichiers de référence

Fichier	Lire quand
references/platformio-setup.md	Créer/réparer platformio.ini, choisir la plateforme/version du core, modifications API Arduino 2.x→3.x, PSRAM, USB-CDC série, partitions et système de fichiers, utiliser ESP-IDF dans PlatformIO, sdkconfig
references/pins-and-variants.md	Choisir ou vérifier des broches, comparer ESP32/S2/S3/C3/C6, ADC, touch, broches de réveil en deep-sleep
references/rtos-memory-power.md	Tâches, cœurs, ISR, files d'attente, watchdog, pile/heap/PSRAM, IRAM, sommeil profond/léger, batterie
references/panics-and-debug.md	Tout crash, reset, watchdog, brownout, boot loop, échec d'upload, débogage JTAG, core dumps, raison du reset
references/connectivity-ota-security.md	Robustesse Wi-Fi/BLE, NVS/Preferences, mises à jour OTA et rollback, décisions sur secure boot / chiffrement de la flash