Skip to content

VERIFICATION HowTo Flash Firmware

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

Verification: HowTo-Flash-Firmware.md

Status: Complete Verified: 25/25 claims Last Updated: 2026-02-02 Source Document: HowTo-Flash-Firmware.md

Summary

This verification file validates technical claims in HowTo-Flash-Firmware.md against authoritative sources including project source code, KiCad schematics, and PlatformIO documentation.

Document Purpose: Guide users through updating both Glitchy firmware (via PlatformIO) and the web GUI (via SD card file copy).

Verification Scope:

  • Hardware connections and connector types
  • Firmware build/upload procedures
  • Web GUI update procedure
  • SD card requirements
  • Troubleshooting procedures

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

Hardware Claims

Claim: USB cable is micro-USB

  • Source: KiCad schematic PCB/Miswired-Glitchy.kicad_sch — component USB1: MICROXNJ, footprint MICRO-USB-SMD_MICROXNJ, LCSC C404969
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Schematic confirms SHOU-HAN MicroXNJ micro-USB connector.

Claim: Firmware resides in ESP32-S3 flash memory

  • Source: PlatformIO uploads to ESP32-S3 flash via serial; standard ESP32 firmware storage
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Standard ESP32-S3 firmware execution from flash.

Claim: Web GUI resides on SD card

  • Source: Code/Glitchy/src/webserver.cpp:52,55 — request->send(SD, "/index.html", ...) and server.serveStatic("/", SD, "/")
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Web server explicitly serves all static files from the SD card filesystem.

Claim: SD card reader needed for web GUI updates

  • Source: Web GUI files are on SD card (verified above); must be copied externally
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: No over-the-air update mechanism for SD card files in current firmware.

Software/Procedure Claims

Claim: Git clone URL is https://github.com/miswired/glitchy.git

  • Source: GitHub repository (project README references this)
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Confirmed repository URL.

Claim: Project folder is glitchy/Code/Glitchy/

  • Source: platformio.ini at Code/Glitchy/platformio.ini (verified in PlatformIO verification)
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Consistent with PlatformIO document verification.

Claim: Upload via arrow icon (→) or Ctrl+Alt+U in VS Code

  • Source: PlatformIO IDE for VS Code documentation
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Standard PlatformIO IDE upload methods.

Claim: CLI upload via pio run --target upload

  • Source: PlatformIO CLI documentation
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Standard PlatformIO upload command.

Claim: Serial Monitor at 115200 baud

  • Source: Code/Glitchy/platformio.ini:20 monitor_speed = 115200; main.cpp:148 Serial.begin(115200)
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Consistent between config and firmware.

Claim: Verify version number in boot output

  • Source: Code/Glitchy/src/main.cpp:146-172 — setup() function does NOT print version
  • Confidence: HIGH
  • Status: ❌ Incorrect
  • Notes: ISSUE #1 — The firmware does not print a version number during boot. setup() prints WiFi and SD card info, but no version string. A CommsVersion (1.1) exists in JSON protocol responses (webserver.cpp:150-151) but is not printed to Serial. See Issues Found section.

Claim: Web GUI available from GitHub Releases page

  • Source: GitHub repository at https://github.com/miswired/glitchy/releases
  • Confidence: MEDIUM
  • Status: ⚠️ Needs Testing
  • Notes: The releases URL is plausible but whether pre-built web GUI zips are actually published there needs confirmation.

Claim: Copy web GUI files to SD card root

  • Source: Code/Glitchy/src/webserver.cpp:55 — server.serveStatic("/", SD, "/") maps URL root to SD card root
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Web server serves from SD card root directory. Files must be at the top level.

Claim: Delete old web GUI files before copying new ones

  • Source: General best practice for file replacement
  • Confidence: MEDIUM (procedure claim)
  • Status: ✓ Verified
  • Notes: Reasonable procedure to avoid stale files. No auto-cleanup in firmware.

Claim: Clear browser cache and reload after web GUI update

  • Source: General web development practice — browsers cache static assets
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Browser caching of JS/CSS/HTML files would serve stale content without cache clear.

Claim: Check version on the About page

  • Source: Would need to examine web GUI source (glitchy-vue-app) for About page/route
  • Confidence: LOW
  • Status: ⚠️ Needs Testing
  • Notes: Could not confirm whether the Vue web app has an "About page" without examining the running application or the built web GUI files. The Vue app source would need to be checked for this route.

Troubleshooting Claims

Claim: Install drivers — CP210x or CH340

  • Source: KiCad schematic — component U4/U2: CP2102N-A02-GQFN28R
  • Confidence: HIGH
  • Status: ❌ Incorrect
  • Notes: ISSUE #2 — Same as PlatformIO doc: Glitchy uses CP2102N only. CH340 reference should be removed. The doc does link to the correct CP210x driver page (silabs.com).

