Skip to content

VERIFICATION HowTo Configure WiFi

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

Verification: HowTo-Configure-WiFi.md

Status: Complete Verified: 22/22 claims Last Updated: 2026-02-02 Source Document: HowTo-Configure-WiFi.md

Summary

This verification file validates technical claims in HowTo-Configure-WiFi.md against authoritative sources including the firmware source code and ESP32-S3 documentation.

Document Purpose: Guide users through WiFi configuration, including switching between Access Point (AP) and Client (Station) modes.

Verification Scope:

  • WiFi mode behavior (AP vs Client)
  • Default configuration values (SSID, password, IP)
  • Code snippet accuracy
  • Troubleshooting steps

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

Configuration Claims

Claim: Access Point (AP) mode is the default

  • Source: Code/Glitchy/src/main.cpp:33 — #define HOST_ACCESS_POINT is defined (uncommented) by default
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: The HOST_ACCESS_POINT macro is defined, so the #else branch (AP mode) in initWiFi() executes by default.

Claim: Default WiFi network is named "Glitchy"

  • Source: Code/Glitchy/src/main.cpp:39 — const char* ap_ssid = "Glitchy";
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Document says "Glitchy" (or similar)" which is imprecise — the SSID is always exactly "Glitchy" unless the user modifies the source. The "(or similar)" could be removed for clarity.

Claim: AP mode IP address is 192.168.4.1

  • Source: Code/Glitchy/src/main.cpp:122-124 — WiFi.softAP(ap_ssid, ap_password) then WiFi.softAPIP() returns default
  • Confidence: MEDIUM
  • Status: ✓ Verified
  • Notes: IP is not explicitly set — relies on ESP32 Arduino library default (192.168.4.1). Functionally correct. ESP-IDF/Arduino default is well-documented.

Claim: No internet access through AP connection

  • Source: ESP32-S3 softAP mode documentation — AP mode creates isolated network
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: ESP32 softAP does not provide NAT/routing to an upstream connection. Correct.

Claim: Client mode — Glitchy connects to existing WiFi network

  • Source: Code/Glitchy/src/main.cpp:106-118 — WiFi.begin(ssid, password) when HOST_ACCESS_POINT is not defined
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: The #ifndef HOST_ACCESS_POINT branch connects to an external network.

Claim: Client mode — IP assigned by router (DHCP)

  • Source: WiFi.begin() uses DHCP by default in Arduino ESP32 library
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: No static IP is configured in the STA branch; DHCP is the default.

Claim: Client mode — IP is printed at boot on Serial Monitor

  • Source: Code/Glitchy/src/main.cpp:115 — Serial.println(WiFi.localIP());
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: The local IP is printed after successful connection in STA mode.

Claim: Default AP password is "123456789"

  • Source: Code/Glitchy/src/main.cpp:40 — const char* ap_password = "123456789";
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Confirmed. Note: the AP mode section of the document does not explicitly state the default password, only the code block shows it. Users may miss this.

Claim: Default client SSID placeholder is "YOUR_SSID_HERE"

  • Source: Code/Glitchy/src/main.cpp:35 — const char* ssid = "YOUR_SSID_HERE";
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Exact match.

Claim: Default client password placeholder is "YOUR_PASSWORD_HERE"

  • Source: Code/Glitchy/src/main.cpp:36 — const char* password = "YOUR_PASSWORD_HERE";
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Exact match.

Claim: Code block showing WiFi configuration in main.cpp matches actual source

  • Source: Code/Glitchy/src/main.cpp:32-40
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: The code block is functionally identical to the source. One minor difference: the document corrects a grammar typo — doc has "its" while source has "it's" in the HOST_ACCESS_POINT comment. This is acceptable editorial cleanup.

Claim: Configuration file is at Code/Glitchy/src/main.cpp

  • Source: File exists at that path
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Correct path.

