DIY Projects

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

PlatformIO is an alternative to the Arduino IDE for developing connected objects or code for microcontrollers in a more general way. PlatformIO is not a code editor, it is a set of tools (toolchains) in the form of plugins for Visual Studio Code (or VSCode) from Microsoft and Atom from GitHub (also Microsoft!). VSCode is a lightweight and free code editor for Windows, macOS, Linux (32 or 64-bit).


PlatformIO is available as a plugin for many code editors (Atom, CLion, CodeBlocks, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, Vim, Visual Studio, VSCode). The functionalities are identical whatever the publisher. I opted for Microsoft’s Visual Studio Code, a fast, free, cross-platform editor. You choose !

Install Visual Studio Code (VSCode) for Windows, macOS, or Linux

Go to the official VSCode page to download and install the version that fits your environment.

Install the PlatformIO IDE package for VSCode

VSCode has an extension manager (plugin) that can be opened via the View -> Extension menu or directly from the icon located in the sidebar.

VSCode works very similar to Sublime Text (good ideas are often copied …), you can also invoke the extension manager with the CTRL + P key combination (or Cmd + P under macOS).

Enter platformio in the search field.

Click on Install to start installing the plugin and dependencies.

Be careful, some extension developers use the official project icon which can be confusing. You can trust the title of the extension. Development environment for Embedded, IoT, Arduino, ARM mbed, Espressif (ESP8266 / ESP32), AVR, RISC-V, STM32, PIC32, nRF51 / nRF52, MSP430, MCS-51 (8051), FPGA, FreeRTOS, ESP-IDF, CMSIS, SPL

The installation process takes place in the background, it’s a bit confusing when you discover VSCode. A window located at the bottom right of the screen allows you to follow the smooth progress of the installation. This is quite rare, but if you have an installation problem (or a crash), simply relaunch VSCode to resume the installation process.

Small tip by the way, VSCode having an operation very similar to Sublime Text (good ideas are often copied …) you can also call the extension manager with the key combination CTRL + P (Or Cmd + P under macOS) .

Starting PlatformIO for the first time on VSCode

At the end of the installation, it is not necessary to restart the editor. The PIO home page opens in a new tab ➀. This page greatly slows down the start of VSCode and does not help. I advise you to disable its opening at startup by unchecking the Show at startup ➁ option.

A new icon in the form of an ant head appears in the sidebar ➂. It provides access to all the functions of PIO. We will detail them a little later.

Finally, a mini toolbar ➃ appears at the bottom of the screen. It is a light version of the PIO menu ➂. It combines the following functions

For those who prefer to use keyboard shortcuts, you can summon the palette with the key combination Ctrl + Shift + P (or Cmd + + P on macOS).

Then enter the keyword platformio to display all the available commands

The PIO menu

Let’s go back to the PIO menu which is the easiest and most complete way to use PIO. It is always accessible from the sidebar. It combines all the functions of PIO.

Here are the most useful commands:

Build compile

Upload compiles and uploads the program

Monitor opens serial monitor

Upload and monitor compiles, uploads and opens the serial monitor

Upload File System image uploads all files stored in the data folder (SPIFFS or LittleFS format)

Erase Flash empties the flash memory of the development board

Devices List connected devices

Clean clears the build folder

Update project libraries updates the libraries used by the project

Create a new project (ESP32 or ESP8266)

It’s time to move on to a small example to test it all out.

Open the PIO home window (if necessary) and click +New Project to open the wizard for project creation

Name the project then select the development board from the list. The list is impressive.

You can enter the first letters of the manufacturer (LoLin, TTGO), that of the board (d1 mini), the type (ESP32, ESP8266 …) to filter the development board.

Leave Arduino in the framework. Depending on your board, you can opt for another framework, but in this case you will have to refer to the latter’s documentation for programming.

Finally, choose the directory for creating the project. If you check Use Default Location, the project will be created in the Documents/PlatformIO/Projects folder. The directory name will be the name of the project.

Click on Finish to start the initialization of the project. The operation only lasts a handful of seconds.

Be careful not to use special characters which may interfere with the compiler

The project is now accessible from the explorer

The folder contains several folders and configuration files.

Warning, you must never intervene (delete, modify, move) the folders and the platformio.ini file otherwise you will no longer be able to compile your project.

Open the main.cpp file located in the src (source) folder. As you can see, you must declare the Arduino.h library when developing Arduino code in PIO.

#include "Arduino.h"

