VSCode & PlatformIO

Overview

Visual Studio Code (VSCode) with PlatformIO IDE is the recommended development environment for embedded programming on the ESP32 microcontroller. This combination provides a professional-grade embedded development workflow with powerful features like IntelliSense, debugging, serial monitoring, and library management.

VSCode Features

Modern code editor with syntax highlighting, Git integration, and extensions

PlatformIO Features

Embedded development platform with build automation, library manager, and serial monitor

Visual Studio Code

Installation

Download VSCode

Download from code.visualstudio.comSupported platforms:

Windows 10/11 (x64, ARM64)
macOS 10.15+ (Intel, Apple Silicon)
Ubuntu 20.04+ / Debian 10+

Install VSCode

Windows: Run the installer .exe filemacOS: Drag Visual Studio Code.app to Applications folderLinux:

sudo dpkg -i code_*.deb
# Or using snap
sudo snap install --classic code

Launch VSCode

Open VSCode and verify installation by checking Help → About

Essential Extensions

Beyond PlatformIO, these extensions enhance your development experience:

Extension	Purpose	Command
PlatformIO IDE	Embedded development (required)	`ext install platformio.platformio-ide`
C/C++	IntelliSense and debugging	`ext install ms-vscode.cpptools`
GitLens	Advanced Git integration	`ext install eamodio.gitlens`
Serial Monitor	Alternative serial port tool	`ext install ms-vscode.vscode-serial-monitor`
Doxygen	Code documentation	`ext install cschlosser.doxdocgen`

Install extensions from the Extensions sidebar (Ctrl+Shift+X / Cmd+Shift+X) or via Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

VSCode Configuration

Recommended settings for embedded development:

settings.json

{
  // Editor settings
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.formatOnSave": true,
  "editor.rulers": [80, 120],

  // C/C++ settings
  "C_Cpp.intelliSenseEngine": "default",
  "C_Cpp.clang_format_style": "Google",

  // File associations
  "files.associations": {
    "*.ino": "cpp",
    "*.h": "c",
    "*.tpp": "cpp"
  },

  // Terminal settings
  "terminal.integrated.defaultProfile.windows": "Command Prompt",
  "terminal.integrated.fontSize": 12,

  // Git settings
  "git.autofetch": true,
  "git.confirmSync": false
}

Access settings via File → Preferences → Settings (Windows/Linux) or Code → Preferences → Settings (macOS)

PlatformIO IDE

Installation

Open Extensions

Click Extensions icon in sidebar or press Ctrl+Shift+X / Cmd+Shift+X

Search PlatformIO

Search for “PlatformIO IDE” and click Install

Installation may take 5-10 minutes as it downloads toolchains and packages (~500MB)

Reload VSCode

Click Reload when prompted, or restart VSCode manually

Verify Installation

You should see the PlatformIO icon (alien head) in the sidebar

PlatformIO Home

Access PlatformIO Home by clicking the PIO Home icon (house) in the bottom status bar. Key sections:

Projects: Create and manage PlatformIO projects
Libraries: Browse and install 10,000+ embedded libraries
Boards: View supported development boards (ESP32, Arduino, STM32, etc.)
Platforms: Manage development platforms and frameworks
Devices: Monitor connected serial devices

Creating a New Project

Open PlatformIO Home

Click PIO Home icon in bottom status bar

Create New Project

Click + New Project button

Configure Project

Name: mecanum_robot_firmware
Board: Espressif ESP32 Dev Module
Framework: Arduino
Location: [Leave default or choose custom]

Click Finish and wait for project initialization

Explore Project Structure

mecanum_robot_firmware/
├── .pio/               # Build files (auto-generated)
├── include/            # Header files
├── lib/                # Project libraries
├── src/
│   └── main.cpp        # Main source file
├── test/               # Unit tests
└── platformio.ini      # Project configuration

platformio.ini Configuration

The platformio.ini file defines your project’s build environment:

platformio.ini

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

; Serial monitor settings
monitor_speed = 115200
monitor_filters =
    default
    time

; Build flags
build_flags =
    -D DEBUG=1
    -D CORE_DEBUG_LEVEL=3

; Upload settings
upload_speed = 921600
upload_port = /dev/ttyUSB0  ; macOS: /dev/cu.usbserial-*
                             ; Windows: COM3, COM4, etc.

; Library dependencies
lib_deps =
    Wire
    SPI
    adafruit/Adafruit ICM20X@^2.0.6
    adafruit/Adafruit BusIO@^1.14.1

