04 · Compiler et transférer un programme

Les deux actions de base pour mettre un programme sur la carte ESP32 : compiler (Build) puis téléverser (Upload).

← Ressources PlatformIO

1. Brancher la carte et vérifier le port

Connecter la carte sur un port USB de l'ordinateur. platformio doit détecter automatiquement le port COM (icône 9 ci-dessous — voir aussi la ressource 02 · Les outils platformio / PlatformIO) :

Si le port n'est pas détecté : vérifier le câble USB (certains câbles ne transmettent que l'alimentation, pas les données), et que le pilote du composant USB-série de la carte est bien installé. Ce composant varie selon la carte (par exemple CP210x, CH340 ou FTDI) — voir la documentation de la carte utilisée pour connaître le pilote correspondant.

2. Compiler (Build)

Cliquer sur Build (icône 2 ci-dessous), dans la barre du bas ou dans le panneau latéral :

Lire le résultat dans le terminal qui s'ouvre en bas de VSCode :

Compiling .pio\build\...\src\main.cpp.o
Linking .pio\build\...\firmware.elf
Building .pio\build\...\firmware.bin
========================= [SUCCESS] =========================

Un [SUCCESS] en vert signifie que le code compile sans erreur. Un [FAILED] en rouge indique une erreur dans le code — généralement une ligne et un message d'erreur précis apparaissent juste au-dessus.

En cas d'échec, exemple oubli d'un ; :

src/main.cpp: In function 'void loop()':
src/main.cpp:71:32: error: expected ';' before 'messageUART'
   71 |   clignotementLedBleueInterne()
      |                                ^
      |                                ;
   72 |     messageUART(intervalleClignotement);
      |     ~~~~~~~~~~~
*** [.pio\build\upesy_wroom\src\main.cpp.o] Error 1
========================= [FAILED] Took 8.40 seconds =========================

Ici, le compilateur signale une erreur ligne 71 (« expected ; before 'messageUART' »), avec le symbole ^ et un ; suggéré juste après clignotementLedBleueInterne() : c'est bien à cet endroit, à la fin de la ligne 71, que le point-virgule manque. La ligne 72 n'apparaît que parce que le compilateur, perturbé par l'erreur précédente, ne reconnaît plus l'appel à messageUART — inutile de s'y attarder.

Toujours regarder la toute première ligne d'erreur. Une seule faute dans le code peut provoquer une cascade de plusieurs messages d'erreur qui semblent sans rapport : les erreurs suivantes ne sont souvent que des conséquences de la première. C'est elle qui indique la vraie ligne à corriger.

Message d'erreur	Cause probable	Solution
`expected ';' before ...`	Point-virgule `;` oublié à la fin de la ligne précédente.	Ajouter le `;` manquant à la ligne indiquée par le compilateur moins une.
`'xxx' was not declared in this scope`	Nom de variable ou de fonction mal orthographié, ou `#include` manquant.	Vérifier l'orthographe exacte (majuscules/minuscules) et que le fichier `.h` correspondant est bien inclus.
`expected '}' at end of input`	Accolade `{` ouvrante sans accolade `}` fermante correspondante.	Vérifier que chaque `{` a bien son `}` — utiliser l'indentation ou le clic sur une accolade dans VSCode pour repérer sa paire.
`redefinition of 'xxx'`	Une même variable ou fonction est déclarée deux fois.	Supprimer la déclaration en double.
`No such file or directory`	Le fichier indiqué dans un `#include "..."` n'existe pas ou son nom est mal orthographié.	Vérifier le nom exact du fichier (avec l'extension `.h`) et son emplacement dans `include`.
`'lib_name' does not name a type`	Bibliothèque non incluse ou mal installée.	Vérifier le `#include` correspondant et la section `lib_deps` du `platformio.ini`.

3. Téléverser (Upload)

Cliquer sur Upload (icône 3 ci-dessous). platformio recompile si besoin, puis transfère le programme sur la carte via le port sélectionné :

Uploading .pio\build\...\firmware.bin
...
========================= [SUCCESS] =========================

Pendant le transfert, une LED de la carte clignote généralement plus vite : c'est normal, ne pas débrancher la carte à ce moment-là.

En cas d'échec, un message d'erreur apparaît dans le terminal, par exemple si le port COM est déjà utilisé par un autre programme :

A serial exception error occurred: Cannot configure port, something went wrong. Original message: PermissionError(13, 'Accès refusé.', None, 5)
Note: This error originates from pySerial. It is likely not a problem with esptool, but with the hardware connection or drivers.
For troubleshooting steps visit: https://docs.espressif.com/projects/esptool/en/latest/troubleshooting.html
*** [upload] Error 1
========================= [FAILED] Took 9.49 seconds =========================

Symptôme	Cause probable	Solution
« Could not find a JLink »	Une carte différente était sélectionnée précédemment.	Vérifier la ligne `board` du `platformio.ini`.
« Failed to connect to ESP32 » / timeout	Port COM incorrect, câble d'alimentation seul, ou carte déjà utilisée.	Rebrancher la carte, vérifier le port (voir 02 · Les outils…), fermer tout moniteur série déjà ouvert.
« PermissionError(13, 'Accès refusé.'…) »	Le port COM est déjà ouvert par un autre programme (moniteur série, Arduino IDE, PuTTY, une autre fenêtre VSCode…).	Fermer le ou les programmes qui utilisent ce port, puis relancer Upload.
Le moniteur série reste ouvert et bloque l'upload	Le port COM est occupé par le moniteur série.	Fermer le moniteur série avant de relancer Upload.
Upload très lent ou qui échoue au milieu	Câble USB de mauvaise qualité ou port USB défectueux.	Essayer un autre câble ou un autre port USB.