Skip to content

HowTo Update WebGUI

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

How To: Update Web GUI

This guide explains how to update Glitchy's web interface files stored on the SD card.

Prerequisites

  • SD card reader (built-in or USB adapter)
  • Latest web GUI files (from releases or build)
  • FAT32 formatted SD card

Quick Update

Step 1: Download Latest Release

  1. Go to Releases
  2. Download the web GUI archive (e.g., webgui-v2.0.0.zip)
  3. Extract the archive to a temporary folder

Step 2: Prepare SD Card

  1. Power off Glitchy
  2. Remove SD card from Glitchy
  3. Insert SD card into computer

Step 3: Replace Files

  1. Delete existing web files from SD card:

    • index.html
    • *.js files
    • *.css files
    • assets/ folder (if present)

  2. Copy new files from extracted archive to SD card root

Step 4: Verify Structure

Your SD card should now contain:

SD Card/
├── index.html
└── assets/
    ├── index-[hash].js
    ├── index-[hash].css
    └── [other asset files]

Note: Vite uses hashed filenames (e.g., index-HjK8x2.js) for cache busting. The exact filenames will vary with each build.

Step 5: Install and Verify

  1. Safely eject SD card from computer
  2. Insert SD card into Glitchy
  3. Power on Glitchy
  4. Connect to WiFi network
  5. Open browser to http://192.168.4.1
  6. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
  7. Verify the interface loads and functions correctly

Building from Source

If you want to build the web GUI yourself:

Prerequisites

  • Node.js 16+ and npm
  • Git

Build Steps

# Navigate to web GUI repository (separate from main glitchy repo)
cd glitchy-vue-app

# Install dependencies
npm install

# Build for production
npm run build

# Output files are in dist/ folder

Note: The web GUI source is in the glitchy-vue-app repository, which is separate from the main glitchy firmware repository.

Deploy Build

Copy contents of dist/ folder to SD card root. The Vite build produces:

dist/
├── index.html
├── favicon.ico (if present)
└── assets/
    ├── index-[hash].js
    ├── index-[hash].css
    └── [other chunks]

SD Card Requirements

Format

  • File System: FAT32 (format the entire card)
  • Cluster Size: Default (usually 4096 bytes)
  • Minimum Size: Any size works (web files are small)

Formatting

Windows:

  1. Right-click SD card in File Explorer
  2. Select "Format"
  3. Choose FAT32
  4. Click "Start"

macOS:

  1. Open Disk Utility
  2. Select SD card
  3. Click "Erase"
  4. Choose MS-DOS (FAT)

Linux:

sudo mkfs.vfat -F 32 /dev/sdX1

Version Compatibility

Web GUI and firmware should be from the same release. Mismatched versions may cause:

  • WebSocket connection failures
  • Missing features
  • JavaScript errors

Best practice: Always download firmware and web GUI from the same GitHub release to ensure compatibility.

See Reference: Version Compatibility

Troubleshooting

Web Interface Not Loading

"Connection refused" or blank page:

  1. Verify SD card is inserted properly
  2. Check file names are correct (case-sensitive)
  3. Try reformatting SD card as FAT32
  4. Verify index.html exists at root level

Old Version Still Showing

Browser cache issue:

  1. Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
  2. Clear browser cache completely
  3. Try incognito/private browsing mode
  4. Try different browser

WebSocket Connection Failed

Version mismatch:

  1. Ensure firmware and web GUI are from the same release
  2. Download both components from the same GitHub release
  3. Update both if versions don't match

Files Not Recognized

File system issue:

  1. Reformat SD card as FAT32
  2. Ensure no hidden files causing issues
  3. Try different SD card

See Also

Clone this wiki locally