Programmer un ESP8266

Ce document couvre tout le cycle de programmation d’un microcontrôleur, en partant d’un Linux Mint neuf où rien n’est installé : préparer le PC → comprendre les fichiers du projet → écrire/modifier le code → compiler → transférer (« flasher ») dans la carte.

Si vous débutez, lisez tout dans l’ordre. Les habitués peuvent sauter directement à « Compiler ».

Comprendre le projet (avant d’écrire du code)

Qu’est-ce que « programmer » ici ?

Un ESP8266 n’a pas de disque ni de système d’exploitation. On y installe un seul programme (le firmware) qui démarre tout seul à la mise sous tension et tourne en boucle jusqu’à la coupure du courant. « Programmer la carte » veut donc dire :

1. écrire le code source sur le PC (fichiers .cpp / .h),
2. le compiler : le PC traduit le C++ en un fichier binaire firmware.bin compréhensible par la puce,
3. le flasher : on transfère ce .bin dans la mémoire flash de l’ESP par le câble USB.

On ne « code » jamais directement sur la carte : on édite sur le PC puis on reflashe. C’est le cycle éditer → compiler → flasher → tester que l’on répète.

L’outil de build : PlatformIO

Le projet en cours utilise PlatformIO, qui automatise tout : il télécharge le compilateur pour l’ESP8266, récupère les bibliothèques, compile et flashe. Une seule commande (pio run -t upload) enchaîne compilation + transfert.

Les fichiers du projet et leur rôle

Prenons le projet “relais” :

relais/
├── platformio.ini     # 1. recette de compilation (carte, bibliothèques, options)
├── include/
│   └── config.h       # 2. réglages « en dur » : brochage + valeurs par défaut
├── src/
│   └── main.cpp       # 3. le programme lui-même (la logique)
└── docs/              # documentation

Pour programmer (au sens : produire un firmware qui fonctionne), il faut au minimum ces trois fichiers. Voici précisément à quoi sert chacun :

1. platformio.ini — la recette de build. C’est le fichier que PlatformIO lit en premier. Il déclare :

• board = nodemcuv2 : le modèle de carte (profil compatible Wemos/NodeMCU ESP-12E) ;
• framework = arduino : on programme avec l’API Arduino (setup(), loop(), digitalWrite()…) ;
• lib_deps : les bibliothèques externes à télécharger automatiquement (WiFiManager, PubSubClient, ArduinoJson) — inutile de les installer à la main ;
• build_flags, monitor_speed, etc. : les options fines.

Sans ce fichier, PlatformIO ne sait ni pour quelle puce compiler, ni quelles bibliothèques chercher.

2. include/config.h — les réglages de compilation. Un fichier d’en-tête (.h) qui regroupe des #define : nombre de relais, brochage GPIO, logique active-bas, valeurs par défaut MQTT, mots de passe par défaut… Ce sont des constantes figées au moment de la compilation. On y touche pour adapter le firmware au matériel (ex. : passer de GPIO direct à MCP23017 via #define USE_MCP23017 1). Les paramètres réseau/MQTT, eux, se règlent plutôt au runtime via le portail captif.

3. src/main.cpp — le programme. C’est ici que vit la logique. Tout programme Arduino repose sur deux fonctions obligatoires :

void setup() {
  // Exécuté UNE fois au démarrage : on initialise le WiFi, le MQTT,
  // les broches des relais, le serveur web, etc.
}

void loop() {
  // Exécuté EN BOUCLE, indéfiniment : on traite les messages MQTT,
  // on répond aux requêtes web, on publie la télémétrie…
}

Le fichier commence par des #include (ses dépendances), puis déclare des variables globales, des fonctions, et enfin ces deux fonctions. Le #include "config.h" en haut de main.cpp est ce qui rend les #define du fichier (2.) visibles dans le programme.

💡 Où sont les bibliothèques ? Elles ne sont pas dans le dépôt : elles sont listées dans platformio.ini (lib_deps) et téléchargées à la première compilation dans le dossier .pio/ (ignoré par git). C’est normal de ne pas les voir dans src/.

Préparer le PC (Linux Mint, installation depuis zéro)

On suppose une machine Linux Mint fraîche. Trois choses à installer : les outils Python, PlatformIO, puis les droits d’accès au port USB.

1. Outils système (Python, venv, git)

Ouvrez un terminal (Ctrl+Alt+T) :

sudo apt update
sudo apt install -y python3 python3-venv python3-pip git

• python3 / python3-venv : PlatformIO est écrit en Python ; le venv permet de l’installer proprement, isolé du système.
• git : pour récupérer ce dépôt (et pratique au quotidien).

2. Récupérer le projet

cd ~
git clone <url-du-depot> relais   # ou copiez le dossier du projet ici
cd relais

3. Installer PlatformIO Core (CLI)

La méthode recommandée est un environnement virtuel Python dédié. Il fournit la commande pio sans polluer le système :

python3 -m venv ~/pioenv
~/pioenv/bin/pip install -U pip
~/pioenv/bin/pip install -U platformio

Pour taper simplement pio au lieu du chemin complet, ajoutez un alias permanent à votre shell :

echo "alias pio='~/pioenv/bin/pio'" >> ~/.bashrc
source ~/.bashrc

Vérifiez que tout est en place :

pio --version        # doit afficher « PlatformIO Core, version 6.x »

ℹ️ Alternative sans venv : pip install --user platformio fonctionne aussi, mais le venv évite les conflits de versions et se supprime d’un simple rm -rf ~/pioenv. C’est la méthode la plus sûre pour débuter.

ℹ️ La plateforme espressif8266 (compilateur + SDK) n’est pas à installer à la main : PlatformIO la télécharge automatiquement à la première compilation, en lisant platform = espressif8266 dans platformio.ini. Prévoyez quelques minutes et une connexion Internet pour ce premier pio run.

4. Droits d’accès au port USB (règle udev + groupe dialout)

Sous Linux, un utilisateur normal n’a pas le droit d’écrire sur les ports série (/dev/ttyUSB*, /dev/ttyACM*). Sans ça, le flash échoue avec « permission denied ». Ajoutez-vous au groupe dialout :

sudo usermod -aG dialout $USER

⚠️ Déconnectez-vous puis reconnectez-vous (ou redémarrez) pour que l’appartenance au groupe prenne effet.

PlatformIO peut aussi installer les règles udev officielles, utile si la carte n’est pas détectée automatiquement :

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core/master/platformio/assets/system/99-platformio-udev.rules \
  | sudo tee /etc/udev/rules.d/99-platformio-udev.rules
sudo udevadm control --reload-rules
sudo udevadm trigger

5. Pilote de la puce USB-série (CP210x / CH340)

La carte Wemos/NodeMCU communique via une puce USB→série. Les pilotes sont inclus dans le noyau Linux : en général, rien à installer. Pour vérifier, branchez la carte puis :

dmesg | tail -n 20

Vous devriez voir apparaître un périphérique comme cp210x converter now attached to ttyUSB0 (puce CP2102) ou ch341-uart ... ttyUSB0 (puce CH340). Si un port /dev/ttyUSB0 (ou /dev/ttyACM0) apparaît, tout est bon.

🛠️ Si aucun port n’apparaît : essayez un autre câble USB (certains sont « charge seule », sans fils de données), ou un autre port USB.

Écrire ou modifier le code (le cycle)

Ouvrez le projet dans un éditeur. VS Code + extension PlatformIO offre l’autocomplétion et des boutons build/upload, mais n’importe quel éditeur texte convient. Le cycle est toujours le même :

1. Modifier — par ex. dans config.h, changer le nombre de relais par défaut :

   #define DEFAULT_RELAY_COUNT 4   // au lieu de 8

2. Compiler pour vérifier que ça build sans erreur (voir ci-dessous) ;
3. Flasher sur la carte ;
4. Tester via la console série et l’interface web.

Si le compilateur signale une erreur, il indique le fichier et la ligne : corrigez, puis recompilez. Rien n’est envoyé à la carte tant que la compilation n’a pas réussi.

Compiler

Depuis le dossier du projet (~/relais) :

pio run

La première exécution télécharge la plateforme espressif8266 et les bibliothèques (lib_deps) : c’est plus long. Les fois suivantes sont rapides.

Sortie attendue (extrait) :

RAM:   [====      ]  38.8% (used 31768 bytes from 81920 bytes)
Flash: [====      ]  38.5% (used 401679 bytes from 1044464 bytes)
========================= [SUCCESS] =========================

Le firmware produit se trouve dans .pio/build/nodemcuv3/firmware.bin.

Flasher (upload)

Carte branchée en USB :

pio run -t upload

Cette commande compile puis transfère dans la foulée. Si le port n’est pas auto-détecté, précisez-le dans platformio.ini :

upload_port  = /dev/ttyUSB0
monitor_port = /dev/ttyUSB0

Si vous obtenez « permission denied » sur /dev/ttyUSB0, c’est l’étape 4 ci-dessus (groupe dialout) qui n’a pas encore pris effet : reconnectez-vous.

Console série (logs)

pio device monitor

Vitesse : 115200 bauds (déjà fixée par monitor_speed dans platformio.ini). Quitter : Ctrl+C.

Logs typiques au démarrage :

=== relais8 — démarrage ===
[SYS] deviceId = a1b2c3
[FS] Config chargée.
[WiFi] Connecté, IP = 192.168.1.42
[MQTT] Connexion à 192.168.1.10:1883 ...
[MQTT] Connecté.
[HA] discovery relay1 OK
...

Lister les ports / cartes détectées

pio device list

Mise à jour OTA (sans câble, après un premier flash USB)

Le firmware peut ensuite être mis à jour par le réseau WiFi. Décommentez le bloc espota dans platformio.ini :

upload_protocol = espota
upload_port     = relais8_<chipid>.local   ; ou l'IP de la carte
upload_flags    = --auth=relais1234        ; doit correspondre à OTA_PASSWORD

puis relancez pio run -t upload.

Nettoyer le build

pio run -t clean

Effacer entièrement la flash (réinitialisation totale)

Efface aussi la config WiFi/MQTT sauvegardée dans LittleFS :

pio run -t erase