PlatformIO est une alternative à l’IDE Arduino permettant de développer des objets connectés ou du code pour micro-contrôleur d’une manière plus générale. PlatformIO n’est pas un éditeur de code, c’est un ensemble d’outils (toolchains) sous la forme de plugin pour Visual Studio Code (ou VSCode) de Microsoft et Atom de GitHub (également Microsoft !). VSCode est un éditeur de code léger et gratuit pour Windows, macOS, Linux (32 ou64-bits). 

PlatformIO est disponible sour la forme d’un plugin pour la plupart des éditeurs de code (Atom, CLion, CodeBlocks, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, Vim, Visual Studio, VSCode) ainsi que pour les éditeurs en ligne Cloud9, Codeanywhere et Eclipse Che

VSCode est un éditeur de code léger et gratuit qui conviendra parfaitement à tous les usages, du simple bricolage à un usage professionnel. Il est disponible sur tous les environnements (y compris 32-bits).

Installer Visual Studio Code (VSCode) pour Windows, macOS ou Linux

Rendez-vous sur la page officielle de VSCode pour télécharger et installer la version qui correspond à votre environnement.

Normalement, le navigateur reconnait automatiquement votre système d’exploitation. Si ce n’est pas le cas, cliquez sur la flèche située à droite du bouton Download pour choisir la version à télécharger

• Windows : installer ou ZIP
• macOS : package dmg
• Linux 32-bits : .deb, .rpm, .tag.gz
• Linux 64-bits : .deb, .rpm, .tag.gz

Installer le package PlatformIO IDE pour VSCode

VSCode dispose d’un gestionnaire d’extension (plugin) que l’on ouvre via le menu Affichage -> Extension ou directement depuis l’icône située dans la barre latérale.

Saisissez platformio dans le champ de recherche. Cliquez sur Install pour démarrer l’installation du plugin et des dépendances.

Le processus d’installation se déroule en arrière plan, c’est un peu perturbant lorsqu’on découvre VSCode. Une fenêtre située en bas à droite de l’écran permet de suivre le bon déroulement de l’installation. C’est assez rare mais si vous rencontrez un problème d’installation (ou un blocage), il suffit de relancer VSCode pour reprendre le processus d’installation.

Petite astuce au passage, VSCode ayant un fonctionnement très similaire à Sublime Text (les bonnes idées sont souvent copiées…) vous pouvez également convoquez le gestionnaire d’extension avec la combinaison de touches CTRL + P (Ou Cmd + P sous macOS).

Premier démarrage de PlatformIO sur VSCode

A la fin de l’installation, il n’est pas nécessaire de redémarrer l’éditeur. La page d’accueil de PIO s’ouvre dans un nouvel onglet ➀. Cette page ralenti fortement le démarrage de VSCode et n’apporte rien d’utile. Je vous conseille de désactiver son ouverture au démarrage en décochant l’option Show at startup ➁.

Une nouvelle icône sous la forme d’une tête de fourmi fait son apparition dans la barre latérale ➂. Elle permet d’accéder à toutes les fonctionnalités de PIO. Nous allons les détailler un peu plus tard.

Enfin, une mini barre d’outil ➃ apparait dans le bas de l’écran. C’est une version allégée du menu PIO ➂. Elle regroupe les fonctions suivantes

• Errors signale les problèmes de compilation
• Home ouvre la fenêtre d’accueil de PIO. Utile lorsqu’on veut importer ou créer un nouveau projet
• Build compile le code du projet. Permet de vérifier s’il y a des erreurs
• Upload compile et téléverse le projet. La détection est automatique mais il est aussi possible de spécifier le port dans le fichier de configuration
• Upload to remote device idem mais sur un MCU distant. Un compte PIO (payant ou limité dans l’offre gratuite) est  nécessaire
• Clean supprime le dossier build. Ne pas hésiter en cas de problème. N’a aucun impact sur le code source du projet
• Test pour tester le code avant de le compiler
• Run Task ouvre la palette de commande de VSCode
• Serial Monitor ouvre le moniteur série
• Terminal ouvre un Terminal directement dans VSCode ou Power Shell sous Windows. On est directement positionné à la racine du projet

Pour ceux qui préfèrent utiliser les raccourcis clavier,  vous pouvez convoquer la palette avec la combinaison de touche Ctrl + Shift + P (ou Cmd + ↑ + P sur macOS). Saisissez ensuite le mot clé platformio pour afficher toutes les commandes disponibles

Le menu PIO

Revenons au menu PIO qui est le moyen le plus simple et le plus complet pour utiliser PIO. Il est en permanence accessible depuis la barre latérale. Elle regroupe toutes les fonctions de PIO.

Voici les commandes les plus utiles :

