Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266 (Windows, Mac OS X, Linux Ubuntu)

Learn how to program the ESP32 and ESP8266 NodeMCU boards using VS Code (Microsoft Visual Studio Code) with PlatformIO IDE extension. We cover how to install the software on Windows, Mac OS X or Ubuntu operating systems.

Getting Started with VS Code and PlatformIO IDE for ESP32 and NodeMCU ESP8266 boards: Windows, Mac OS X, Linux Ubuntu

The Arduino IDE works great for small applications. However, for advanced projects with more than 200 lines of code, multiple files, and other advanced features like auto completion and error checking, VS Code with the PlatformIO IDE extension is the best alternative.

In this tutorial, we’ll cover the following topics:

A) Installing VS Code on Windows (Visual Studio Code)

Go to https://code.visualstudio.com/ and download the stable build for your operating system (Windows).

Microsoft Visual Studio Code VS Code Download Page for Windows PC

Click on the installation wizard to start the installation and follow all the steps to complete the installation. Accept the agreement and press the Next button.

Microsoft Visual Studio Code VS Code Installation wizard

Select the following options and click Next.

Microsoft Visual Studio Code VS Code Installation wizard step 2

Press the Install button.

Microsoft Visual Studio Code VS Code Installation wizard step 3

Finally, click Finish to finish the installation.

Microsoft Visual Studio Code VS Code Installation wizard final step

Open VS Code and you’ll be greeted by a Welcome tab with the released notes of the newest version.

Microsoft Visual Studio Code VS Code Installation wizard welcome screen on a Windows PC

That’s it. Visual Studio Code was successfully installed.

Installing Python on Windows

To program the ESP32 and ESP8266 boards with PlatformIO IDE you need Python 3.5 or higher installed in your computer. We’re using Python 3.8.5.

Go to python.org/download and download Python 3.8.5 or a newest version.

Open the downloaded file to start the Python installation wizard.

The following window shows up.

Installing Python 3.8.5 on a Windows PC and Add to Path

IMPORTANT: Make sure you check the option Add Python 3.8 to PATH. Then, you can click on the Install Now button.

When the installation is successful you’ll get the following message.

Python Installation successful on Windows PC

You can click the Close button.

Now, go to this section to install PlatformIO IDE extension.


B) Installing VS Code on Mac OS X (Visual Studio Code)

Go to https://code.visualstudio.com/ and download the stable build for your operating system (Mac OS X).

Microsoft Visual Studio Code VS Code Download Page for Mac OS X

After downloading the Visual Studio Code application file, you’ll be prompted with the following message. Press the “Open” button.

Microsoft Visual Studio Code VS Code Downloading application file for Mac OS X

Or open your Downloads folder and open Visual Studio Code.

Microsoft Visual Studio Code VS Code Downloading application file for Mac OS X

After that, you’ll be greeted by a Welcome tab with the released notes of the newest version.

Microsoft Visual Studio Code VS Code Installation wizard welcome screen on Max OS X

That’s it. Visual Studio Code was successfully installed.

Installing Python on Mac OS X

To program the ESP32 and ESP8266 boards with PlatformIO IDE you need Python 3.5 or higher installed in your computer. We’re using Python 3.8.5.

To install Python I’ll be using Homebrew. If you don’t have the brew command available, type the next command:

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
Microsoft Visual Studio Code VS Code installing homebrew

Then, run the brew command to install Python 3.X:

$ brew install python3
Microsoft Visual Studio Code VS Code installing Python 3 with brew command

Now, go to this section to install PlatformIO IDE extension.


C) Installing VS Code on Linux Ubuntu (Visual Studio Code)

Go to https://code.visualstudio.com/ and download the stable build for your operating system (Linux Ubuntu).

Microsoft Visual Studio Code VS Code Download Page for Linux Ubuntu

Save the installation file:

Microsoft Visual Studio Code VS Code Save installation file for Linux Ubuntu

To install it, open a Terminal windows, navigate to your Downloads folder and run the following command to install VS Code.

$ cd Downloads
~/Downloads $ sudo apt install ./code_1.49.1-1600299189_amd64.deb

When the installation is finished, VS Code should be available in your applications menu.

