Skip to main content

​
Overview

Setting up a proper development environment is crucial for productive embedded programming. We’ll use VSCode with PlatformIO, which provides excellent support for ESP32 development.

​
Why VSCode + PlatformIO?

Better than Arduino IDE

  • IntelliSense (code completion)
  • Advanced debugging
  • Git integration
  • Professional IDE features

Library Management

  • Easy library installation
  • Dependency management
  • Multiple boards/platforms
  • Built-in examples

​
Installation Steps

​
Step 1: Install VSCode

  • Windows
  • macOS
  • Linux (Ubuntu)
  1. Download from https://code.visualstudio.com/
  2. Run installer (VSCodeUserSetup-x64-X.XX.X.exe)
  3. Important: Check “Add to PATH” during installation
  4. Complete installation

​
Step 2: Install PlatformIO Extension

  1. Open VSCode
  2. Click Extensions icon (or Ctrl+Shift+X)
  3. Search for “PlatformIO IDE”
  4. Click “Install”
  5. Wait for installation (may take 5-10 minutes)
  6. Restart VSCode when prompted
PlatformIO extension in VSCode marketplace

​
Step 3: Install USB Drivers (Windows only)

ESP32 uses CP2102 or CH340 USB-to-Serial chips: CP2102 Driver: CH340 Driver: Mac/Linux: Usually works out of the box! No drivers needed.

​
Step 4: Verify Installation

  1. Open VSCode
  2. Click PlatformIO icon in left sidebar (alien head)
  3. Should see PlatformIO Home screen
  4. If not, check for error messages in Output panel

​
Create First Project

1

New Project

  1. Click “New Project” in PlatformIO Home
  2. Name: “ESP32_Blink_Test”
  3. Board: “Espressif ESP32 Dev Module”
  4. Framework: “Arduino”
  5. Location: Choose folder
  6. Click “Finish”
2

Project Structure

ESP32_Blink_Test/
├── .pio/              # Build files (auto-generated)
├── include/           # Header files
├── lib/               # Project-specific libraries
├── src/
│   └── main.cpp       # Your code goes here
├── test/              # Unit tests
└── platformio.ini     # Project configuration
3

Write Blink Code

Open src/main.cpp and replace with:
#include <Arduino.h>

#define LED_PIN 2  // Built-in LED on most ESP32 boards

void setup() {
  pinMode(LED_PIN, OUTPUT);
  Serial.begin(115200);
  Serial.println("ESP32 Blink Test Starting...");
}

void loop() {
  digitalWrite(LED_PIN, HIGH);
  Serial.println("LED ON");
  delay(1000);
  
  digitalWrite(LED_PIN, LOW);
  Serial.println("LED OFF");
  delay(1000);
}
4

Connect ESP32

  • Plug ESP32 into computer via USB
  • Check COM port in Device Manager (Windows) or ls /dev/tty* (Mac/Linux)
5

Upload Code

  1. Click checkmark icon (Build) - should compile successfully
  2. Click arrow icon (Upload) - uploads to ESP32
  3. Watch for “Success” message
  4. LED should blink!
6

Open Serial Monitor

  • Click plug icon (Serial Monitor)
  • Set baud rate to 115200
  • Should see “LED ON” / “LED OFF” messages
Upload Issues? Try holding BOOT button on ESP32 while clicking Upload. Some boards require this.

​
PlatformIO Configuration

​
platformio.ini Explained

[env:esp32dev]
platform = espressif32        # ESP32 platform
board = esp32dev              # Board type
framework = arduino           # Use Arduino framework
monitor_speed = 115200        # Serial baud rate
upload_port = COM3            # Specify port (optional)
monitor_port = COM3           # Specify monitor port (optional)

# Optional: Library dependencies
lib_deps =
    br3ttb/PID@^1.2.1        # PID library
    adafruit/Adafruit BusIO@^1.14.1  # I2C/SPI library

# Optional: Build flags
build_flags =
    -D DEBUG=1               # Enable debug output
    -D ENCODER_CPR=330       # Counts per revolution

​
Useful PlatformIO Commands

Build

  • Icon: Checkmark ✓
  • Shortcut: Ctrl+Alt+B
  • Compiles code without uploading

Upload

  • Icon: Right arrow →
  • Shortcut: Ctrl+Alt+U
  • Builds and uploads to board

Serial Monitor

  • Icon: Plug icon
  • Shortcut: Ctrl+Alt+S
  • View serial output

Clean

  • Via PlatformIO menu
  • Removes build artifacts
  • Use if strange compile errors

​
Installing Libraries

  1. Click PlatformIO icon → Libraries
  2. Search for library (e.g., “PID”)
  3. Click desired library
  4. Click “Add to Project”
  5. Select your project
  6. Library added to platformio.ini

​
Method 2: Manual in platformio.ini

Add to [env:esp32dev] section: 
lib_deps =
    br3ttb/PID@^1.2.1
    adafruit/Adafruit ICM20X@^2.0.5
    sparkfun/SparkFun ICM-20948 Arduino Library@^1.2.12
Save file, PlatformIO auto-downloads libraries.

​
Method 3: Local Library

  1. Create folder in lib/ directory
  2. Add .h and .cpp files
  3. Include in code: #include "MyLibrary.h"
Enhance VSCode with these extensions:
  • C/C++ (Microsoft) - IntelliSense, debugging
  • Serial Monitor (Microsoft) - Alternative serial viewer
  • GitLens - Git visualization
  • Bracket Pair Colorizer - Easier to read nested code
  • Teleplot - Real-time data plotting from serial

​
Troubleshooting

Solutions:
  • Check internet connection
  • Disable antivirus temporarily
  • Manually install Python 3.6+ first
  • Try VSCode Insiders build
Solutions:
  • Install CP2102 or CH340 drivers
  • Try different USB cable (some are power-only!)
  • Try different USB port
  • Check Device Manager for unknown devices
Solutions:
  • Hold BOOT button while clicking Upload
  • Check correct COM port selected
  • Close Serial Monitor before uploading
  • Press RESET button after upload starts
Solutions:
  • Check for typos in code
  • Verify all #include statements
  • Clean project (PlatformIO → Clean)
  • Delete .pio folder and rebuild
Solutions:
  • Check baud rate matches code (115200)
  • Verify correct COM port
  • Press ESP32 RESET button
  • Check USB cable quality

​
Best Practices

Version Control

  • Initialize Git in project folder
  • Add .pio/ to .gitignore
  • Commit regularly
  • Push to GitHub

Code Organization

  • Separate concerns (motor.cpp, encoder.cpp)
  • Use header files (.h)
  • Modular functions
  • Comments and documentation

Testing

  • Test incrementally
  • Unit test each component
  • Use Serial.println() for debugging
  • Log important values

Power Management

  • Use external power for motors
  • Don’t power motors from USB!
  • Common ground between ESP32 and motor supply

​
Next Steps

ESP32 Basics

Learn ESP32 pinout and features

Motor Driver

Understand IBT-2 H-bridge

DC Motor Control

Start implementing motor control

Code Examples

See working code examples

​
References

[1] PlatformIO Documentation: https://docs.platformio.org/ [2] ESP32 Arduino Core: https://github.com/espressif/arduino-esp32 [3] VSCode Tips: https://code.visualstudio.com/docs/getstarted/tips-and-tricks