Build compiler

Upload compile et téléverse le programme

Monitor ouvre le moniteur série

Upload and monitor compile, téléverse et ouvre le moniteur série

Upload File System image téléverse les fichiers du dossier data stockés au format SPIFFS ou LittleFS.

Erase Flash vide la mémoire flash de la carte de développement

Devices Liste les devices connectés

Clean efface le dossier build

Update project libraries met à jour les librairies utilisées par le projet

Créer un nouveau projet (Arduino, ESP32, ESP8266…)

Il est temps de passer à un petit exemple pour tester tout ça. Ouvrez la fenêtre d’accueil de PIO (si nécessaire) et cliquez sur + New Project pour ouvrir l’assistant de création de projet

Nommer le projet puis sélectionnez la carte de développement dans la liste. La liste est impressionnante. Vous pouvez saisir les premières lettre du fabricant (WeMos, TTGO), celle de la carte (d1 mini), le type (ESP32, ESP8266…) pour filtrer les cartes

Laissez Arduino dans le framework. En fonction de votre carte, vous pourrez opter pour un autre framework, mais dans ce cas il faudra vous reporter à la documentation de ce dernier pour la programmation.

Enfin, choisissez le répertoire de création du projet. Si vous cochez Use Default Location, le projet sera créé dans le dossier Documents / PlatformIO / Projects. Le nom de répertoire portera le nom du projet. Cliquez sur Finish pour lancer l’initialisation du projet. L’opération ne dure qu’une poignée de secondes.

Le projet est maintenant accessible depuis l’explorateur

Le dossier contient plusieurs dossiers et fichiers de configuration.

• .pio est un dossier (caché) qui contient les builds. Ce sont les fichiers binaires générés par le compilateur. Un sous-dossier est créé par cible (carte de développement)
• lib est le dossier dans lequel seront installées les librairies nécessaires au projet. Cela permet de mieux gérer les problèmes de versions d’un projet à l’autre. Par contre, attention à la consommation d’espace disque.
• src. Ce dossier contient le code source de votre projet. C’est votre dossier de travail
• platformio.ini est le fichier de configuration de PIO

Ouvrez le fichier main.cpp qui se trouve dans le dossier src (source). Comme vous pouvez le constater, il faut déclarer la librairie Arduino.h lorsqu’on développe du code Arduino sous PIO.

#include "Arduino.h"

void setup(){
}

void loop(){
}

Remplacez ce code par le code blink et enregistrer la modification

#include "Arduino.h"

void setup() {
   // initialize digital pin LED_BUILTIN as an output.
   pinMode(LED_BUILTIN, OUTPUT);
}

// the loop function runs over and over again forever
void loop() {
   digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
   delay(1000); // wait for a second
   digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
   delay(1000); // wait for a second
}

Décryptage du fichier platformio.ini

Découvrons maintenant pour décrypter ce que contient le fichier de configuration platformio.ini qui ce trouve à la racine du projet.

La force de PIO est de pouvoir compiler un même code (projet) vers autant de cibles (cartes de développement, MCU) que l’on souhaite. La configuration de chaque carte se fait par bloc qui commence par la clé env: entre crochets, par exemple [env:esp12e] pour la LoLin d1 mini. Il faut 3 paramètres pour définir complètement une carte :

• Platform qui correspond au SoC utilisé par la carte (ESP32, ESP8266, Atmel AVR, STM32…). La liste complète est ici
• Board, la carte de développement. La liste complète se trouve ici
• Framework, l’environnement logiciel qui fera fonctionner le code du projet. Attention, chaque SoC n’est compatible qu’avec un nombre limité de framework. La liste se trouve ici.

[env:esp12e]               ## Début de configuration pour la carte de développement
platform = espressif8266   
board = esp12e
framework = arduino

On pourra ensuite spécifier d’autres paramètres, par exemple

upload_port, spécifier le port COM

• /dev/ttyUSB0 – port série sur les systèmes basés sur Linux (ou macOS)
• COM3 – port série sur Windows
• 192.168.0.13 – adresse IP pour la mise à jour sans fil en WiFi (OTA) 

upload_speed, spécifier la vitesse de transfert en baud

monitor_speed, vitesse du moniteur série

Plus d’options ici

Pour ajouter une nouvelle carte de développement, je vous conseille de récupérer directement la configuration de votre carte sur le WiKi officiel plutôt que d’utiliser l’assistant de configuration. Plus de 850 cartes de développement sont déjà répertoriées. Vous n’aurez pas à tâtonner pour trouver les bon réglages comme pour cette carte Heltec ESP32 avec connectivité LoRa qui existe en 2 versions.

Compiler depuis PlatformIO