Microsoft Visual Studio Code VS Code Open application Linux Ubuntu

Open VS Code and you’ll be greeted by a Welcome tab with the released notes of the newest version.

Microsoft Visual Studio Code VS Code Installation wizard welcome screen on Linux Ubuntu

That’s it. Visual Studio Code was successfully installed.

Installing Python on Linux Ubuntu

To program the ESP32 and ESP8266 boards with PlatformIO IDE you need Python 3.5 or higher installed in your computer. We’re using Python 3.8.

Open the Terminal window and check that you already have Python 3 installed.

$ python3 --version
python 3.8.2
Linux ubuntu installing Python3 testing version

As you can see in the preceding figure, Python 3.8.2 is already installed.

If you don’t have Python 3.8.X installed, run the next command to install it:

$ sudo apt install python3

Whether you already have Python installed or not, you need to run the following command to install Python utilities.

$ sudo apt install python3-distutils
Installing python3-distutils Linux Ubuntu for PlatformIO IDE

Now, go to this section to install PlatformIO IDE extension.


Installing PlatformIO IDE Extension on VS Code

It is possible to program the ESP32 and ESP8266 boards using VS Code with the PlatformIO IDE extension. Follow the next steps to install the PlatformIO IDE extension.

Open VS Code:

  1. Click on the Extensions icon or press Ctrl+Shift+X to open the Extensions tab
  2. Search for “PlatformIO IDE
  3. Select the first option
  4. Finally, click the Install button (Note: the installation may take a few minutes)
Install PlatformIO IDE Extension on VS Code

After installing, make sure that PlatformIO IDE extension is enabled as shown below.

PlatformIO IDE Extension Enabled on VS Code

After that, the PlatformIO icon should show up on the left sidebar as well as an Home icon that redirects you to PlatformIO home.

PlatformIO Extension Installed Successfully

That’s it, PlatformIO IDE extension was successfully added to VS Code.

If you don’t see the PIO icon and the quick tools at the bottom, you may need to restart VS code for the changes to take effect.

Either way, we recommend restarting VS Code before proceeding.

VS Code Quick Interface Overview

Open VS Code. The following print screen shows the meaning of each icon on the left sidebar and its shortcuts:

VS Code Visual Studio Application Interface Overview
  • File explorer
  • Search across files
  • Source code management (using gist)
  • Launch and debug your code
  • Manage extensions

Additionally, you can press Ctrl+Shift+P or go to View > Command Palette… to show all the available commands. If you’re searching for a command and you don’t know where it is or its shortcut, you just need to go to the Command Palette and search for it.

At the bottom, there’s a blue bar with PlatformIO commands.

PlatformIO IDE extension Quick Tools Icons

Here’s the what icon does from left to right:

  • PlatformIO Home
  • Build/Compile
  • Upload
  • Clean
  • Serial Monitor
  • New Terminal

If you hover your mouse over the icons, it will show what each icon does.

Alternatively, you can also click on the PIO icon to see all the PlatformIO tasks. 

PlatformIO IDE extension Tasks menu

If the tasks don’t show up on your IDE when you click the icon, you may need to click on the three dot icon at the top and enable PlatformIO tasks as shown below.

Enable PlatformIO IDE extension tasks

PlatformIO IDE Overview

For you to get an overview on how PlatformIO works on VS code, we’ll show you how to create, save and upload a “Blinking LED” sketch to your ESP32 or ESP8266 board.

Create a New Project

On VS Code, click on the PlartfomIO Home icon. Click on + New Project to start a new project.

Create New Project PlatformIO VS Code

Give your project a name (for example Blink_LED) and select the board you’re using. In our case, we’re using the DOIT ESP32 DEVKIT V1. The Framework should be “Arduino” to use the Arduino core.

You can choose the default location to save your project or a custom location.

The default location is in this path Documents >PlatformIO >Projects. For this test, you can use the default location. Finally, click “Finish”.

PlatformIO with VS Code Create New ESP32 Project

For this example, we’ll be using the DOIT ESP32 DEVKIT board. If you are using an ESP8266 NodeMCU board the process is very similar, you just need to select your ESP8266 board:

PlatformIO IDE extension with VS Code Create New ESP8266 Project

The Blink_LED project should be accessible from the Explorer tab.

PlatformIO IDE Extension Project Folder Structure

VS Code and PlatformIO have a folder structure that is different from the standard .ino project. If you click on the Explorer tab, you’ll see all the files it created under your project folder. It may seem a lot of files to work with. But, don’t worry, usually you’ll just need to deal with one or two of those files.

Warning: you shouldn’t delete, modify or move the folders and the platformio.ini file. Otherwise, you will no longer be able to compile your project using PlatformIO.

platformio.ini file

The platformio.ini file is the PlatformIO Configuration File for your project. It shows the platform, board, and framework for your project. You can also add other configurations like libraries to be included, upload options, changing the Serial Monitor baud rate and other configurations.

PlatformIO IDE extension Configuration File for ESP32
  • platform: which corresponds to the SoC used by the board.
  • board: the development board you’re using.
  • framework: the software environment that will run the project code.

With the ESP32 and ESP8266, if you want to use a baud rate of 115200 in your Serial Monitor, you just need to add the following line to your platformio.ini file.

monitor_speed = 115200

After that, make sure you save the changes made to the file by pressing Ctrl+S.

In this file, you can also include the identifier of libraries you’ll use in your project using the lib_deps directive. For example:

lib_deps =
  arduino-libraries/Arduino_JSON @ 0.1.0
  adafruit/Adafruit BME280 Library @ ^2.1.0
  adafruit/Adafruit Unified Sensor @ ^1.1.4

This installs the libraries locally by its identifier. PlatformIO will download the libraries and all its dependencies automatically. We’ll take a look at this subject later in this tutorial.

src folder

The src folder is your working folder. Under the src folder, there’s a main.cpp file. That’s where you write your code. Click on that file. The structure of an Arduino program should open with the setup() and loop() functions.

PlatformIO IDE extension main.cpp file under src folder

In PlatformIO, all your Arduino sketches should start with the #include <Arduino.h>.

Uploading Code using PlatformIO IDE: ESP32/ESP8266

Copy the following code to your main.cpp file. 

/*********
  Rui Santos
  Complete project details at https://RandomNerdTutorials.com/vs-code-platformio-ide-esp32-esp8266-arduino/
*********/

#include <Arduino.h>

#define LED 2

void setup() {
  // put your setup code here, to run once:
  Serial.begin(115200);
  pinMode(LED, OUTPUT);
}

void loop() {
  // put your main code here, to run repeatedly:
  digitalWrite(LED, HIGH);
  Serial.println("LED is on");
  delay(1000);
  digitalWrite(LED, LOW);
  Serial.println("LED is off");
  delay(1000);
}

View raw code

This code blinks the on-board LED every second. It works with the ESP32 and ESP8266 boards (both have the on-board LED connected to GPIO 2). 

We recommend that you copy this code manually, so that you see the autocompletion and other interesting features of the IDE in action. Additionally, if you have a syntax error somewhere in your program, it will underline it in red even before compiling.

After that, press Ctrl+S or go to File > Save to save the file.

Now, you can click on the Upload icon to compile and upload the code. Alternatively, you can go to the PIO Project Tasks menu and select Upload.

Upload Code ESP32 board PlatformIO VS Code Visual Studio

If the code is successfully uploaded, you should get the following message.

Upload Code to ESP32 PlatformIO VS Code Success

After uploading the code, the ESP32 or ESP8266 should be blinking its on-board LED every second.

ESP32 board Built in LED turned on HIGH

Now, click on the Serial Monitor icon and you should see it printing the current LED state.

PlatformIO IDE VS Code Visual Studio Serial Monitor ESP32 board

Note: if you don’t see the Terminal window, go to the menu Terminal > New Terminal.

Detect COM Port

PlatformIO will automatically detect the port your board is connected to. To check the connected devices you can go to the PIO Home and click the Devices icon.

PlatformIO IDE extension VS Code Visual Studio Connected Devices COM Port Serial

Troubleshooting

If when trying to upload code you get the following error: “Failed to connect to ESP32: Timed out waiting for packet header” it usually means that your board is not in flashing mode when you’re uploading the code. 

When this happens you need to press the ESP32 on-board BOOT button when you start seeing a lot of dots in the debugging window.

If you don’t want to have to press the BOOT button every time you upload new code, you can follow this guide: [SOLVED] Failed to connect to ESP32: Timed out waiting for packet header.

Changing the Serial Monitor Baud Rate – PlatformIO IDE

The default baud rate used by PlatformIO is 9600. However, it is possible to set up a different value as mentioned previously. On the File Explorer, under your project folder, open the platformio.ini file and add the following line:

monitor_speed = baud_rate

For example:

monitor_speed = 115200
PlatformIO IDE extesion Change Serial Monitor Baud Rate 115200

After that, save that file.

Installing ESP32/ESP8266 Libraries on PlatformIO IDE

Follow the next procedure if you need to install libraries in PlatformIO IDE.

Click the Home icon to go to PlatformIO Home. Click on the Libraries icon on the left side bar.

Search for the library you want to install. For example Adafruit_BME280.

PlatformIO IDE extension VS Code Visual Studio Search for BME280 Library

Click on the library you want to include in your project. Then, click Add to Project.

PlatformIO with VS Code Add Library to Project

Select the project were you want to use the library.

PlatformIO with VS Code Add Library to Project Choose Project

This will add the library identifier using the lid_deps directive on the platformio.ini file. If you open your project’s platformio.ini file, it should look as shown in the following image.

Add Library Identifier to Configuration File PlatformIO

Alternatively, on the library window, if you select the Installation tab and scroll a bit, you’ll see the identifier for the library. You can choose any of those identifiers depending on the options you want to use. The library identifiers are highlighted in red.

PlatformIO IDE Extension Library Registry menu

Then, go to the platformio.ini file of your project and paste the library identifier into that file, like this:

lib_deps = adafruit/Adafruit BME280 [email protected]^2.1.0

If you need multiple libraries, you can separate their name by a coma or put them on different lines.

PlatformIO has a built-in powerful Library Manager, that allows you to specify custom dependencies per project in the Project Configuration File platformio.ini using lib_deps. This will tell PlatformIO to automatically download the library and all its dependencies when you save the configuration file or when you compile your project.

Open a Project Folder

To open an existing project folder on PlatformIO, open VS Code, go to PlatformIO Home and click on Open Project. Navigate through the files and select your project folder.

VS Code with PlatformIO Open Project Folder

PlatformIO will open all the files within the project folder.

VS Code Color Themes

VS Code lets you choose between different color themes. Go to the Manage icon and select Color Theme. You can then select from several different light and dark themes.

VS Code Visual Studio Change Color Themes Dark Light

Shortcuts’ List

For a complete list of VS Code shortcuts for Windows, Mac OS X or Linux, check the next link:

Wrapping Up

In this tutorial you’ve learned how to install and prepare Visual Studio Code to work with the ESP32 and ESP8266 boards. VS Code with the PlatformIO IDE extension is a great alternative to the classical Arduino IDE, especially when you’re working on more advanced sketches for larger applications.

Here’s some of the advantages of using VS Code with PlatformIO IDE over Arduino IDE: 

  • It detects the COM port your board is connected to automatically; 
  • VS Code IntelliSense: Auto-Complete. IntelliSense code completion tries to guess what you want to write, displaying the different possibilities and provides insight into the parameters that a function may expect;
  • Error Highlights: VS Code + PIO underlines errors in your code before compiling;
  • Multiple open tabs: you can have several code tabs open at once;
  • You can hide certain parts of the code;
  • Advanced code navigation;
  • And much more…

If you’re looking for a more advanced IDE to write your applications for the ESP32 and ESP8266 boards, VS Code with the PlatformIO IDE extension is a great option.

We hope you’ve found this tutorial useful. If you like ESP32 and ESP8266, check the following resources:



Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »

Learn how to program and build projects with the ESP32 and ESP8266 using MicroPython firmware DOWNLOAD »


Enjoyed this project? Stay updated by subscribing our weekly newsletter!