Common platformio.ini Options

Platform options:

platform: Development platform (espressif32, atmelavr, etc.)
platform_packages: Override platform packages
board: Target board identifier
framework: Framework to use (arduino, espidf, etc.)

Build options:

build_flags: Compiler flags and macros
build_unflags: Remove default flags
lib_deps: Project library dependencies
lib_ignore: Libraries to exclude from build

Upload options:

upload_port: Serial port for uploading
upload_speed: Upload baud rate (default: 115200)
upload_protocol: Upload method (esptool, avrdude, etc.)

Monitor options:

monitor_speed: Serial monitor baud rate
monitor_port: Serial port for monitoring
monitor_filters: Output filters (colorize, time, log2file, etc.)

Build Commands

PlatformIO provides several build and upload commands accessible via:

Bottom toolbar buttons
Terminal commands (PlatformIO Core CLI)
Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

Task	Toolbar Icon	Terminal Command	Description
Build	✓ (checkmark)	`pio run`	Compile project
Upload	→ (arrow)	`pio run --target upload`	Upload to board
Clean	🗑️ (trash)	`pio run --target clean`	Delete build files
Monitor	🔌 (plug)	`pio device monitor`	Open serial monitor
Test	🧪 (flask)	`pio test`	Run unit tests

Use Upload and Monitor (plug with arrow icon) to upload and immediately start serial monitoring

Serial Monitor

The integrated serial monitor provides real-time output from your ESP32: Opening the monitor:

Click Serial Monitor icon (plug) in bottom toolbar
Or run pio device monitor in terminal

Monitor filters:

platformio.ini

monitor_filters =
    default          ; Default output
    colorize         ; ANSI color codes
    time             ; Add timestamps
    log2file         ; Save to file
    printable        ; Show only printable chars
    send_on_enter    ; Send commands on Enter

Exiting the monitor:

Press Ctrl+C in terminal
Or click Stop button in status bar

Library Management

Via PlatformIO Home
Via platformio.ini
Via CLI

Open PIO Home → Libraries
Search for library (e.g., “Adafruit ICM20X”)
Click library name → Add to Project
Select your project environment
Library automatically added to platformio.ini

Debugging

Serial Print Debugging

The most common debugging method for ESP32:

src/main.cpp

void setup() {
  Serial.begin(115200);
  Serial.println("\n=== ESP32 Mecanum Robot ===");
  Serial.printf("Firmware version: %s\n", VERSION);
}

void loop() {
  // Debug print encoder values
  Serial.printf("Encoders: FL=%ld FR=%ld RL=%ld RR=%ld\n",
                encoder_FL, encoder_FR, encoder_RL, encoder_RR);
  delay(100);
}

Use Serial.printf() for formatted output instead of multiple Serial.print() calls

Advanced Debugging (GDB)

PlatformIO supports hardware debugging with JTAG adapters:

platformio.ini

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

; Enable debugging
debug_tool = esp-prog         ; Or: jlink, ftdi, cmsis-dap
debug_init_break = tbreak setup
debug_build_flags = -O0 -g -ggdb

Supported debug adapters:

ESP-Prog: Official Espressif JTAG adapter (~$10)
J-Link: Professional debugger (~$400)
FTDI FT2232: Generic JTAG adapter (~$15)

Hardware debugging requires additional wiring to ESP32 JTAG pins (GPIO12, 13, 14, 15) and is optional for this project

Keyboard Shortcuts

Essential VSCode shortcuts for efficient development:

Action	Windows/Linux	macOS
Command Palette	Ctrl+Shift+P	Cmd+Shift+P
Quick Open File	Ctrl+P	Cmd+P
Toggle Terminal	Ctrl+`	Ctrl+`
Go to Definition	F12	F12
Find References	Shift+F12	Shift+F12
Format Document	Shift+Alt+F	Shift+Option+F
Multi-cursor	Alt+Click	Option+Click
Comment Line	Ctrl+/	Cmd+/
Duplicate Line	Shift+Alt+↓	Shift+Option+↓

Troubleshooting

PlatformIO installation fails or gets stuck

Symptoms: Installation hangs at “Installing PlatformIO Core…”Solutions:

Check internet connection (downloads ~500MB)
Disable antivirus temporarily
Install Python 3.6+ manually first

Clear PlatformIO cache:

# Windows
rmdir /s %USERPROFILE%\.platformio

