DIY Projects

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

platformio ini options file configuration tips

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 structure Structure of a PIO project imported from the Arduino IDE Structure of a project generated by PlatformIO
├── data 
│   └── file.txt
├── main.ino
├── data
│   └── file.txt
├── lib 
│   └── README 
├── platformio.ini 
├── src 
│   └── main.ino
└── test 
    └── ...
├── 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 = espressif8266   
board = esp12e
framework = arduino

This is the equivalent of the menu on the Arduino IDE

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 …)

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.

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.

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

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 v2.8
Serial port /dev/cu.usbserial-1410

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:

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

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

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


14/09/2020 Publication de l’article

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