49 thoughts on “Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266 (Windows, Mac OS X, Linux Ubuntu)”

    • Besides the link Sara mentions here are some other references:

      A good video from Andreas Spiess demonstrating hardware debug in platformio:
      youtube.com/watch?v=psMqilqlrRQ

      Another good reference and video:
      hackster.io/brian-lough/use-the-platformio-debugger-on-the-esp32-using-an-esp-prog-f633b6

      Most guides show only Windows installation. To get the JTAG interface to work in Linux you need to install the 99-platformio-udev.rules so the USB ingterface recognizes the device as explained in:
      docs.platformio.org/en/latest/plus/debug-tools/esp-prog.html
      For MacOS, you apparently need to remove the default FTDI drivers (same reference above).

      I recommend the ESP-PROG made by Espressif. Besides the usual Chinese suppliers, it is available from US mainstream distributors for $12-13 without shipping.

      Reply
  1. Is there any experience, what is the speed difference on program run/code size VS coded vs. C coded? Is it possible to handle interrupts in VS?

    Reply
  2. pretty complex to setup microsoft visual studio and platformIO
    What is the big advantage of using with VS Code and PlatformIO IDE over the Arduino-IDE that would be worth the hassle of this setup-process?

    Reply
    • The wrapping up statement gives you the main benefits for your efforts, i will add that your programming skills will be taken to a higher level. I wish i had this when i installed it on my pc. This ia a great tutorial to get you started on what could be a career changing journey for some.

      Reply
    • Stefan:

      I was wondering the same thing! What is the advantage of using VS Code and PlatformIO! With the Arduino platform, I know, at time, there is issue. I have learned to deal with it. I don’t have any project that the Arduino platform doesn’t work.

      Reply
    • Hi.
      It is very useful if you’re setting up a web server with separated HTML, CSS and Javascript files. You can program all the files using the same software and you can open the files side by side. It also allows you to upload the files to the ESP32 or ESP8266 filesystem easily.
      Additionally, if you’re working on a quite complex project, it can be useful because it highlights errors, helps with autocompletion, identation, etc.
      Regards,
      Sara

      Reply
  3. Excelent Guide to start!

    Can not wait for a book with some full projects to fully understand it maybe multi platform and some debugging tutorials?

    Reply
  4. Thanks for a great writeup! It was nice to have instructions for Windows, MacOS, and Linux.

    I’ve always thought the code editing and management of VSCode was so much better than the Arduino. I used the old (not VSCode) Platformio before for ESP and STM, but as Stefan mentions, it’s a bunch of overhead. As you mention, for larger projects VSCode is way better.

    The best reason to use platformio is to get interactive hardware debugging inside VSCode. That is a game-changer. It would be great to add another tutorial to the series on how to use hardware debug on Windows/Mac/Linux. I have an EDP-Prog (<$13) but I haven’t had time to play with it.

    Reply
  5. Thank you for introducing here this new tool!
    It showed very useful here when I used it to create a project using ESP32 FreeRTOS (ESP-IDF).
    I already used the VS Code when I was studying FreeRTOS here, but without using the PlatformIO resources. Now it’s much better to use it!

    Reply
  6. Hi Sara,
    wonderfull tutorial up to the Blink_LED tutorial. All is running ok and I thank you very much for your patience and precision.
    I’ve a simple question : can I copy all Arduino ESP32 projects now running with Arduino compilation in PlatformIO without any changes ( I mean instruction and declaration define etc. ) and uploading it with PLatformIO on ESP32 board ? Or it’s a long way of conversion and test ?
    Regards and thanks again.

    Reply
  7. Hi,

    Is it required to press the boot switch of the esp32 while downloading?

    I am asking so as I got:
    “*** [upload] Error 1
    =========================================== [FAILED] Took 3.74 seconds ===========================================
    The terminal process “platformio ‘run’, ‘–target’, ‘upload'” terminated with exit code: 1.”

    Or I am missing something?

    Zvika

    Reply
  8. I am mostly a hobbyist / tinkerer. I’ve played around with VSCode / Platformio a bit, alongside the Arduino IDE.

    My take on it is that VSCode / Platformio is extremely convenient for those who are writing complex code that involves (for example) writing new libraries alongside the actual Arduino or ESP code, or working with files of different kinds all next to each other (as in the article summary). And the syntax error underlining and completion tools are helpful.

    But I suspect that VSCode / Platformio is overkill for those who are comfortable with the Arduino IDE, are writing simple code for Arduino or ESP, and are largely following “recipes” online using pre-baked libraries.

    VSCode / Platformio has a learning curve in terms of figuring out how folders are organized, where your code is, what the windows do, how to properly update libraries and board configuration files, etc. Hobbyists may find it’s not worth climbing that learning curve.

    A short take on it would be that VSCode / Platformio is more “programmer” focused while the Arduino IDE is more “hobbyist” focused.

    I myself bounce back and forth between the two — quite often switch back to the Arduino IDE when I find myself frustrated with a basic problem (often board compatibility) that I don’t know how to fix in VSCode / Platformio.

    Reply
    • Hi Jordan.
      That’s very true.
      It may be overwhelming for beginners. For simpler and smaller programs Arduino IDE works just fine.
      Thanks for sharing your experience.
      Regards,
      Sara

      Reply
  9. Have tried one of Your projects from book ordered from You. Works good in Windows, but
    in Linux i have problem not directly pertaining Your lesson but with Arduino IDE has problem with serial. I’m not talking about connecting board to computer’s USB, that works fine. It’s rather whether You call for “Serial.print” in code or not, when compiling it gives error: No module named ‘serial’. I understand that ESP32 needs python to work with IDE
    (or that I’m just assuming, correct me if I’m wrong). ESP8266 works fine. I have Python 3 installed ans also installed pyserial(with pip3 comm.) But no matter I tried it gives error again.

    Reply
  10. Thank you for this informative tutorial!
    Another HUGE benefit from using PIO is the portability!
    When using Arduino IDE, copying a project to another computer involves adding new boards or libraries using the board and library manager (often quite a hassle to satisfy all dependencies).
    By using the lib_deps statement in the platformio.ini PIO just downloads missing libraries!

    Reply
  11. Hi Sara,

    Thanks for providing details and steps for that.

    I am ESP8266 and ESP32 developer and I have total 2 to 2.5 years experience for same. Till now we are using ESP32 IDF behing our own SDK and developed almost 10 to 12 products.

    I just want to know that VS will support for ESP32 IDF or just for Arduino?

    Reply
  12. I have just started using VS Studio with PlatformIO. How do I “update” external libraries specified in “lib_deps” to the latest version?

    In the Arduino IDE, I just click on “Manage Libs” and it updates all my specified external libraries.

    Reply
    • Hi.
      If you want to use the latest version of the library, you can search for the library in the Libraries tab, select the installation tab and there should be several options for the lib_deps. Usually there’s something indicating the library version. So, you just need to copy the name of the latest version.
      Regards,
      Sara

      Reply
  13. I already followed the example in Windiws 10 without any problem. Only have a question: Why is required to load phyton?

    REgards

    Reply
  14. “Follow the next procedure if you need to install libraries in PlatformIO IDE.”
    Do you need to do this if you already have a lot of installed libraries under the Arduino IDE?

    Reply
    • Okay, yes. The libraries I’ve accumulated are within the Arduino file structure, not the PIO structure.
      I don’t think I want to import many of my Arduino projects into PIO. Converting .ino files and backtracking its libraries is a little bit of a pain. Going forward, on new projects, I will start using PIO instead of the arduino IDE, and I’ll give it a shot. But, the LED_blink example is a big help, and you guys have made implementing PIO pretty easy.

      Reply
  15. Put me down as a PlatformIO convert. Intellisense, variable and code hinting for the most part are a big help. “Attaching” a board to a project (by way of pasting two or three lines of formatted text into a project’s platform.ini file) is a better board management practice, as are attaching libraries that may change over time.

    You can import older sketches into PIO, you just have to make a few changes, like adding arduino include and changing the .ino file to .cpp.

    Reply
    • Hi Donald.
      That’s great!
      I’m glad you liked using PlatformIO. It’s way easier to write code and manage libraries.
      Once you get used to it, you won’t want to go back 🙂
      Regards,
      Sara

      Reply

Leave a Comment

Download our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.