Skip to content

HowTo Setup PlatformIO

Jump to bottom
miswired edited this page Feb 7, 2026 · 2 revisions

How To: Set Up PlatformIO Development Environment

This guide walks you through setting up PlatformIO to build and upload Glitchy firmware.

Note: PlatformIO is the current recommended build system, replacing the older Arduino IDE setup.

Prerequisites

  • A computer running Windows, macOS, or Linux
  • USB cable for ESP32-S3 connection
  • Basic familiarity with command line or VS Code

Option A: VS Code with PlatformIO Extension (Recommended)

1. Install Visual Studio Code

Download and install VS Code from code.visualstudio.com.

2. Install PlatformIO Extension

  1. Open VS Code
  2. Click the Extensions icon in the sidebar (or press Ctrl+Shift+X)
  3. Search for "PlatformIO IDE"
  4. Click Install on the PlatformIO IDE extension
  5. Wait for installation to complete (this may take several minutes)
  6. Restart VS Code when prompted

3. Open the Glitchy Project

  1. In VS Code, go to File → Open Folder
  2. Navigate to glitchy/Code/Glitchy/
  3. Select the folder and click Open
  4. PlatformIO will automatically detect the project and download required dependencies

4. Wait for Dependencies

The first time you open the project, PlatformIO will:

  • Download the ESP32 platform tools
  • Install required libraries (AsyncTCP, ESPAsyncWebServer, ArduinoJson)
  • Configure the build environment

This may take 5-10 minutes depending on your internet connection. Watch the terminal output for progress.

5. Build the Firmware

  1. Click the checkmark icon (✓) in the PlatformIO toolbar at the bottom
    • Or use keyboard shortcut: Ctrl+Alt+B
    • Or open Command Palette (Ctrl+Shift+P) and type "PlatformIO: Build"
  2. Wait for the build to complete
  3. A successful build shows [SUCCESS] in the terminal

6. Upload to Device

  1. Connect your ESP32-S3 to your computer via USB
  2. Click the arrow icon (→) in the PlatformIO toolbar
    • Or use keyboard shortcut: Ctrl+Alt+U
    • Or open Command Palette and type "PlatformIO: Upload"
  3. Wait for upload to complete

Tip: If upload fails, you may need to hold the BOOT button on the ESP32-S3 while connecting, or press BOOT then RST.

Option B: PlatformIO Core (Command Line)

1. Install PlatformIO Core

Follow the official installation guide for your OS:

Quick install (Python required):

pip install platformio

2. Navigate to Project

cd path/to/glitchy/Code/Glitchy

3. Build

pio run

4. Upload

pio run --target upload

5. Monitor Serial Output

pio device monitor

Project Configuration

The Glitchy project uses the following configuration (platformio.ini):

[platformio]
default_envs = esp32-s3-devkitc-1

[env:esp32-s3-devkitc-1]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino
lib_deps =
    https://github.com/me-no-dev/AsyncTCP.git
    https://github.com/yubox-node-org/ESPAsyncWebServer
    bblanchon/ArduinoJson@^7.3.1
monitor_speed = 115200

Key Settings

Setting Value Description
platform espressif32 ESP32 platform package
board esp32-s3-devkitc-1 Target board
framework arduino Arduino framework
monitor_speed 115200 Serial monitor baud rate

Dependencies

Library Purpose
AsyncTCP Asynchronous TCP for ESP32
ESPAsyncWebServer Async HTTP/WebSocket server
ArduinoJson JSON parsing and serialization

Verification

After successful upload:

  1. Open Serial Monitor (click plug icon or pio device monitor)
  2. Press the RST button on the ESP32-S3
  3. You should see startup messages including WiFi AP information
  4. Connect to the Glitchy WiFi network (default: Glitchy)
  5. Open http://192.168.4.1 in your browser

Troubleshooting

Build Errors

"Library not found"

  • Run pio pkg install to refresh dependencies
  • Check internet connection

"Board not found"

  • Run pio pkg update -p espressif32

Upload Errors

"No serial port found"

  • Check USB cable connection
  • Install CP210x USB drivers from Silicon Labs
  • On Linux, add user to dialout group: sudo usermod -aG dialout $USER

"Upload failed, timeout"

  • Hold BOOT button while connecting USB
  • Press BOOT, then RST, then release BOOT
  • Try a different USB port

"Permission denied" (Linux/macOS)

sudo chmod 666 /dev/ttyUSB0  # or /dev/ttyACM0

Serial Monitor Issues

"Port is busy"

  • Close other applications using the serial port
  • Disconnect and reconnect USB

Migrating from Arduino IDE

If you previously used Arduino IDE:

  1. Your code will work without changes (same Arduino framework)
  2. Library locations are different (PlatformIO manages its own)
  3. Build outputs are in .pio/build/ instead of temp folders
  4. No need to manually install board packages or libraries

See Also

References:

Clone this wiki locally