Maintenant que tout est près, vous pouvez lancer la création du build depuis le menu PIO

ou depuis la palette d’outil

Pour une raison qui m’échappe encore, le test et la vérification du code (check) se termine par un message d’erreur.

Contrairement à l’IDE Arduino, il n’est pas obligatoirement nécessaire d’installer les librairies avant de compiler. PIO s’occupe de tout du moment que les dépendances sont correctement indiquées dans le fichier ini.

Un Terminal s’ouvre en dessous du code et indique la progression de la compilation. Le temps de compilation est identique à l’IDE Arduino.

Si tout s’est déroulé sans erreur, vous devez obtenir un message de [success]

Linking .pio/build/esp12e/firmware.elf
Retrieving maximum program size .pio/build/esp12e/firmware.elf
Checking size .pio/build/esp12e/firmware.elf
Building .pio/build/esp12e/firmware.bin
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM: [=== ] 32.7% (used 26816 bytes from 81920 bytes)
Flash: [== ] 24.6% (used 257212 bytes from 1044464 bytes)
Creating BIN file ".pio/build/esp12e/firmware.bin" using ".pio/build/esp12e/firmware.elf"
======================================================== [SUCCESS] Took 32.26 seconds ====

Vérifier que la carte de développement est correctement détectée

Sur l’IDE Arduino, il suffit d’aller dans le menu Outils -> Port pour savoir si la carte de développement à été détectée.

Sur PIO, une fonction équivalente est disponible. Ouvrez la page d’accueil de PIO et ouvrez l’onglet Devices (appareils). Les cartes sont automatiquement détectée est apparaissent dans le liste (ici sur un Mac). Si ce n’est pas le cas, utilisez le bouton Refresh pour forcer la détection des devices.

Petite rappel au passage, si vous rencontrez des difficultés pour téléverser le programme sur la carte, il est possible de spécifier le port et la vitesse de transfert dans la configuration (voir plus haut)

Téléverser un programme sur une carte de développement (Arduino, ESP8266, ESP32, STM32…)

Tout est prêt pour téléverser le programme sur la carte de développement. Comme précédemment, la méthode Upload est accessible depuis la palette ou depuis le menu PIO

PIO compile le projet, se connecte à la carte et téléverse le binaire.

> Executing task in folder Demo ESP8266: platformio run --target upload <

Warning! Ignore unknown configuration option `upload_serial` in section [env:esp12e]
Processing esp12e (platform: espressif8266; board: esp12e; framework: arduino)
----------------------------------------------------------------------------------------------------------------------------------------------
Verbose mode can be enabled via `-v, --verbose` option
CONFIGURATION: https://docs.platformio.org/page/boards/espressif8266/esp12e.html
PLATFORM: Espressif 8266 2.5.1 > Espressif ESP8266 ESP-12E
HARDWARE: ESP8266 80MHz, 80KB RAM, 4MB Flash
PACKAGES: 
- framework-arduinoespressif8266 3.20701.0 (2.7.1) 
- tool-esptool 1.413.0 (4.13) 
- tool-esptoolpy 1.20800.0 (2.8.0) 
- tool-mkspiffs 1.200.0 (2.0) 
- toolchain-xtensa 2.40802.200502 (4.8.2)
LDF: Library Dependency Finder -> http://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 30 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Retrieving maximum program size .pio/build/esp12e/firmware.elf
Checking size .pio/build/esp12e/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM: [=== ] 32.7% (used 26816 bytes from 81920 bytes)
Flash: [== ] 24.6% (used 257212 bytes from 1044464 bytes)
Configuring upload protocol...
AVAILABLE: espota, esptool
CURRENT: upload_protocol = esptool
Looking for upload port...
Auto-detected: /dev/cu.usbserial-1410
Uploading .pio/build/esp12e/firmware.bin
esptool.py v2.8
Serial port /dev/cu.usbserial-1410
Connecting....
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 5c:cf:7f:85:e6:20
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Compressed 261360 bytes to 192964...

Writing at 0x00000000... (8 %)
Writing at 0x00004000... (16 %)
Writing at 0x00008000... (25 %)
Writing at 0x0000c000... (33 %)
Writing at 0x00010000... (41 %)
Writing at 0x00014000... (50 %)
Writing at 0x00018000... (58 %)
Writing at 0x0001c000... (66 %)
Writing at 0x00020000... (75 %)
Writing at 0x00024000... (83 %)
Writing at 0x00028000... (91 %)
Writing at 0x0002c000... (100 %)
Wrote 261360 bytes (192964 compressed) at 0x00000000 in 18.6 seconds (effective 112.6 kbit/s)...
Hash of data verified.

Leaving...
Hard resetting via RTS pin...
================================ [SUCCESS] Took 23.11 seconds ==============================

