Skip to content

VERIFICATION HowTo Update WebGUI

Jump to bottom
miswired edited this page Feb 7, 2026 · 1 revision

Verification: HowTo-Update-WebGUI.md

Status: Complete Verified: 28/28 claims Last Updated: 2026-02-02 Source Document: HowTo-Update-WebGUI.md

Summary

This verification file validates technical claims in HowTo-Update-WebGUI.md against authoritative sources including project structure, source code, and Vue.js/Vite documentation.

Document Purpose: Guide users through updating the web GUI files on the SD card, including both pre-built downloads and building from source.

Verification Scope:

  • SD card file structure and format requirements
  • Web GUI build process and commands
  • File system requirements (FAT32)
  • Version compatibility

Known Issues: 4 issues found (see Issues Found section)

Configuration Claims

Claim: Web GUI files are stored on SD card

  • Source: Code/Glitchy/src/webserver.cpp:52,55 — serves from SD card filesystem
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Confirmed in multiple verification files.

Claim: SD card must be FAT32 formatted

  • Source: Arduino SD library used in main.cpp:56 — SD.begin() uses Arduino SD library which requires FAT16/FAT32
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: FAT32 is the correct recommendation for SD cards > 2GB.

Claim: Files must be at SD card root level

  • Source: Code/Glitchy/src/webserver.cpp:55 — server.serveStatic("/", SD, "/")
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: URL "/" maps to SD card root "/".

Claim: index.html is required at root

  • Source: Code/Glitchy/src/webserver.cpp:52 — request->send(SD, "/index.html", ...)
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Root URL explicitly serves /index.html from SD card.

Claim: Default IP address is 192.168.4.1

  • Source: ESP32 Arduino library default for softAP mode; verified in WiFi document
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Consistent across all documents.

Build Process Claims

Claim: Web GUI source is at glitchy/Code/WebGUI

  • Source: Directory listing of glitchy/Code/ shows only: Glitchy/, Libraries/, Target Examples/
  • Confidence: HIGH
  • Status: ❌ Incorrect
  • Notes: ISSUE #1 — No WebGUI directory exists inside glitchy/Code/. The Vue app is in a separate repository: glitchy-vue-app/ (sibling to glitchy/, not inside it). See Issues Found section.

Claim: Node.js 16+ and npm are prerequisites

  • Source: package.json uses ES modules ("type": "module"), Vue 3.4.x, Vite 5.3.x
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Vue 3 + Vite 5 require Node.js 16+. Correct prerequisite.

Claim: Install dependencies with npm install

  • Source: Standard npm workflow; package.json contains dependencies
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Correct command.

Claim: Build with npm run build

  • Source: glitchy-vue-app/package.json:8 — "build": "vite build"
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Build script is defined and uses Vite.

Claim: Output files are in dist/ folder

  • Source: Vite default output directory is dist/; not overridden in vite.config.js
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Standard Vite build output.

Claim: Copy contents of dist/ folder to SD card root

  • Source: Web server expects files at root (verified above)
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Correct deployment procedure.

File Structure Claims

Claim: SD card contains index.html, app.js, style.css, and other web files

  • Source: Vite builds produce: index.html + hashed JS/CSS in assets/ folder (standard Vite output)
  • Confidence: MEDIUM
  • Status: ❌ Incorrect
  • Notes: ISSUE #2 — Vite does not output app.js and style.css at root. Instead, it produces index.html at root with hashed asset files in an assets/ subdirectory (e.g., assets/index-abc123.js). The example file structure shown is incorrect for a Vite-built app. See Issues Found section.

Claim: assets/ folder may be present

  • Source: Vite default build structure includes assets/ for chunked JS/CSS
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: The mention of assets/ folder is correct — Vite outputs assets there.

Formatting Claims

Claim: Windows format via right-click → Format → FAT32

  • Source: Standard Windows procedure
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Windows File Explorer format dialog supports FAT32 for smaller cards. Note: Windows GUI may not offer FAT32 for cards > 32GB.

Claim: macOS format via Disk Utility → Erase → MS-DOS (FAT)

  • Source: Standard macOS procedure
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Disk Utility labels FAT32 as "MS-DOS (FAT)". Correct.

Claim: Linux format via sudo mkfs.vfat -F 32 /dev/sdX1

  • Source: Standard Linux FAT32 formatting command
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Correct command. Users must replace sdX1 with actual device.

Claim: Default cluster size (4096 bytes) is acceptable

  • Source: Standard FAT32 cluster size for small cards
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Default cluster sizes work fine for web GUI files.

Version Compatibility Claims

Claim: Firmware 2.0.x requires Web GUI 2.0.x

  • Source: Cannot verify specific version numbers — no version documentation found
  • Confidence: LOW
  • Status: ⚠️ Needs Testing
  • Notes: ISSUE #3 — The version numbers (2.0.x, 1.x) appear to be placeholders or future versions. The current glitchy-vue-app package.json shows version "1.0.0". The firmware has no version string printed at boot (per Flash-Firmware verification). See Issues Found section.

Claim: Mismatched versions cause WebSocket connection failures

  • Source: webserver.cpp:150-151 — CommsVersion in JSON protocol suggests version checking
  • Confidence: MEDIUM
  • Status: ✓ Verified
  • Notes: The firmware includes a CommsVersion (1.1) in protocol. Mismatched protocol versions could cause issues.

