Migrate a project from the Arduino IDE to PlatformIO. ESP32, ESP8266 or other

Table of Contents

PlatformIO seems less accessible than the Arduino IDE when you start, but it is an infinitely more powerful code editor. We will see how to migrate (import) an existing project (ESP32, ESP8266 or other) that has been developed with the Arduino IDE.


PlatformIO supports the support of SPIFFS and LittleFS since version 2.6.0 of the ESP8266 SDK. To use LittleFS, you just need to specify it using the board_build.filesystem=littlefs option in the platformio configuration file. Read this tutorial to learn more.

Read Also
ESP8266. Upload the data folder (SPIFFS or LittleFS) from PlatformIO

Install PlatformIO (PIO) on VSCode

PlatformIO (PIO) is not a code editor. It is a command line development environment (also called tool-chain) available as a plugin for the vast majority of code editors. Atom, CLion, CodeBlocks, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, Vim, Visual Studio, VSCode. The functionality is the same regardless of the editor you use.

I advise you to install the PIO plugin for Visual Studio Code (VSCode) from Microsoft, a fast, free and cross-platform editor. You choose !

Read Also
Getting started with PlatformIO IDE on VSCode (Windows, macOS, Raspbian, Linux)

Manually import an Arduino project on PlatformIO

1 Open the PIO home page from the toolbar on the left of the screen or from the house icon from the toolbar at the bottom of the screen.

Ouvrir la page d'accueil (Home) de platformIO PIO

2 Click Import Arduino Projects to start importing an existing project.

Importer un projet arduino existant sur platformio pio

3 Select the desired development board

Here we will choose a LoLin d1 mini. PIO supports more than 800 development boards.

It is possible to add (or modify the board) later, this is an advantage of PIO

4 Locate and select the Arduino / ESP32 / ESP8266 project folder to migrate to PIO.

Importer projet ESP32 ESP8266 arduino sur PIO PlatformIO

5 Launch the import / migration of the project to PIO

A new folder containing the source code of the project is created in the PlatformIO working folder. By default, the working folder is in My Documents on Windows and Documents on macOS or Linux.

The folder created in the Projects directory takes as name the target date-time (name of the development board) and contains the following elements:

  • lib private libraries are moved to the lib folder
  • src will contain all the ino files (source code of the Arduino project)
  • platformio.ini is the configuration file that allows you to define the environments. Each environment allows you to specify the type of development board (Arduino, ESP32, ESP8266, STM32 …), the framework to use for compilation and many other parameters documented here.

platformio pio project structure import

Once the copying of files is complete, PIO generates the project configuration file.

platformio pio platformio ini file import generate

New structure of the Arduino project under PIO

With the Arduino IDE, libraries are stored in Documents in an Arduino -> Library subfolder.

Under PIO, it is advisable to manage the libraries directly in the project folder. 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.

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 (if it exists) to the same level as the src folder

Arduino project structure PIO project structure after migration
├── data 
│   └── file.txt
├── main.ino
├── data 
│   └── file.txt
├── lib
│   └── README
├── platformio.ini
├── src
│   └── main.ino
└── test
    └── ...

Move the data folder containing LittleFS or SPIFFS files (optional)

If your project includes LittleFS or SPIFFS files in a data folder, you will have to move it manually so that it is at the same level as the src folder like this.

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

By default, PIO uses the SPIFFS file system. To activate LittleFS, you will need to specify it by adding the option board_build.filesystem=littlefs to the platformio.ini file

To specify the size of the File System (FS), just add the option board_build.ldscript and specify the value in the form 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.

platform = espressif8266
board = d1_mini_lite
board_build.filesystem = littlefs
board_build.ldscript = eagle.flash.4m3m.ld

Then use Upload File System Image option

upload file system image esp8266 littlefs spiffs pio platformio tool

To learn more about using LittleFS and SPIFFS with PIO, read this tutorial

Read Also
ESP8266. Upload the data folder (SPIFFS or LittleFS) from PlatformIO


16/09/2020 Publication of article

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

Thanks for your reading

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

Are you having a problem with this topic?

Maybe someone has already found the solution, visit the forum before asking your question
We will be happy to hear your thoughts

Leave a Reply

Read more
DIY Projects
DIY Projects