Problèmes fréquents

Impossible de téléverser

esptool.py n’arrive pas à se connecter à la carte

Looking for upload port...
Auto-detected: /dev/cu.usbserial-1420
Uploading .pio/build/esp12e/firmware.bin
esptool.py v2.8
Serial port /dev/cu.usbserial-1420
Connecting........_____....._____....._____....._____....._____....._____....._____

A fatal error occurred: Failed to connect to ESP8266: Timed out waiting for packet header
*** [upload] Error 2
============================= [FAILED] Took 27.38 seconds ===================

Causes et remèdes possibles :

• Le module n’est pas en mode booltload ou n’a pas reçu la demande. Remèdes à tester :
  • Faire un reset
  • Débrancher / rebrancher / recommencer l’upload
  • Idem en changeant la câble USB
  • Idem sur un autre port USB
  • Effacer la mémoire flash
  • Vérifier si la carte est détectée dans les devices
  • Tester avec un autre module…si ça ne toujours pas après plusieurs tentatives, envisager de remplacer le module

Impossible de se connecteur avec le Moniteur Série

Par défaut, le port série est configuré à 9600 bauds sur l’extension officielle. Jun Han a ajouté un paramètre permettant de définir la vitesse. Pour utiliser un vitesse différente, ouvrez le Terminal et exécutez la commande suivante pio device monitor -b 115200.

Vous pouvez aussi spécifier la vitesse dans le fichier plaformio.ini à l’aide de l’option monitor_speed.

Désactiver PlatformIO

PIO peut ralentir le démarrage de VSCode. Si vous en avez une utilisation ponctuelle, vous pouvez le désactiver depuis le gestionnaire d’extension. Activez le lorsque vous avez besoin des fonctionnalités de PIO. Le chargement se fait à chaud, pas besoin de relancer VSCode !

Installer les outils en ligne de commande (CLI) de PlatformIO

Le package PIO pour VSCode (et les autres éditeurs) est autonome. Cependant, il ne permet pas d’accéder à tous les outils proposés par PIO, notamment la connexion au compte utilisateur nécessaire pour utiliser les outils de debug.

Il est nécessaire d’installer le CLI (Command-line interface ou interface en ligne de commande en français) manuellement.

Voici comment faire en fonction de votre ordinateur. Tout est expliqué ici

python get-platformio.py

python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/develop/scripts/get-platformio.py)"

curl -fsSL https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -o get-platformio.py
python3 get-platformio.py

wget https://raw.githubusercontent.com/platformio/platformio-core-installer/master/get-platformio.py -O get-platformio.py
python3 get-platformio.py

Une fois le Core installé, vous pouvez accéder à toutes les commandes de PIO depuis une fenêtre de Terminal sous VSCode.

pio -h
Usage: pio [OPTIONS] COMMAND [ARGS]...

Options:
  --version          Show the version and exit.
  -f, --force        DEPRECATE
  -c, --caller TEXT  Caller ID (service)
  --no-ansi          Do not print ANSI control characters
  -h, --help         Show this message and exit.

Commands:
  access    Manage resource access
  account   Manage PlatformIO account
  boards    Embedded board explorer
  check     Static code analysis
  ci        Continuous integration
  debug     Unified debugger
  device    Device manager & serial/socket monitor
  home      UI to manage PlatformIO
  lib       Library manager
  org       Manage organizations
  package   Package manager
  platform  Platform manager
  project   Project manager
  remote    Remote development
  run       Run project targets (build, upload, clean, etc.)
  settings  Manage system settings
  system    Miscellaneous system commands
  team      Manage organization teams
  test      Unit testing
  update    Update installed platforms, packages and libraries
  upgrade   Upgrade PlatformIO to the latest version

Désinstaller le Core et les packages le PlatformIO

Pour désinstaller PlatformIO exécuter cette commande (fonctionne sur Windows, macOS et Linux)

pip uninstall platformio

ou uniquement sur macOS si vous avez utilisé brew pour l’installation

brew uninstall platformio

Il faudra supprimer manuellement les dépendances en supprimant le dossier platformio. Par défaut, il se trouve :

• sur Linux et macOS ~/.platformio
• sur Windows %HOMEPATH%\.platformio

Plus d’informations ici

Visual Studio Code est un très bonne alternative à l’éditeur Atom. Très léger, il démarre beaucoup plus rapidement qu’Atom. Il conviendra également très bien à une configuration légère ou un PC recyclé fonctionnant sous Linux 32-bits. Vous serez un peu moins guidé que sur Atom qui reste la plateforme de développement officielle de PlatformIO. Le SDK étant très bien documenté, la prise en main est très rapide.

Avez-vous aimé cet article ?