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.
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:
Installing VS Code (Visual Studio Code):
A) Windows
B) Mac OS X
C) Linux Ubuntu
Installing PlatformIO IDE Extension on VS Code
Visual Studio Quick Interface Overview
PlatformIO IDE Overview
Uploading Code using PlatformIO IDE: ESP32/ESP8266
Changing the Serial Monitor Baud Rate – PlatformIO IDE
Installing Libraries on PlatformIO IDE
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).
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.
Select the following options and click
Next
Press the
Install
button.
Finally, click
Finish
to finish the installation.
Open VS Code and you’ll be greeted by a Welcome tab with the released notes of the newest version.
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.
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.
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).
After downloading the Visual Studio Code application file, you’ll be prompted with the following message. Press the “
Open
” button.
Or open your Downloads folder and open Visual Studio Code.
After that, you’ll be greeted by a Welcome tab with the released notes of the newest version.
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)\"
Then, run the brew command to install Python 3.X:
$ brew install python3
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).
Save the installation file:
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.
Open VS Code and you’ll be greeted by a Welcome tab with the released notes of the newest version.
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
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
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:
Click on the
Extensions
icon or press
Ctrl
+
Shift
+
to open the
Extensions
tab
PlatformIO IDE
”
Select the first option
Finally, click the
Install
button (Note: the installation may take a few minutes)
After installing, make sure that PlatformIO IDE extension is enabled as shown below.
After that, the PlatformIO icon should show up on the left sidebar as well as an
icon that redirects you to PlatformIO home.
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:
File explorer
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.
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.
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.
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
icon. Click on
+ New Project
to start a new project.
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”.
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:
The Blink_LED project should be accessible from the Explorer tab.
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