How to Install and Configure PlatformIO for ESP32 in VS Code
**PlatformIO** is the industry-standard tool for compiling, flashing and debugging embedded systems. Integrated directly into **VS Code**, it removes the limitations of traditional IDEs.
platformio.ini for ESP32: Configuration Example
ESP32-S3 targetUse the block below in the platformio.ini file in your project to configure ESP32-S3 compilation.
| 1 | [env:esp32-s3-devkitc-1] |
| 2 | platform = espressif32 |
| 3 | board = esp32-s3-devkitc-1 |
| 4 | framework = arduino |
| 5 | monitor_speed = 115200 |
How to Install PlatformIO IDE in VS Code
1. Download and Install VS Code
Download the free Visual Studio Code for Windows, Linux or macOS from the official code.visualstudio.com website.
2. Install the PlatformIO IDE Extension
Open the Extensions tab (Ctrl+Shift+X), search for PlatformIO IDE and click Install.
3. Install USB-UART Drivers (CH340, CP2102, FTDI)
Make sure the USB-UART bridge drivers (CH340, CP2102 or FTDI) for your board are installed in the operating system.
This page summarizes the installation. For the complete path, with the VS Code screens step by step until the LED blinks, follow the ESP32 first steps in VS Code tutorial. For the display board, using the terminal, see the first steps with ESP32-C3 and a 1.44" LCD.
Folder Structure of an ESP32 PlatformIO Project
Contains the main source code (main.cpp or auxiliary .c/.cpp files).
Dedicated folder for header files and prototype definitions (.h / .hpp).
Stores custom local libraries specific to the project that are not in the global manager.
Space for automated unit tests using the Unity Framework.
Arduino Framework or ESP-IDF: Which Should You Use on ESP32?
| Feature | Arduino Framework | ESP-IDF (Native Espressif) |
|---|---|---|
| Learning curve | Easy / Fast prototyping | Intermediate / Advanced |
| Hardware control | Abstracted by friendly functions | Direct access to registers and low-level APIs |
| Flash memory usage | Medium (includes Arduino runtime) | Minimal / Fully optimized |
| FreeRTOS support | Available in the background | Native / Seamless task integration |
PlatformIO serial monitor (pio device monitor)
Open the serial terminal using the shortcut in the VS Code bottom bar or from the terminal:
pio device monitor -b 115200ESP32 firmware upload (pio run -t upload)
Flash the compiled file directly to the ESP32 over the USB cable:
pio run --target uploadAdd libraries with lib_deps in platformio.ini
Add dependencies to platformio.ini using the lib_deps directive.
pio Terminal Commands: Compile, Flash and Monitor the ESP32
Every action in the PlatformIO graphical interface has a CLI equivalent. Using pio directly in the VS Code integrated terminal is faster day to day and is the only path when you automate builds in scripts or CI pipelines.
| 1 | pio run # compile the firmware |
| 2 | pio run -t upload # flash the ESP32 |
| 3 | pio device monitor -b 115200 |
| 4 | pio device list # list serial ports |
| 5 | pio run -t clean # clean build artifacts |
| Command | What it does |
|---|---|
| pio run | Compiles the project for the environment defined in platformio.ini. |
| pio run -t upload | Compiles and flashes the firmware to the ESP32 over USB. |
| pio device monitor | Opens the serial monitor. Use -b to force the baud rate. |
| pio device list | Lists detected serial ports — useful when the board is not recognized. |
| pio run -t clean | Deletes build artifacts. It resolves many stubborn compilation errors. |
| pio pkg install | Downloads the libraries declared in lib_deps. |
To flash a specific port, add --upload-port COM5 on Windows or --upload-port /dev/ttyUSB0 on Linux. If the project has multiple environments in platformio.ini, select one with -e, for example pio run -e esp32-s3-devkitc-1 -t upload.
Common PlatformIO Errors with ESP32 and How to Fix Them
Hold the board's BOOT button when the terminal shows Connecting... or connect a 10uF capacitor between EN and GND.
Make sure the baud rate in monitor_speed exactly matches the value in Serial.begin(115200) in your C++ file.