Platformio.ini, tips and useful settings. data_dir, monitor_speed, upload_port …

platformio ini options file configuration tips
Share on facebook
Share on twitter
Share on linkedin
Share on pinterest
Share on email
Share on whatsapp

The platformio.ini configuration file allows you to define target platforms, build options and many other parameters. The documentation is online is very complete, see too complete for simple projects or when starting out.

 

This document summarizes the most important parameters to know when starting a new project with PlatformIO. How to create and add a development board environment, specify upload speed, serial port speed, install and update project libraries, activate SPIFFS or LittleFS file system, specify path to the data folder …

If you encounter problems during your development with PlatformIO, I invite you to consult this article which recapitulates the most common problems and the remedies to test.

Structure of an Arduino project under PIO, platformio.ini file

The structure of an Arduino project under the IDE and PlatformIO is different. It is also different after a migration.

When developing a project with the Arduino IDE, the libraries are stored in Documents in the Arduino -> Libraries subfolder.

Under PIO, it is advisable to manage the libraries directly in the project folder, this is the default behavior. This allows you to manage the versions of the libraries for each project. It’s also possible to do this with the Arduino IDE, but it’s less convenient.

When migrating an existing project, the main.ino file is automatically moved to the src folder.

It’s different with PlatformIO. When creating a new project, PIO generates a cpp file and adds a call to the Arduino.h library.

#include <Arduino.h> 

You will have to manually move the data folder which contains the SPIFFS or LittleFS files (if there is one) to the same level as the src folder.

Arduino project structureStructure of a PIO project imported from the Arduino IDEStructure of a project generated by PlatformIO
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
    └── ...

Basic environment of a platformio project

Now let’s find out what the platformio.ini configuration file contains at the root of the project.

The strength of PIO is to be able to compile the same code (project) towards as many targets (development boards) as one wishes. The configuration of each board is done by block which begins with the key env: between brackets

For example [env:esp12e] for the LoLin d1 mini.

Three parameters are required to fully define a board:

  • Platform which corresponds to the SoC used by the board (ESP32, ESP8266, Atmel AVR, STM32 …). The full list is here
  • Board the development board. The full list can be found here
  • Framework the software environment that will run the project code. Please note, each SoC is only compatible with a limited number of frameworks. The list can be found here.
[env:esp12e]               
platform = espressif8266   
board = esp12e
framework = arduino

This is the equivalent of the menu on the Arduino IDE

esp8266 sdk esp idf espressif ide arduino install

Rather than fumbling around to find the right parameters, two solutions are possible to add a new development board

Add a new configuration from the PlatformIO site

PIO lists almost 900 development boards for 37 different platforms (Atmel AVR, Atmel SAMD, Espressif ESP8266, ESP32, STM32, PIC …)

Rechercher une carte de développement sur PIO

All you have to do is enter the beginning of the label to find the board. You are unlikely to find yours!

If so, you can submit a request through GitHub.

pio dev boards list platformio

Then all you have to do is copy the board configuration into the platformio.ini file

Here for example that of a Heltec ESP32 Lora V2 board.

Configuration PlatformIO, carte de développement ESP32 Heltec Lora WiFi

Add a development board from the PIO configuration manager

PIO has a configuration manager that allows you to manage the parameters of the platformio.ini file via a graphical interface.

Unfortunately, it is not possible to directly recover the entire configuration of the board. Each parameter will have to be entered manually. I therefore advise you to go through the previous method to add a new board

Specify the COM port and speed for uploading

Here are some very useful options on a daily basis to develop Arduino, ESP32, ESP8266, ESP01 projects with PlatformIO

upload_port allows you to specify the USB port on which the board is connected. This is useful if you are developing on multiple targets simultaneously.

Here are some examples depending on the development platform

  • /dev/ttyUSB0 – serial port on Linux (or macOS) based systems
  • COM3 – serial port on Windows
  • 192.168.0.13 – IP address for wireless update over WiFi (OTA)

