Skip to content

HowTo Flash Firmware

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

How To: Flash Firmware

This guide explains how to update Glitchy's firmware and web GUI files.

Prerequisites

  • Computer with PlatformIO installed (setup guide)
  • USB cable (micro-USB)
  • SD card reader (for web GUI updates)

Two Components to Update

Glitchy has two separate components that may need updating:

Component Location Update Method
Firmware ESP32-S3 flash PlatformIO upload
Web GUI SD card File copy

Important: Keep both components at matching versions. See Version Compatibility.

Updating Firmware

Step 1: Get Latest Firmware

Option A: Clone Repository

git clone https://github.com/miswired/glitchy.git
cd glitchy/Code/Glitchy

Option B: Download Release

  1. Go to Releases
  2. Download source code zip
  3. Extract to your computer

Step 2: Open Project in PlatformIO

Option A: VS Code

  1. Open VS Code
  2. File → Open Folder
  3. Select glitchy/Code/Glitchy/
  4. Wait for PlatformIO to initialize

Option B: Your Own Editor You can use your own editor, but you will need to build using the command line option.

Step 3: Connect Device

  1. Connect Glitchy via USB
  2. The device should be recognized as a serial port

Step 4: Build and Upload

Using VS Code:

  1. Click the arrow (→) in PlatformIO toolbar
  2. Or: Ctrl+Alt+U

Using Command Line:

cd glitchy/Code/Glitchy
pio run --target upload

Step 5: Verify

  1. Open Serial Monitor (115200 baud)
  2. Press RST button
  3. Verify startup messages appear (WiFi AP info, SD card detection)
  4. Connect to WiFi and confirm web interface loads

Updating Web GUI

Step 1: Get Latest Web GUI

  1. Go to Releases
  2. Download the web GUI release zip
  3. Extract the files

Step 2: Prepare SD Card

  1. Remove SD card from Glitchy
  2. Insert into computer's card reader
  3. Backup any existing files you want to keep

Step 3: Copy Files

  1. Delete old web GUI files from SD card
  2. Copy contents of zip to card

Step 4: Verify and Install

  1. Safely eject SD card
  2. Insert into Glitchy
  3. Power on/reset Glitchy
  4. Clear browser cache and reload interface
  5. Check version on the About page

Troubleshooting

Upload Fails

"No serial port found"

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

"Timeout waiting for download"

  1. Hold BOOT button on ESP32-S3
  2. Press and release RST button
  3. Release BOOT button
  4. Upload within 10 seconds

"Permission denied" Add yourself to the appropriate group, or change device permissions

# Linux/macOS
sudo chmod 666 /dev/ttyUSB0

Web GUI Not Loading

  • Verify files copied to SD card root (including assets/ folder)
  • Check that index.html exists at root level
  • Try reformatting SD card as FAT32
  • Clear browser cache completely

Version Mismatch Errors

  • Update both firmware AND web GUI together
  • Download matching versions from the same release
  • See compatibility guide

Rollback Procedure

If an update causes problems:

Firmware Rollback

  1. Checkout previous version from git
  2. Or download previous release
  3. Build and upload as normal

Web GUI Rollback

  1. Download previous web GUI version
  2. Replace files on SD card

Verification Checklist

After updating, verify:

  • Device powers on normally
  • WiFi network appears
  • Web interface loads
  • Version numbers correct

See Also

Clone this wiki locally