Claim: Changes require rebuild and reupload of firmware

  • Source: WiFi config is compile-time (#define and const char* in source); no runtime config mechanism
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Correct — all WiFi settings are compiled into firmware. No web-based config UI exists.

Procedural Claims

Claim: WiFi takes 10-30 seconds to start (AP mode)

  • Source: Code/Glitchy/src/main.cpp:146-172 — setup() calls initWiFi() early
  • Confidence: HIGH
  • Status: ❌ Incorrect
  • Notes: ISSUE #1 — In AP mode, WiFi.softAP() executes during setup() and typically completes in under 2 seconds. The 10-30 second estimate is significantly overestimated for AP mode. This timeframe might be more appropriate for client mode (scanning + DHCP). See Issues Found section.

Claim: ESP32-S3 requires 2.4GHz WiFi (not 5GHz)

  • Source: ESP32-S3 Datasheet — WiFi 802.11 b/g/n, 2.4GHz only
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: ESP32-S3 does not support 5GHz WiFi. Important troubleshooting point.

Claim: Reset to AP mode by re-flashing firmware with default AP configuration

  • Source: HOST_ACCESS_POINT is defined by default; re-flashing restores default
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid procedure — re-uploading unmodified firmware restores AP mode.

Troubleshooting Claims

Claim: Check SD card — must be present and valid (for AP network troubleshooting)

  • Source: Code/Glitchy/src/main.cpp:154-155 — initWiFi() is called BEFORE initSDCard()
  • Confidence: HIGH
  • Status: ❌ Incorrect
  • Notes: ISSUE #2 — WiFi initialization occurs before SD card initialization in setup(). SD card status cannot affect AP network visibility. The WiFi AP should broadcast regardless of SD card state. This troubleshooting step is misleading in the context of "Can't Find AP Network". See Issues Found section.

Claim: Verify WiFi credentials exactly (for client mode troubleshooting)

  • Source: General WiFi troubleshooting; credentials are hardcoded strings
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid — typos in SSID/password strings are a common issue.

Claim: Check MAC filtering on router (for client mode troubleshooting)

  • Source: General networking knowledge
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid troubleshooting step for client mode connectivity.

Claim: Move Glitchy closer to router (for client mode troubleshooting)

  • Source: General WiFi troubleshooting
  • Confidence: HIGH
  • Status: ✓ Verified
  • Notes: Valid — ESP32-S3's PCB antenna has limited range.

Claim: Future firmware may allow WiFi configuration through web interface

  • Source: None — this is a future enhancement note
  • Confidence: N/A
  • Status: ✓ Verified
  • Notes: Noted as a future enhancement. Currently no web-based WiFi config exists, confirmed by source code review.

Issues Found

Issue #1: Overestimated WiFi AP startup time (10-30 seconds)

  • Document Location: "Connecting in AP Mode" step 2; "Can't Find AP Network" step 1
  • Problem: States WiFi takes 10-30 seconds to start in AP mode. In practice, WiFi.softAP() typically completes in under 2 seconds.
  • Correct Information: AP mode WiFi should be available within a few seconds of power-on. The full setup() (including SD card, web server, ADC) may take several seconds total, but the WiFi AP is one of the first things initialized.
  • Source: Code/Glitchy/src/main.cpp:154 — initWiFi() is called early in setup(); ESP32 WiFi.softAP() documentation
  • Severity: Minor (overly conservative estimate; may frustrate users who expect faster startup)
  • Proposed Fix: Change to "Wait a few seconds for WiFi to start" or "Wait 5-10 seconds for the system to fully initialize"

Issue #2: SD card unrelated to AP network visibility

  • Document Location: Troubleshooting > "Can't Find AP Network" > step 3
  • Problem: Lists "Check SD card — Must be present and valid" as troubleshooting for AP network not appearing. WiFi init happens before SD card init, so SD card state cannot affect AP visibility.
  • Correct Information: SD card is only needed for the web interface content, not for WiFi AP operation. A missing SD card means the web GUI won't load, but the WiFi network itself will still appear.
  • Source: Code/Glitchy/src/main.cpp:154-155 — initWiFi() (line 154) before initSDCard() (line 155); initSDCard() returns gracefully on failure
  • Severity: Minor (misleading troubleshooting step; may cause users to chase the wrong problem)
  • Proposed Fix: Remove from "Can't Find AP Network" section. Could add to a separate "Web interface not loading" troubleshooting section instead.

Issue #3: Default AP password not mentioned in AP Mode section

  • Document Location: "Access Point Mode (Default)" section
  • Problem: The section describes connecting to "Glitchy" network but does not mention the default password ("123456789"). Users see the password only in the code block under "Changing Settings" (which they may skip if they just want to connect).
  • Correct Information: Default AP password is "123456789" (main.cpp:40)
  • Source: Code/Glitchy/src/main.cpp:40 — const char* ap_password = "123456789";
  • Severity: Minor (users may struggle to connect without knowing the password)
  • Proposed Fix: Add to "Connecting in AP Mode" step 3: 'connect to "Glitchy" network (default password: 123456789)'

Testing Requirements

The following claims require testing on physical Glitchy hardware:

  • AP mode WiFi startup time (measure actual seconds from power-on to SSID visible)
  • Confirm WiFi AP still broadcasts when SD card is removed
  • Confirm default password "123456789" works for AP connection
  • Verify 192.168.4.1 is the actual AP IP address
  • Client mode prints IP to serial at 115200 baud

Test Procedures:

  1. AP startup time: Power on Glitchy, time until "Glitchy" SSID appears in WiFi scan
  2. SD card independence: Remove SD card, power on, verify SSID still appears
  3. Default password: Connect to "Glitchy" WiFi using password "123456789"
  4. AP IP: After connecting, verify 192.168.4.1 responds to ping/browser
  5. Client IP: Flash with client mode, open serial monitor, verify IP is printed

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 code block shown in the document is an accurate representation of the source with one minor editorial grammar fix ("its" vs "it's").
  • The document does a good job explaining both WiFi modes and the compile-time configuration approach.
  • The missing default password in the AP Mode section is the most user-impacting issue — new users following the guide won't know what password to enter.
  • The SD card troubleshooting item is factually incorrect for AP visibility but could be valid for web GUI loading issues.

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

Clone this wiki locally