upload_speed allows you to specify the transfer speed (in bauds)

This option can be useful if you have a problem uploading … or to save time by lowering the transfer speed to maximum.

Specify the serial port speed

monitor_speed allows to specify the speed of the serial monitor

By default the serial monitor is configured at 9600 baud. This option allows you to specify the same speed as in C++ code with the Serial.begin(speed) command.

If you are having trouble with the COM port

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 =========================

Read this article

Add libraries to a project

lib_deps is the option that allows you to specify the libraries to include in the project

It is possible to specify the library (s) to add to the project:

  • The number of the PIO library. Each library referenced by the PlatformIO team is identified by a number
  • The name, the one used.
  • The GitHub repository

A path to a local folder if you have developed your own C++ library

It is possible to specify the authorized version (s) with quite complex rules which are explained here.

By convention, a version is represented by 3 digits separated by a point

<version number (major revision)>.<revision number>.<patch>
                 1               .        2        .   3

here is a summary

  • ^1.2.3 any compatible version. ADVISED
  • ~1.2.3 any version with the same major and minor versions, and an equal or higher patch version
  • >1.2.3 any version greater than 1.2.3. >= and <= are also possible
  • >0.1.0, != 0.2.0, <0.3.0 any version greater than 0.1.0, other than 0.2.0 and less than 0.3.0
  • 1.2.3 only use this exact version.

How to download (install) the libraries in a PlatformIO project

Once the libraries are specified in the configuration file, PIO takes care of downloading and installing the dependencies before each compilation.

If no rule is specified for the version number, it is possible to force the update of the library manually. This can be useful to clear an error when calling an available method in a new one that is not yet installed locally.

If you’re having trouble with libraries, check out this article first

Specify the path to the data folder

The data folder contains the files needed for the project that you want to upload to the flash memory available on some development boards. The ESP8266 and ESP32 modules have, for example, 4MB or 16MB of flash memory accessible via the SPI bus.

This will be for example the HTML interface files (javascript code, CSS style sheet), images, configuration files in JSON format …

data_dir allows you to specify the path to the data folder in the project. By default the data folder must be located at the same level as the src folder

Example: the data folder is located in the src folder, which is the case when you have just migrated an Arduino project to PlatformIO.

data_dir = /src/data

Enable the SPIFFS and LittleFS file system

The SPIFFS file system is supported by default by PlatformIO. There is nothing more to do. Everything is explained in detail in this article

If your project requires LittleFS, the successor to SPIFFS, you will need to specify it in the platformio.ini file using the board_build.filesystem option.

board_build.filesystem = littlefs

Then, depending on the development board, you will need to indicate the size of the flash memory reserved for the file system.

To specify the size of the File System (FS), just add the option board_build.ldscript and specify the value in the form of eagle.flash. ***. Ld

All available configurations are here.

Here is an example for a LoLin d1 mini equipped with 4MB of Flash memory of which 3MB will be allocated to the LittleFS file system.

Where to add files to upload

By default, the data folder which will contain all the files to be uploaded to the flash memory of the ESP8266 or ESP32 must be at the same level as the src folder.

It is also possible to manually specify the location of the folder by adding the data_dir key in the platformio.ini file

Structure d'un projet PlatformIO PIO ESP8266 avec un dossier data contenant des fichiers LittleFS SPIFFS

Other tutorials and projects to go further

And those articles that explain how to use the SPIFFS or LittleFS file system on ESP32 or ESP8266 boards

Updates

14/09/2020 Publication de l’article

Click to rate this post!
[Total: 0 Average: 0]

Are you having a problem with this topic?

Maybe someone has already found the solution, visit the forum before asking your question
Ask your question

Share on facebook
Share on twitter
Share on linkedin
Share on pinterest
Share on email
Share on whatsapp

Did you like this project ? Don't miss any more projects by subscribing to our weekly newsletter!

We will be happy to hear your thoughts

      Leave a Reply

      DIY Projects