Platformio.ini, astuces et paramètres utiles. data_dir, monitor_speed, upload_port...

Le fichier de configuration platformio.ini permet de définir les plateformes cibles, les options de compilations et de nombreux autres paramètres. La documentation est ligne est très complète, voir trop complète pour des projets simples ou lorsqu'on débute. 

Ce document récapitule les paramètres les plus importants à connaître lorsqu'on démarre un nouveau projet avec PlatformIO. Comment créer et ajouter un environnement d'une carte de développement, spécifier la vitesse pour téléverser, la vitesse du port série, installer et mettre à jour les librairies d'un projet, activer le système de fichier SPIFFS ou LittleFS, spécifier le chemin vers le dossier data...

Si vous rencontrez des problèmes lors de vos développement avec PlatformIO, je vous invite à consulter cet article qui récapitule les problèmes les plus courants et les remèdes à tester.

Structure d'un projet Arduino sous PIO, fichier platformio.ini

La structure d'un projet Arduino sous l'IDE et PlatformIO est différente. Elle est également différente après une migration.

Lorsqu'on développe un projet avec l'IDE Arduino, les librairies sont stockées dans les Documents dans le sous-dossier Arduino -> Libraries.

Sous PIO, il est conseillé de gérer les librairies directement dans le dossier du projet, c'est le comportement par défaut. Cela permet de gérer les versions des libraries pour chaque projet. C'est aussi possible de le faire avec l'IDE Arduino, mais c'est moins pratique.

Lorsqu'on migre un projet existant, le fichier main.ino est automatiquement déplacé dans le dossier src.

C'est différent avec PlatformIO. Lorsqu'on créé un nouveau projet, PIO génère un fichier cpp et ajoute un appel vers la librairie Arduino.h 

#include <Arduino.h> 

Il faudra déplacer manuellement le dossier data qui contient les fichiers SPIFFS ou LittleFS (s'il existe) au même niveau que le dossier src.

project_dir
├── data 
│   └── file.txt
├── main.ino

project_dir 
├── data
│   └── file.txt
├── lib 
│   └── README 
├── platformio.ini 
├── src 
│   └── main.ino
└── test 
    └── ...

project_dir
├── lib
│   └── README
├── platformio.ini
├── src
│   └── main.cpp
└── test
    └── ...

Environnement de base d'un projet platformio

Découvrons maintenant 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) 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.

Trois paramètres sont nécessaires 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

C'est l'équivalent du menu sur l'IDE Arduino

Plutôt que de tâtonner pour trouver les bons paramètres, deux solutions sont possibles pour ajouter une nouvelle carte de développement

Ajouter une nouvelle configuration depuis le site PlatformIO

PIO répertorie presque 900 cartes de développements pour 37 plateformes différentes (Atmel AVR, Atmel SAMD, Espressif ESP8266, ESP32, STM32, PIC...)

Il suffit de saisir le début du libellé pour trouver la carte. Il est peu probable que vous ne trouviez pas la vôtre !

Si tel est le cas, vous pouvez soumettre une demande via GitHub.

Il suffit ensuite de copier la configuration de la carte dans le fichier platformio.ini

Ici par exemple celle d'une carte Heltec ESP32 Lora V2.

Ajouter une carte de développement depuis le gestionnaire de configuration de PIO

PIO dispose d'un gestionnaire de configuration qui permet de gérer via une interface graphique les paramètres du fichier platformio.ini.

Malheureusement, il n'est pas possible de récupérer directement l'intégralité de la configuration de la carte. Il faudra saisir manuellement chaque paramètre. Je vous conseille donc de passer par la méthode précédente pour ajouter une nouvelle carte

Spécifier le port COM et la vitesse pour téléverser (upload)

Voici quelques options très utiles au quotidien pour développer des projets Arduino, ESP32, ESP8266, ESP01 avec PlatformIO

upload_port permet de spécifier le port USB sur lequel est connecté la carte. C'est utile si vous développez sur plusieurs cibles simultanément.

Voici quelques exemples en fonction de la plateforme de développement

• /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 permet de spécifier la vitesse de transfert (en bauds)

Cette option pourra s'avérer utile en cas de problème pour téléverser...ou pour gagner du temps en passant la vitesse de transfert au maximum.

Spécifier la vitesse du port série

monitor_speed permet de spécifier la vitesse du moniteur série

Par défaut le moniteur série est configuré à 9600 bauds. Cette option permet de spécifier la même vitesse que dans le code C++ avec la commande Serial.begin(vitesse).

Si vous rencontrez des problèmes avec le port COM

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

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

Consultez cet article

Ajouter des librairies à un projet

lib_deps est l'option qui permet de spécifier les librairies à inclure dans le projet

Il est possible de spécifier la (ou les) librairie(s) à ajouter au projet :

• Le numéro de la librairie PIO. Chaque librairie référencée par l'équipe de PlatformIO est identifiée par un numéro
• Le nom, celui utilisé.
• Le dépôt GitHub
• Un chemin vers un dossier local si vous avez développé votre propre librairie C++

Il est possible de spécifier la (les) version (s) autorisées avec des règles assez complexes qui sont expliquée ici.