# macOS/Linux
rm -rf ~/.platformio

Reinstall PlatformIO extension

ESP32 not detected / upload failed

Symptoms: Error: Could not open /dev/ttyUSB0Solutions:

Install CP2102 or CH340 USB driver
- Windows: Download from Silicon Labs or WCH
- macOS: brew install --cask silicon-labs-vcp-driver
- Linux: Usually built-in, add user to dialout group:
  sudo usermod -a -G dialout $USER # Logout and login again

Check correct port in platformio.ini:

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

Hold BOOT button while clicking Upload
Check USB cable (must be data cable, not charge-only)

IntelliSense not working / red underlines

Symptoms: Code shows errors but compiles successfullySolutions:

Rebuild IntelliSense:
- Ctrl+Shift+P → “C/C++: Reset IntelliSense Database”
Update C/C++ configuration:
- Ctrl+Shift+P → “C/C++: Edit Configurations (JSON)”
- Ensure compilerPath points to PlatformIO toolchain
Clean and rebuild:
```
pio run --target clean
pio run
```
Check .vscode/c_cpp_properties.json exists

Library not found / compilation error

Symptoms: fatal error: library.h: No such file or directorySolutions:

Verify library in platformio.ini:

lib_deps =
    adafruit/Adafruit ICM20X@^2.0.6

Clean and rebuild to download dependencies:
```
pio run --target clean
pio run
```
Check library compatibility with ESP32
Manually install library:
```
pio lib install "Adafruit ICM20X"
```

Serial monitor shows garbage characters

Symptoms: Output shows random symbols: ��ߟ��Solutions:

Baud rate mismatch - Most common issue:

// In code:
Serial.begin(115200);

# In platformio.ini:
monitor_speed = 115200

Both must match!

Check wiring if using external USB-to-Serial adapter
Try standard baud rates: 9600, 57600, 115200

Best Practices

Project Organization

Keep main.cpp minimal, use separate files for motors, sensors, etc.
Put reusable code in lib/ folder
Use meaningful names for files and functions
Comment complex algorithms

Version Control

Commit working code frequently
Add .pio/ and .vscode/ to .gitignore
Write descriptive commit messages
Use branches for experimental features

Code Quality

Enable format on save
Use consistent indentation (2 or 4 spaces)
Keep functions under 50 lines
Avoid global variables when possible

Testing

Test on hardware frequently, not just simulation
Add debug prints for critical values
Use unit tests in test/ folder
Document known issues in README

Next Steps

ESP32 Basics

Learn ESP32 GPIO, PWM, and interrupt configuration

Motor Control

Implement PID motor control with encoders

Git & GitHub

Set up version control for team collaboration

Hardware Reference

ESP32 specifications and pinout diagrams

Hardware

Software Tools

ROS2 Concepts

Code Examples

Overview

VSCode Features

PlatformIO Features

Visual Studio Code

Installation

Essential Extensions

VSCode Configuration

PlatformIO IDE

Installation

PlatformIO Home

Creating a New Project

platformio.ini Configuration

Build Commands

Serial Monitor

Library Management

Debugging

Serial Print Debugging

Advanced Debugging (GDB)

Keyboard Shortcuts

Troubleshooting

Best Practices

Project Organization

Version Control

Code Quality

Testing

Next Steps

ESP32 Basics

Motor Control

Git & GitHub

Hardware Reference

References

Hardware

Software Tools

ROS2 Concepts

Code Examples

​Overview

VSCode Features

PlatformIO Features

​Visual Studio Code

​Installation

​Essential Extensions

​VSCode Configuration

​PlatformIO IDE

​Installation

​PlatformIO Home

​Creating a New Project

​platformio.ini Configuration

​Build Commands

​Serial Monitor

​Library Management

​Debugging

​Serial Print Debugging

​Advanced Debugging (GDB)

​Keyboard Shortcuts

​Troubleshooting

​Best Practices

Project Organization

Version Control

Code Quality

Testing

​Next Steps

ESP32 Basics

Motor Control

Git & GitHub

Hardware Reference

​References

Overview

Visual Studio Code

Installation

Essential Extensions

VSCode Configuration

PlatformIO IDE

Installation

PlatformIO Home

Creating a New Project

platformio.ini Configuration

Build Commands

Serial Monitor

Library Management

Debugging

Serial Print Debugging

Advanced Debugging (GDB)

Keyboard Shortcuts

Troubleshooting

Best Practices

Next Steps

References