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

Share on facebook
Share on twitter
Share on linkedin
Share on pinterest
Share on email
Share on whatsapp
Table of Contents

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.

  • Windows : installer ou ZIP
  • macOS : dmg
  • Linux 32-bits : .deb, .rpm, .tag.gz
  • Linux 64-bits : .deb, .rpm, .tag.gz

download vscode

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 open extension plugin manager

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.

Chercher et installer le plugin PlatformIO sur Visual Studio Code

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.

Suivi de l'installation du plugin PlatformIO sur VSCode

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.

Page d'accueil de PlatformIO sur VSCode

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

  • Errors indicates compilation problems
  • Home opens the PIO home window. Useful when you want to import or create a new project
  • Build compiles the project code. Allows you to check for errors
  • Upload compiles and uploads the project. Detection is automatic but it is also possible to specify the port in the configuration file
  • Upload to remote device idem but on a remote MCU. A PIO account (paid or limited in the free tier) is required
  • Clean removes the build folder. Do not hesitate in case of problem. Has no impact on the source code of the project
  • Test to test the code before compiling it
  • Run Task opens the VSCode command palette
  • Serial Monitor opens the serial monitor
  • Terminal opens a Terminal directly in VSCode or Power Shell on Windows. We are directly positioned at the root of the project

Mini palette d'outils pour PIO

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

platformio visual studio code 3 ctrl shif p palette command

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:

Menu PIO sous VSCodeBuild 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

Créer un nouveau projet avec PlatformIO sous VSCode

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.

Assistant de création de projet de PlatformIO sous VSCode

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

Création du projet en cours

The project is now accessible from the explorer

Explorateur de projet VSCode

The folder contains several folders and configuration files.

  • .pio is a (hidden) folder that contains the builds. These are the binary files generated by the compiler. A subfolder is created by target (development board)
  • lib is the folder in which the libraries required for the project will be installed. This allows better management of version issues from one project to another. On the other hand, pay attention to the consumption of disk space.
  • src this folder contains the source code for your project. This is your working file
  • platformio.ini is the PIO configuration file
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 which corresponds to the SoC used by the board (ESP32, ESP8266, Atmel AVR, STM32 …). The full list is here
  • Board the development board. The full list can be found here
  • Framework 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 here.
platform = espressif8266   
board = esp12e
framework = arduino

We can then specify other parameters, for example

upload_port specify the COM port

  • /dev/ttyUSB0 serial port on Linux (or macOS) based systems
  • COM3 serial port on Windows
  • IP address for wireless update over WiFi (OTA)

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.

Configuration PlatformIO, carte de développement ESP32 Heltec Lora WiFi

Compile from PlatformIO

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

Compiler le code depuis le menu PIO

or from the tool palette

Compiler le code depuis la palette PIO

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.

Liste des devices connectés

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:

  • The module is not in booltload mode or has not received the request.
  • Remedies to test:
    • Do a reset
    • Disconnect / reconnect / restart upload
    • Ditto by changing the USB cable
    • Ditto on another USB port
    • Clear flash memory
    • Check if the board is detected in the devices
    • Test with another module … if it’s still not after several attempts, consider replacing the module

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.

platformio visual studio code vscode package

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!

Désactiver PIO depuis le gestionnaire d'extensions de 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: 6 Average: 5]

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
1 Comment
  1. Hi, Thanks a lot for sharing.

    Leave a Reply

    Read more
    Recent posts on the Forum
    DIY Projects
    DIY Projects
    %d bloggers like this: