ESP32 PlatformIO: How To Program Your ESP32 in VS Code!

If you’ve ever used the Arduino IDE for your ESP32 projects, you know it gets the job done, but it has limitations. From a basic text editor with minimal autocomplete to poor project organization, the Arduino IDE can quickly feel outdated and restrictive.

That’s where PlatformIO in Visual Studio comes in.
In this beginner-friendly guide, I’ll show you how to program your ESP32 using PlatformIO inside VS Code. This modern development environment brings useful tools like intelligent code completion, proper syntax highlighting, and a lot more!

Why Use PlatformIO Instead of the Arduino IDE?

While the Arduino IDE is great for getting started, you will encounter several limitations when diving deeper into embedded development.

For instance, the Arduino IDE doesn’t offer an autocompletion feature that would make programming way faster.
On PlatformIO with VS Code, when typing “digi”, a proper autocompletion would already suggest the function “digitalWrite()”. Also, it will show you information, like the parameters of the function and its return type.

That’s only one of many advantages PlatformIO has over the Arduino IDE. Here’s a list of the most important advantages:

• Supports multiple frameworks (e.g., Arduino, ESP-IDF)
• Advanced debugging and testing tools (paid plan)
• Intelligent autocompletion
• Proper syntax highlighting
• File explorer with tabs and advanced code navigation
• Modern and feature-rich development environment with Visual Studio Code
• …

#1: Install Visual Studio Code

If you haven’t already, download and install Visual Studio Code from Microsoft. It’s a lightweight, open-source, and powerful code editor available for Windows, macOS, and Linux.

Head to the official download page and download the installer for your operating system.
Then run it and follow the instructions there.

#2: Install the PlatformIO Extension

Start Visual Studio Code and click the extensions button (4 blocks) on the left.

Next, search for PlatformIO in the search bar and install the PlatformIO IDE extension by hitting install.

This process might take a few minutes, so don’t worry. When it’s finished, there will be a message in the bottom right corner. As soon as you see this message, restart VS Code.

After the restart, there should be an alien icon under the extensions button on the left. That’s your PlatformIO home button. If you click on it, you are greeted with the PlatformIO Home tab, where you can open and create projects, see your recent projects, some news, along some other information.

If you don’t see the home tab when clicking the PlatformIO button, click on the PlatformIO button again and then QUICK ACCESS > PIO Home > Open.

#3: Create a New ESP32 PlatformIO Project

Let’s create a new ESP32 project inside PlatformIO!

To do so, hit “New Project” in your PlatformIO home view.

Next, you can enter a name for your project, select your board, and a Framework. After selecting an ESP32 board, you can choose between the Arduino and the ESP-IDF framework.
In this tutorial, we will be using the Arduino framework, as that’s what most developers are familiar with coming from the Arduino IDE.

After hitting finish, your new project will be created.

Because this is the first time you create a project, PlatformIO needs to download the toolchain required for your board type and framework. Hence, this process takes a while.

#4: Write Your First Sketch

Now that your first project is created, we can get into writing the first code.

Probably, the first thing you see is a file called platformio.ini. We will cover that later on.
Additionally, there’s a project explorer tab on the left, which shows multiple folders, a .gitignore file, and the platformio.ini.

The folders that are the most important to us are the lib folder and the src folder.

The lib folder is where our main source code will go, just like you may know it from the Arduino IDE.

The src folder, on the other hand, is where we put our own libraries. For instance, if we’ve written a library called LEDController, we create a folder inside lib called LEDController, and place the header and cpp file there.

These libraries can be accessed in the source code like any other libraries you might include. For example:

#include <LEDController.h>

For more details, read the README file inside lib.

Blinking an LED

To start writing a simple test program, open the src folder. Probably, there already is a file called main.cpp filled with some other example code.

Feel free to remove all of that and write your own blink sketch, like you would in the Arduino IDE.
You can also use this one:

#include <Arduino.h>

const int LED = 2;

void setup() {
  pinMode(LED, OUTPUT);
}

void loop() {
  digitalWrite(LED, HIGH);
  delay(250);
  digitalWrite(LED, LOW);
  delay(250);
}

Always make sure to include Arduino.h at the top to make use of the Arduino framework!

In addition, your source code files are now regular .cpp files, not .ino files like they were used in the Arduino IDE.

#5: Upload ESP32 PlatformIO Code

Last but not least, we need to upload the program to our ESP32.

Before we can do that, however, we must specify the COM port for uploading and reading the serial monitor. That’s where the platformio.ini file comes in.
Inside it, you need to specify the upload_port and monitor_port as follows:

upload_port = COM4
monitor_port = COM4

On Linux, the ports are specified differently:

upload_port = /dev/ttyUSB*
monitor_port = /dev/ttyUSB*

The asterisk (*) means that the first port matching the preceding expression will be used. This also works on Windows with COM*.

Hint: You can also specify an IP address as the upload port for OTA (Over-The-Air) programming.

Additionally, you can specify the baud rate for the serial monitor with the following line inside platformio.ini:

monitor_speed = 115200

After all of that has been set up, we can now upload the program via the little arrow button located at the bottom of the VS Code window.

Including External Libraries

One of PlatformIO’s strengths is how easy it makes it to manage libraries.

Because PlatformIO lists all the libraries used in a project in the platformio.ini file, sharing your project or working on it from different computers doesn’t require you to collect and install all the libraries manually again. Instead, it will automatically download all the required libraries to compile the project.

Method 1: Using the Library Manager

PlatformIO has its own library manager, where you can search for libraries and add them to your project.

You can access the library manager from your PlatformIO Home tab, where you can search for the library you need. If you click on it, you have the option to directly add it to your project.

Always make sure that your board is supported by the library though.

Method 2: Adding Libraries Manually in platformio.ini

Instead of using the “Add to Project” button from the library manager, you can manually add libraries in the platformio.ini file. This way, you can also add libraries from GitHub that are not listed in the library manager.

Open the platformio.ini file and add the libraries by their name from the library manager or the GitHub link as follows:

lib_deps = 
    TensorFlowLite_ESP32@1.0.0
    https://github.com/bblanchon/ArduinoJson.git

You can also specify the version of a library using the @ symbol followed by the version number.

Note that for using libraries from GitHub, you need to have Git installed on your computer.

Accessing the Serial Monitor in PlatformIO

Accessing the Serial Monitor on PlatformIO is very easy. Just click on the little plug icon located at the bottom of your VS Code window.

Troubleshooting Tips

• Upload Failed? Make sure the right COM port is selected and no other app is using the port. Also, if your board doesn’t automatically switch into upload mode, press the BOOT button on your board while uploading.
• Board not recognized? You might need to install the USB drivers for your ESP32 board.

Conclusion

PlatformIO is a fantastic tool for programming the ESP32 in a professional development environment. Once you get used to it, you’ll never want to go back!

Have questions or run into issues? Drop a comment below or reach out through the contact page!

Thanks for reading, happy coding!