Par convention, une version est représentée par 3 chiffres séparés par un point

<numéro de version (révision majeur)>.<numéro de révision>.<correctif (patch)>
                     1               .         2          .         3

Voici un résumé

• ^1.2.3 toute version compatible. CONSEILLÉ
• ~1.2.3 toute version avec les mêmes versions majeures et mineures, et une version de correctif égale ou supérieure
• >1.2.3 toute version supérieure à 1.2.3. > =, <et <= sont également possibles
• >0.1.0,!=0.2.0, <0.3.0 toute version supérieure à 0.1.0, différente de 0.2.0 et inférieure à 0.3.0
• 1.2.3  n'utiliser que cette version exacte.

Comment télécharger (installer) les librairies dans un projet PlatformIO

Une fois que les librairies sont spécifiées dans le fichier de configuration, PIO s'occupe de télécharger et d'installer les dépendances avant chaque compilation.

Si aucune règle n'est précisée pour le numéro de version, il est possible de forcer la mise à jour de la librairie manuellement. Ca peut être utile pour effacer une erreur lorsqu'on appel une méthode disponible dans une nouvelle qui n'est pas encore installée en local.

Si vous rencontrez des problèmes avec les librairies, commencer par consulter cet article

Spécifier le chemin vers le dossier data

Le dossier data contient les fichiers nécessaires au projet que l'on souhaite téléverser sur la mémoire flash disponible sur certaines cartes de développement. Les modules ESP8266 et ESP32 disposent par exemple de 4Mo ou 16Mo de mémoire flash accessible via le bus SPI.

Ce sera par exemple les fichiers de l'interface HTML (code javascript, feuille de style CSS), des images, des fichiers de configuration au format JSON...

data_dir permet de spécifier le chemin vers le dossier data dans le projet. Par défaut le dossier data doit être situé au même niveau que le dossier src

Exemple : le dossier data se trouve dans le dossier src, ce qui est le cas lorsqu'on vient de migrer un projet Arduino vers PlatformIO.

data_dir = /src/data

Activer le système de fichier SPIFFS et LittleFS

Le système de fichier SPIFFS est supporté par défaut par PlatformIO. Il n'y a rien de plus à faire. Tout est expliqué en détail dans cet article

Si votre projet nécessite LittleFS, le successeur de SPIFFS, il faudra le spécifier dans le fichier de platformio.ini à l'aide de l'option board_build.filesystem.

board_build.filesystem = littlefs

Ensuite, en fonction de la carte de développement, il faudra indiquer la taille de la mémoire flash réservée au système de fichier.

Pour spécifier la taille du File System (FS), il suffit d'ajouter l'option board_build.ldscript et de spécifier la valeur sous la forme eagle.flash..ld

Toutes les configurations disponibles sont ici.

Voici un exemple pour un LoLin d1 mini équipée de 4Mo de mémoire Flash dont 3Mo sera attribué au système de fichier LittleFS.

[env:d1_mini_lite]
platform = espressif8266
board = d1_mini_lite
board_build.ldscript = eagle.flash.4m3m.ld

Où ajouter des fichiers à téléverser

Par défaut, le dossier data qui contiendra tous les fichiers à téléverser sur la mémoire flash de l'ESP8266 ou de l'ESP32 doit se trouver au même niveau que le dossier src.

Il est également possible de spécifier manuellement l'emplacement du dossier en ajoutant la clé data_dir dans le fichier platformio.ini

D'autres tutoriels et projets pour aller plus loin

Et ces articles qui expliquent comment utiliser le système de fichier SPIFFS ou LittleFS sur les cartes ESP32 ou ESP8266

• Platformio.ini, astuces et paramètres utiles. data_dir, monitor_speed, upload_port…
• Résumé de la semaine du 31 Août au 4 septembre 2020.
• ESP32 Sketch data upload pour IDE Arduino. Téléverser des fichiers SPIFFS sur la mémoire flash
• ESP32. Débuter avec la librairie SPIFFS.h pour lire, écrire, modifier des fichiers
• ESP32. Accéder aux fichiers SPIFFS en FTP avec la librairie ESP8266FtpServer
• ESP8266. Téléverser le dossier data (SPIFFS ou LittleFS) depuis PlatformIO
• Migrer un projet de l’IDE Arduino vers PlatformIO. ESP32, ESP8266 ou autre
• ESP8266. Téléverser avec LittleFS Data Upload pour IDE Arduino
• ESP8266. Utiliser la librairie LittleFS pour lire, écrire, modifier des fichiers
• ESP8266. Accéder en FTP aux fichiers SPIFFS ou LittleFS. Librairies ESP8266FtpServer et FTPClientServer

Mises à jour

14/09/2020 Publication de l'article

• Développer avec PlatformIO. Problèmes et solutions
• Platformio.ini, astuces et paramètres utiles. data_dir, monitor_speed, upload_port…
• ESP8266. Téléverser le dossier data (SPIFFS ou LittleFS) depuis PlatformIO
• Migrer un projet de l’IDE Arduino vers PlatformIO. ESP32, ESP8266 ou autre
• ESP Easy Mega. Installation facile avec PlatformIO sur ESP8266 (R120 obsolète)