void setup(){

void loop(){

Replace the code with the blink code and save the change

#include "Arduino.h"

void setup() {
   // initialize digital pin LED_BUILTIN as an output.

// the loop function runs over and over again forever
void loop() {
   digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
   delay(1000); // wait for a second
   digitalWrite(LED_BUILTIN, LOW); // turn the LED off by making the voltage LOW
   delay(1000); // wait for a second

Decryption of the platformio.ini file

Now let’s find out how to decrypt 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, MCUs) as one wishes. The configuration of each board is done by block which starts with the key env: between brackets, for example [env: esp12e] for the LoLin d1 mini.

You need 3 parameters to completely define a board:

platform = espressif8266   
board = esp12e
framework = arduino

We can then specify other parameters, for example

upload_port specify the COM port

upload_speed specify the baud transfer speed

monitor_speed serial monitor speed

More options here

To add a new development board, I advise you to directly retrieve the configuration of your board from the official WiKi rather than using the configuration wizard. Over 850 development boards are already listed.

You will not have to fumble to find the right settings as for this Heltec ESP32 dev board with LoRa connectivity which exists in 2 versions.

Compile from PlatformIO

Now that everything is ready, you can launch the creation of the build from the PIO menu

or from the tool palette

For some reason that still escapes me, the test and code verification (check) ends with an error message.

Unlike the Arduino IDE, it is not necessarily necessary to install the libraries before compiling. PIO takes care of everything as long as the dependencies are correctly indicated in the ini file.

A Terminal opens below the code and indicates the progress of the compilation. The compilation time is identical to the Arduino IDE.

If everything went without error, you should get a message from [success]

Linking .pio/build/esp12e/firmware.elf
Retrieving maximum program size .pio/build/esp12e/firmware.elf
Checking size .pio/build/esp12e/firmware.elf
Building .pio/build/esp12e/firmware.bin
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM: [=== ] 32.7% (used 26816 bytes from 81920 bytes)
Flash: [== ] 24.6% (used 257212 bytes from 1044464 bytes)
Creating BIN file ".pio/build/esp12e/firmware.bin" using ".pio/build/esp12e/firmware.elf"
======================================================== [SUCCESS] Took 32.26 seconds ====

Check that the development board is correctly detected

On the Arduino IDE, just go to the Tools -> Port menu to find out if the development board has been detected.

On PIO, an equivalent function is available. Open the PIO home page and open the Devices tab. The boards are automatically detected and appear in the list (here on a Mac). If this is not the case, use the Refresh button to force the detection of devices.

As a reminder, if you have difficulty uploading the program to the board, it is possible to specify the port and the transfer speed in the configuration (see above)

Upload the program to the development board (Arduino, ESP8266, ESP32, STM32 …)

Everything is ready to upload the program to the development board. As before, the Upload method is accessible from the palette or from the PIO menu

PIO compiles the project, connects to the board and uploads the binary.

> Executing task in folder Demo ESP8266: platformio run --target upload <

Warning! Ignore unknown configuration option `upload_serial` in section [env:esp12e]
Processing esp12e (platform: espressif8266; board: esp12e; framework: arduino)
Verbose mode can be enabled via `-v, --verbose` option
PLATFORM: Espressif 8266 2.5.1 > Espressif ESP8266 ESP-12E
HARDWARE: ESP8266 80MHz, 80KB RAM, 4MB Flash
- framework-arduinoespressif8266 3.20701.0 (2.7.1) 
- tool-esptool 1.413.0 (4.13) 
- tool-esptoolpy 1.20800.0 (2.8.0) 
- tool-mkspiffs 1.200.0 (2.0) 
- toolchain-xtensa 2.40802.200502 (4.8.2)
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 30 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Retrieving maximum program size .pio/build/esp12e/firmware.elf
Checking size .pio/build/esp12e/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM: [=== ] 32.7% (used 26816 bytes from 81920 bytes)
Flash: [== ] 24.6% (used 257212 bytes from 1044464 bytes)
Configuring upload protocol...
AVAILABLE: espota, esptool
CURRENT: upload_protocol = esptool
Looking for upload port...
Auto-detected: /dev/cu.usbserial-1410
Uploading .pio/build/esp12e/firmware.bin v2.8
Serial port /dev/cu.usbserial-1410
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 5c:cf:7f:85:e6:20
Uploading stub...
Running stub...
Stub running...
Configuring flash size...
Auto-detected Flash size: 4MB
Compressed 261360 bytes to 192964...

Writing at 0x00000000... (8 %)
Writing at 0x00004000... (16 %)
Writing at 0x00008000... (25 %)
Writing at 0x0000c000... (33 %)
Writing at 0x00010000... (41 %)
Writing at 0x00014000... (50 %)
Writing at 0x00018000... (58 %)
Writing at 0x0001c000... (66 %)
Writing at 0x00020000... (75 %)
Writing at 0x00024000... (83 %)
Writing at 0x00028000... (91 %)
Writing at 0x0002c000... (100 %)
Wrote 261360 bytes (192964 compressed) at 0x00000000 in 18.6 seconds (effective 112.6 kbit/s)...
Hash of data verified.

Hard resetting via RTS pin...
================================ [SUCCESS] Took 23.11 seconds ==============================

Frequent problems

Unable to upload cannot connect to the development board (ESP32, ESP8266…)

Looking for upload port...
Auto-detected: /dev/cu.usbserial-1420
Uploading .pio/build/esp12e/firmware.bin v2.8
Serial port /dev/cu.usbserial-1420

A fatal error occurred: Failed to connect to ESP8266: Timed out waiting for packet header
*** [upload] Error 2
============================= [FAILED] Took 27.38 seconds ===================

Possible causes and remedies:

Unable to connect with Serial Monitor

By default, the serial port is configured at 9600 baud on the official extension. Jun Han added a parameter to set the speed. To use a different speed, open Terminal and run the following command pio device monitor -b 115200.

You can also specify the speed in the plaformio.ini file using the monitor_speed option.

How to disable PlatformIO extension ?

PIO can slow down the startup of VSCode. If you have one-time use, you can deactivate it from the extension manager. Activate it when you need the functionality of PIO. The loading is done hot, no need to restart VSCode!

Visual Studio Code is a very good alternative to the Atom editor. Very light, it starts much faster than Atom. It will also fit very well in a light configuration or a recycled PC running 32-bit Linux. You will be a little less guided than on Atom which remains PlatformIO’s official development platform. The SDK is very well documented, the grip is very fast.

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