How to Set Up ESP32 on PlatformIO with VS Code: Complete Step-by-Step Guide
Oct 23th,2025
ESP32 PlatformIO setup makes developing projects on the ESP32 easier than ever, thanks to PlatformIO — a modern, open-source ecosystem for IoT development.Unlike the traditional Arduino IDE, PlatformIO offers powerful build automation, dependency management, and debugging tools, all neatly integrated into Visual Studio Code (VS Code).This makes it one of the most beginner-friendly options for anyone following an ESP32 VS Code tutorial.
For developers working on multiple boards or complex firmware, PlatformIO simplifies the workflow: it automatically manages the compiler toolchains, board definitions, and libraries. You can switch between frameworks such as Arduino or ESP-IDF, and work in a clean, modular environment. To learn more about ESP32 frameworks, visit the SunFounder ESP32 Tutorial.In short, PlatformIO provides a professional-grade setup for ESP32 development—faster builds, better library handling, and a fully integrated development environment right inside VS Code.
Prerequisites
Before setting up PlatformIO for ESP32 development, make sure you have the following components ready:
•Visual Studio Code (VS Code): The primary editor and interface for PlatformIO.
•PlatformIO IDE extension: Available from the VS Code Marketplace.
•ESP32 development board: Such as the ESP32 DevKit V1 or NodeMCU-32S.
•USB cable: Used to connect your ESP32 board to the computer.
•USB driver: Depending on your board, you'll need either the CP210x or CH340 driver.
oCP210x is common on boards made by Espressif or DOIT.
oCH340 appears on many clone boards or lower-cost versions.
Once these prerequisites are installed, you’ll be ready to set up your ESP32 development environment and write your first project.
Install and Configure PlatformIO
To install PlatformIO for ESP32, open VS Code and go to the Extensions section on the left toolbar.
1.Open VS Code and go to the Extensions section on the left toolbar.
2.Search for “PlatformIO IDE” and click Install.
3.Once the installation completes, PlatformIO will appear as a new icon (an ant’s head) on the sidebar.
The first time you open PlatformIO, it automatically sets up its core environment—downloading the necessary compilers, frameworks, and board packages. You can find a detailed walkthrough in the SunFounder PlatformIO Setup Guide.This process may take a few minutes the first time, but only needs to be done once.
After installation, open a new terminal inside VS Code and type:
pio --version
If you see a version number, PlatformIO is correctly installed and ready.
Create a New ESP32 Project in PlatformIO
To start your first ESP32 project:
1.Click the PlatformIO icon on the sidebar and select “New Project”.
2.Enter a project name, for example:
3.esp32_blink
4.For the Board, choose “Espressif ESP32 Dev Module.”
5.Under Framework, select Arduino— this step ensures your project uses the PlatformIO Arduino framework for ESP32.
6.Choose a location to save your project and click Finish.
PlatformIO will now generate a complete project structure:
•src/ – Contains your main application source code (for example, main.cpp).
•include/ – Header files for project-wide declarations.
•lib/ – Custom libraries you may create.
•platformio.ini – The project configuration file, which defines your board, framework, and build options.
This structure keeps everything organized and easy to maintain, especially when your project grows in complexity.
Quick Test: Blink + Serial Monitor
Let’s test your setup with an ESP32 blink example to confirm everything works properly.Open the file src/main.cpp and replace its contents with:
#include <Arduino.h>
#define LED_PIN 2
void setup() {
Serial.begin(115200); pinMode(LED_PIN, OUTPUT); Serial.println("ESP32 Blink Test Started");
}
void loop() {
digitalWrite(LED_PIN, HIGH);
delay(1000);
digitalWrite(LED_PIN, LOW);
delay(1000);}
Now connect your ESP32 board via USB and click the checkmark icon (✓) at the bottom of VS Code to build the code. Once it compiles successfully, click the right arrow icon (→) to upload the firmware to your ESP32.
After uploading, open the Serial Monitor by clicking the plug icon at the bottom or pressing Ctrl + Alt + M. Set the baud rate to 115200 to complete your ESP32 Serial Monitor setup.You should see the message:
ESP32 Blink Test Started
and the onboard LED should blink once per second. If it does, congratulations—your development setup works perfectly.
Edit platformio.ini
The platformio.ini file is the heart of every PlatformIO project. If you want to configure platformio.ini for ESP32, this file defines exactly how your firmware is built and uploaded.
Here's a simple example:
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
upload_speed = 921600
Explanation:
•platform: specifies the chipset family (ESP32).
•Board: identifies your exact board model.
•Framework: defines which SDK you're using—Arduino or ESP-IDF.
•monitor_speed: sets the baud rate for Serial Monitor.
•upload_speed: determines how fast your code uploads.
You can modify this file to add more settings or even define multiple environments if you use several boards.
Manage Libraries
ESP32 library management in PlatformIO is one of its biggest advantages, thanks to its automatic handling of dependencies and updates. You can add libraries in two ways:
1.Via the PlatformIO interface:
oOpen the Libraries tab from the PlatformIO sidebar.
oSearch for the desired library (for example, “DHT sensor”).
oClick Add to Project and choose your project.
2.Manually in platformio.ini:
You can directly declare dependencies in the configuration file:
lib_deps =
adafruit/Adafruit Unified Sensor
adafruit/DHT sensor library
When you build the project, PlatformIO automatically downloads and installs these libraries (see the PlatformIO Library Manager documentation for details).This method ensures consistent environments across different computers or collaborators.
Project Tips
To keep your ESP32 projects clean and manageable:
•Use the right folders:
oPut all main code in src/.
oPlace reusable code or custom libraries in lib/.
•Comment your code clearly. Explain what each section does, especially setup routines and pin assignments.
•Use version control (Git): PlatformIO projects integrate well with GitHub or GitLab.
•Name files descriptively: For instance, wifi_manager.cpp or sensor_handler.cpp helps you navigate large projects easily.
•Keep backups of your platformio.ini file—it contains all build configurations and is essential for reproducibility.
These habits save hours of debugging and make it easier to share or revisit your work later.
Troubleshooting
Even with the right setup, a few common issues might appear. Here’s a quick troubleshooting ESP32 upload error guide to help you fix them efficiently:
•Upload Error (Failed to connect to ESP32):
oCause: Wrong serial port or the board not in boot mode.
oFix: Check platformio.ini for the correct port, or hold the BOOT button while uploading.
•Serial Output Unreadable:
oCause: Baud rate mismatch.
oFix: Make sure the Serial.begin() value matches your monitor_speed in platformio.ini.
•Missing Library Error:
oCause: The required library isn't installed.
oFix: Install it using pio lib install or add it under lib_deps in your configuration file.
If problems persist, check the PlatformIO Terminal output for detailed logs. The messages usually contain hints about what went wrong. For more troubleshooting examples, visit the SunFounder ESP32 Troubleshooting Guide.
Conclusion
You've now completed the full ESP32 setup on PlatformIO with VS Code — from installation to running your first Blink program. With PlatformIO’s advanced features like automated library management, customizable configuration, and integrated debugging, you have a powerful and professional development environment at your fingertips. This setup not only streamlines your workflow but also prepares you for larger, more complex ESP32 projects.Next, you can explore topics like Wi-Fi connectivity, OTA updates, or FreeRTOS to unlock the full potential of your ESP32.