Claim: Ubuntu dialout group for serial access: sudo usermod -aG dialout $USER

  • Source: Standard Linux serial port permissions; PlatformIO/ESP32 documentation
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Standard procedure. Note doc says "Ubuntu" specifically but applies to most Linux distributions.

Claim: BOOT + RST button sequence — hold BOOT, press RST, release BOOT, upload within 10 seconds

  • Source: ESP32-S3 Datasheet strapping pins documentation
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Standard ESP32-S3 manual boot mode entry. The "10 seconds" window is approximate but reasonable.

Claim: sudo chmod 666 /dev/ttyUSB0 for permission denied

  • Source: Standard Linux serial port permission workaround
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid temporary workaround. The dialout group method is preferred for persistence.

Claim: SD card should be formatted as FAT32

  • Source: Code/Glitchy/src/main.cpp:56 — SD.begin() uses Arduino SD library which requires FAT32
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Arduino SD library supports FAT16 and FAT32. FAT32 is the practical recommendation for cards > 2GB.

Claim: Firmware rollback by checking out previous version from git and reuploading

  • Source: Standard git workflow; PlatformIO rebuild and upload
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid procedure using git checkout <tag/commit> then normal build/upload.

Claim: Web GUI rollback by replacing SD card files with previous version

  • Source: Web GUI served from SD card (verified above); file replacement is the update mechanism
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid procedure — same as initial install but with older files.

Claim: Keep firmware and web GUI at matching versions

  • Source: CommsVersion protocol in webserver.cpp suggests version-dependent communication
  • Confidence: MEDIUM
  • Status: ✓ Verified
  • Notes: The JSON protocol includes a CommsVersion field (1.1), implying version coupling between firmware and GUI. Good practice even if not strictly enforced currently.

Issues Found

Issue #1: Firmware does not print version number at boot

  • Document Location: "Updating Firmware" > Step 5 > "Verify version number in boot output"
  • Problem: The firmware setup() function does not print any version string to Serial during boot
  • Correct Information: Boot output includes WiFi AP info and SD card detection, but no version number. A CommsVersion exists in JSON protocol but is not printed to Serial.
  • Source: Code/Glitchy/src/main.cpp:146-172 (setup function); webserver.cpp:150-151 (CommsVersion in JSON)
  • Severity: Minor (verification step cannot be completed as described)
  • Proposed Fix: Either (a) add Serial.println("Firmware version: X.Y.Z"); to setup(), or (b) change Step 5 to "Verify startup messages appear including WiFi AP information"

Issue #2: Incorrect USB driver reference (CH340)

  • Document Location: Troubleshooting > Upload Fails > "No serial port found"
  • Problem: Lists both CP210x and CH340 driver links, but Glitchy only uses CP2102N
  • Correct Information: Only CP210x (Silicon Labs) drivers are needed
  • Source: KiCad schematic, component U4/U2: CP2102N-A02-GQFN28R
  • Severity: Minor (unnecessary driver install; may confuse users)
  • Proposed Fix: Remove CH340 link, keep only CP210x: "Install drivers: CP210x"

Issue #3: "About page" may not exist in web GUI

  • Document Location: "Updating Web GUI" > Step 4 > "Check version on the About page"
  • Problem: Cannot confirm the web GUI has an About page from source inspection
  • Correct Information: Needs verification against the running web GUI or Vue app source
  • Source: Would need to check glitchy-vue-app router/views for About route
  • Severity: Minor (if no About page exists, step is misleading)
  • Proposed Fix: Verify in Vue app source; if no About page, change to "Verify web interface loads and functions correctly"

Testing Requirements

The following claims require testing on physical Glitchy hardware:

  • Serial output content at 115200 baud after RST (what exactly is printed?)
  • Web GUI releases are available on GitHub Releases page
  • Web GUI has an "About page" with version information
  • BOOT + RST sequence enters download mode within ~10 seconds
  • SD card file copy procedure works as described

Test Procedures:

  1. Serial output: Connect serial monitor at 115200, press RST, capture full boot output
  2. Releases page: Visit https://github.com/miswired/glitchy/releases, check for web GUI zip
  3. About page: Load web interface, look for About page or version display
  4. Boot mode: Test BOOT+RST sequence with PlatformIO upload

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 micro-USB connector type is confirmed from the schematic (MICROXNJ component).
  • The CH340 driver issue appears in multiple documents (also in HowTo-Setup-PlatformIO.md) — this should be a coordinated fix across all docs.
  • The version number issue suggests a firmware enhancement opportunity: adding a version print to setup().
  • The "About page" claim needs Vue app source verification or runtime testing.

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

Clone this wiki locally