DIY Projects

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

migrer projet ide arduino esp2 esp8266 pio platformio

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.

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

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.

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:

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

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.

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

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]
Exit mobile version