Installation and Setup

PlatformIO is a professional development platform that runs as an extension inside Visual Studio Code (VS Code). It supports the same Arduino framework as the Arduino IDE, so your C++ code is identical -- but the editing experience, project management, and tooling are significantly more powerful.

If you are already comfortable with VS Code, or plan to work on larger projects, PlatformIO is an excellent choice. If you prefer simplicity and a gentler learning curve, the Arduino IDE Setup guide is the easier starting point.

🔗Why PlatformIO?

PlatformIO adds several features that the Arduino IDE lacks:

The tradeoff is complexity: PlatformIO has more to learn upfront. But once set up, day-to-day development is faster and more comfortable, especially for projects with multiple source files or external libraries.

🔗Step 1: Install Visual Studio Code

Download VS Code for your operating system from the official website:

https://code.visualstudio.com

VS Code is available for Windows, macOS, and Linux. Run the installer and follow the standard installation process.

Note: VS Code is not the same as Visual Studio. VS Code is a lightweight, free code editor. Visual Studio is Microsoft's full IDE, which is much heavier and not what we want here.

Linux users: VS Code is available as a .deb or .rpm package from the download page, via Snap (snap install code --classic), or through Flatpak. The official .deb/.rpm packages are generally the most reliable for extension compatibility.

🔗Step 2: Install the PlatformIO Extension

1. Open VS Code
2. Click the Extensions icon in the left sidebar (or press Ctrl+Shift+X)
3. In the search box, type PlatformIO IDE
4. Find "PlatformIO IDE" by PlatformIO (it should be the top result)
5. Click Install

The installation takes a minute or two. PlatformIO will download its core tools in the background. When it finishes, you will see a new PlatformIO icon (an alien head) in the left sidebar, and a small toolbar will appear at the bottom of the VS Code window.

Tip: After installation, VS Code may prompt you to reload the window. Do so if asked. If the PlatformIO Home tab does not appear automatically, click the PlatformIO icon in the sidebar or press Ctrl+Shift+P and type "PlatformIO: Home".

🔗Step 3: Create a New Project

1. Open PlatformIO Home (click the house icon in the bottom toolbar, or use the PlatformIO sidebar)
2. Click New Project
3. Fill in the project settings:
   • Name: esp32-test (or whatever you like)
   • Board: Type ESP32 Dev Module and select "Espressif ESP32 Dev Module"
   • Framework: Select Arduino
   • Location: Use the default location, or choose a custom folder
4. Click Finish

PlatformIO will create the project and download the ESP32 toolchain (compiler, uploader, board definitions). The first project takes a few minutes because of this initial download -- subsequent projects are much faster.

🔗Understanding the Project Structure

After creation, your project looks like this:

esp32-test/
├── src/
│   └── main.cpp          <-- Your code goes here
├── lib/                   <-- Project-specific libraries
├── include/               <-- Header files
├── test/                  <-- Unit tests (optional)
├── platformio.ini         <-- Project configuration
└── .pio/                  <-- Build output (auto-generated, do not edit)

The key differences from Arduino IDE:

• Your main sketch is src/main.cpp, not a .ino file
• You must include #include <Arduino.h> at the top of main.cpp -- the Arduino IDE adds this implicitly behind the scenes, but PlatformIO does not
• Configuration lives in platformio.ini instead of dropdown menus
• Libraries are managed through the config file, not a graphical manager

🔗Step 4: Configure platformio.ini

Open platformio.ini in the project root. It should look something like this:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

If monitor_speed is not present, add it. This sets the Serial Monitor baud rate to 115200, matching the standard ESP32 convention.

Here are the key settings and what they mean:

Tip: You can add upload_speed = 921600 to speed up uploads. If you experience upload failures, try upload_speed = 115200 instead.

🔗Step 5: Write a Test Sketch

Open src/main.cpp. Replace the contents with:

#include <Arduino.h>  // Required in PlatformIO -- Arduino IDE adds this automatically

void setup() {
  Serial.begin(115200);
  delay(1000);
  Serial.println("ESP32 is working!");
}

void loop() {
  Serial.println("Hello from ESP32");
  delay(2000);
}

This is the same test sketch from the Arduino IDE setup guide, with one difference: the #include <Arduino.h> line at the top. Without it, the compiler will not recognize Serial, delay, pinMode, or any other Arduino functions.

Important: Every src/main.cpp file in a PlatformIO Arduino project needs #include <Arduino.h> at the top. This is the single most common mistake when switching from Arduino IDE to PlatformIO.

🔗Step 6: Build and Upload

Connect your ESP32 board via USB, then:

1. Build -- Click the checkmark icon in the bottom toolbar, or press Ctrl+Alt+B. This compiles your code without uploading.
2. Upload -- Click the right arrow icon in the bottom toolbar, or press Ctrl+Alt+U. This compiles and uploads to the board.

PlatformIO automatically detects the serial port in most cases. If it picks the wrong port (rare, but possible if you have multiple serial devices), add this to platformio.ini:

upload_port = /dev/ttyUSB0   ; Linux
; upload_port = COM3          ; Windows
; upload_port = /dev/cu.usbserial-0001  ; macOS

A successful upload ends with output similar to:

Leaving...
Hard resetting via RTS pin...
========================= [SUCCESS] Took 12.34s =========================

🔗If Upload Fails

• "No such file or directory" or "could not open port" -- PlatformIO cannot find the serial port. Make sure the board is plugged in and the USB cable supports data (not charge-only).

• "A fatal error occurred: Failed to connect to ESP32" -- Hold down the BOOT button on your ESP32 while the upload starts, and release it once you see "Writing at 0x00010000..." in the output.

• Permission denied on Linux -- Add your user to the dialout group:

  sudo usermod -a -G dialout $USER

  Log out and back in for this to take effect.

🔗Step 7: Open the Serial Monitor

Click the plug icon in the bottom toolbar, or press Ctrl+Alt+S. You can also open a terminal in VS Code and run:

pio device monitor

You should see:

ESP32 is working!
Hello from ESP32
Hello from ESP32
Hello from ESP32

If you see garbled text, make sure monitor_speed = 115200 is in your platformio.ini.

To close the Serial Monitor, press Ctrl+C in the terminal, or click the trash icon on the terminal tab.

Note: The Serial Monitor must be closed before you can upload new code. PlatformIO usually handles this automatically -- it closes the monitor, uploads, and reopens it. If upload fails with a "port busy" error, close the Serial Monitor manually and try again.

🔗Installing Libraries

One of PlatformIO's biggest advantages is declarative library management. Instead of manually searching and installing libraries through a GUI, you list them in platformio.ini:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

lib_deps =
    adafruit/DHT sensor library@^1.4.0
    adafruit/Adafruit Unified Sensor@^1.1.0

When you build, PlatformIO automatically downloads and installs the listed libraries (and their dependencies). This makes projects reproducible -- anyone who opens your project gets the exact same library versions.

🔗Finding Library Names

To find the correct name for a library:

1. Go to the PlatformIO Registry
2. Search for the library
3. Copy the install name from the library page

You can also use the PlatformIO sidebar in VS Code: click the PlatformIO icon, then Libraries, and search from there. Click Add to Project to automatically add the lib_deps entry.

🔗Common Issues

🔗The PlatformIO Toolbar

The bottom toolbar in VS Code is your main control panel. From left to right:

🔗Next Steps

Your PlatformIO environment is ready. The next article walks you through writing and understanding your first real ESP32 program -- the classic blink sketch -- using PlatformIO's workflow.

Prefer something simpler? If PlatformIO feels like too much right now, the Arduino IDE Setup guide gets you running in fewer steps. You can always switch to PlatformIO later -- the code is the same.