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

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

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.

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 !

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


16/09/2020 Publication of 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