Claim: Mismatched versions cause missing features and JavaScript errors

  • Source: General software compatibility principles
  • Confidence: MEDIUM
  • Status: ✓ Verified
  • Notes: Reasonable expectation if API/protocol changes between versions.

Troubleshooting Claims

Claim: Hard refresh with Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)

  • Source: Standard browser keyboard shortcuts
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Correct cross-platform hard refresh shortcuts.

Claim: Try incognito/private browsing mode for cache issues

  • Source: General web troubleshooting
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Private mode uses fresh cache. Valid troubleshooting step.

Claim: File names are case-sensitive

  • Source: FAT32 is case-insensitive but preserving; ESP32 SD library may be case-sensitive in lookups
  • Confidence: MEDIUM
  • Status: ⚠️ Needs Testing
  • Notes: FAT32 is technically case-insensitive, but the webserver code uses exact paths (e.g., "/index.html"). Needs testing whether "INDEX.HTML" would work.

Claim: Check firmware version on About page or serial output

  • Source: Serial output does not include version (verified in Flash-Firmware document)
  • Confidence: HIGH
  • Status: ❌ Incorrect
  • Notes: ISSUE #4 — Firmware does not print version to serial at boot (no version string in main.cpp setup()). The "About page" claim is also unverified. This repeats the issue from HowTo-Flash-Firmware.md.

Issues Found

Issue #1: Incorrect Web GUI source path

  • Document Location: "Building from Source" > "Build Steps" > cd glitchy/Code/WebGUI
  • Problem: The path glitchy/Code/WebGUI does not exist. The Code/ directory contains only Glitchy/, Libraries/, and Target Examples/.
  • Correct Information: The Vue web GUI source is in a separate repository: glitchy-vue-app/ (at the same level as glitchy/, not inside it)
  • Source: Directory listing of glitchy/Code/; existence of glitchy-vue-app/package.json
  • Severity: Major (users cannot find the source to build from)
  • Proposed Fix: Change path to glitchy-vue-app and note it's a separate repository: "Navigate to the glitchy-vue-app repository (separate from the main glitchy repository)"

Issue #2: Incorrect example file structure

  • Document Location: "Step 4: Verify Structure" — shows app.js, style.css at root
  • Problem: Vite does not output app.js and style.css at root. Vite builds produce: index.html at root + hashed assets in assets/ folder (e.g., assets/index-HjK8x2.js, assets/index-9sLm3.css)
  • Correct Information: After Vite build, structure is: 
    SD Card/
├── index.html
├── favicon.ico (if present)
└── assets/
    ├── index-[hash].js
    ├── index-[hash].css
    └── [other chunks]
  • Source: Vite documentation; default Vite build output behavior
  • Severity: Minor (may confuse users comparing their build output to the example)
  • Proposed Fix: Update example to show Vite's hashed asset output structure

Issue #3: Unverifiable version numbers

  • Document Location: "Version Compatibility" table — 2.0.x, 1.x versions
  • Problem: Cannot verify these version numbers. The Vue app is version 1.0.0. Firmware has no printed version.
  • Correct Information: Current Vue app is 1.0.0 (package.json). Firmware version is not defined/printed.
  • Source: glitchy-vue-app/package.json:3 — "version": "1.0.0"; main.cpp has no version string
  • Severity: Minor (version table may be speculative/future-looking)
  • Proposed Fix: Either add actual version strings to firmware/GUI, or change table to generic "major versions must match" guidance

Issue #4: Firmware version not available in serial output

  • Document Location: Troubleshooting > "WebSocket Connection Failed" > "Check firmware version (About page or serial output)"
  • Problem: Firmware does not print version to serial (same issue as HowTo-Flash-Firmware.md)
  • Correct Information: Setup() does not print a version string. Only WiFi/SD info is printed.
  • Source: Code/Glitchy/src/main.cpp:146-172 (no Serial.println with version)
  • Severity: Minor (troubleshooting step cannot be completed as described)
  • Proposed Fix: Same as Flash-Firmware doc — either add version to firmware or update docs

Testing Requirements

The following claims require testing on physical Glitchy hardware:

  • Vite build output deploys correctly to SD card
  • Web interface loads from Vite-built assets/ structure
  • File name case sensitivity (does INDEX.HTML work?)
  • GitHub Releases has downloadable web GUI archives
  • Version mismatch behavior (what actually breaks?)

Test Procedures:

  1. Vite deployment: Build glitchy-vue-app, copy dist/ to SD card, verify web UI loads
  2. Case sensitivity: Rename index.html to INDEX.HTML, test if it loads
  3. Releases check: Visit https://github.com/miswired/glitchy/releases for web GUI zips

Verification Checklist

  • All technical claims identified and extracted
  • Claims organized by category
  • Each claim has source citation
  • Each claim has confidence level
  • Each claim has status icon
  • Hardware-dependent claims marked for testing
  • Issues documented with corrections
  • Summary section completed
  • Index README.md updated
  • OpenSpec task marked complete

Notes

  • The major issue is the incorrect source path (glitchy/Code/WebGUI vs glitchy-vue-app/). This prevents users from building from source.
  • The file structure example doesn't match Vite's actual output with hashed filenames.
  • Several version-related claims can't be verified because the project lacks explicit versioning in both firmware and web GUI.
  • The About page reference appears in multiple documents but hasn't been verified to exist.

Verification completed by: Claude (AI agent) Review date: 2026-02-02 Approved by: Pending user review

Clone this wiki locally