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.
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|
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:
- ESP32, ESP8266, Atmel AVR, STM32 …). The full list is here which corresponds to the SoC used by the board (
- here the development board. The full list can be found
- here. 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
[env:esp12e] 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
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
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)
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
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
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.
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
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
- ESP8266. Upload the data folder (SPIFFS or LittleFS) from PlatformIO
- ESP32. Access SPIFFS files in FTP with the ESP8266FtpServer library
- ESP32 Sketch data upload for Arduino IDE. Upload SPIFFS files to flash memory
- ESP32. Get started with the SPIFFS.h library to read, write, modify files
- ESP8266FtpServer for ESP8266. Access by FTP to SPIFFS or LittleFS files
- ESP8266 (Web Server – Part 1): Store the web interface in the SPIFFS area (HTML, CSS, JS)
14/09/2020 Publication de l’article
- Develop IoT projects with PlatformIO. Problems and solutions
- Platformio.ini, tips and useful settings. data_dir, monitor_speed, upload_port …
- Migrate a project from the Arduino IDE to PlatformIO. ESP32, ESP8266 or other
- ESP8266. Upload the data folder (SPIFFS or LittleFS) from PlatformIO
- Convert Arduino code into ESP Easy Mega plugin for ESP8266 / ESP32