ESP32 Arduino WiFi Password Legal Characters: Debugging Auth Failures

The Short Answer: ESP32 Arduino WiFi Password Legal Characters

If you are hardcoding credentials or passing them via a web portal, the ESP32 Arduino WiFi password legal characters are strictly defined by the underlying IEEE 802.11i (WPA2) and 802.11-2020 (WPA3) standards, filtered through the ESP-IDF C stack.

For WPA2-Personal (PSK), legal passwords must be either:

• 8 to 63 printable ASCII characters (Hex 0x20 to 0x7E). This includes standard letters, numbers, and symbols like !@#$%^&*().
• Exactly 64 hexadecimal characters (0-9, A-F, a-f) representing a raw Pre-Shared Key (PSK).

For WPA3-SAE, the standard allows UTF-8 encoding. However, the ESP32 Arduino core processes passwords as raw byte arrays. If you copy-paste a password from a smartphone or modern OS, you risk injecting "smart quotes" (curly apostrophes like ’ instead of ') or emojis. WPA2 hashing uses PBKDF2-HMAC-SHA1 on the raw bytes. If your router hashes the standard ASCII apostrophe (1 byte) and your ESP32 hashes the UTF-8 curly apostrophe (3 bytes: E2 80 99), the Pairwise Master Key (PMK) will mismatch, resulting in a silent authentication failure.

Parts List & Pin Mapping for the Debugging Rig

To properly intercept and diagnose WiFi handshake failures, we need a board with a reliable RF trace and mapped status indicators. This guide targets the ESP32-DevKitC V4 featuring the ESP32-WROOM-32E module (which includes improved Bluetooth/WiFi coexistence over the older 32D).

The Decision Tree: Diagnosing Password & Auth Failures

When the ESP32 fails to connect, the Arduino core v3.x exposes the underlying ESP-IDF wifi_err_reason_t enum via the WiFi event hook. Use this decision path to isolate the exact point of failure.

The Concrete Pick: If you are designing a consumer IoT product or a robust home automation node, default to enforcing 8-63 standard ASCII characters on your provisioning input. Strip all non-ASCII bytes before passing the string to WiFi.begin(). Do not rely on WPA3 UTF-8 support unless you are explicitly building for a WPA3-certified enterprise environment, as legacy router firmware handles SAE UTF-8 hashing inconsistently.

Complete Compilable Debug Code (ESP32 DevKit V1)

This sketch targets the ESP32-DevKitC V4. It utilizes the modern WiFi.onEvent() hook to catch exact disconnect reasons, maps the onboard LED for visual feedback, and uses the BOOT button (GPIO 0) to force a reconnect test without hitting the reset button.

#include <WiFi.h>

// --- PIN DEFINITIONS ---
#define LED_PIN 2    // Onboard Blue LED (Active HIGH on DevKit V4)
#define BTN_PIN 0    // Onboard BOOT Button (Active LOW)

// --- WIFI CREDENTIALS ---
// Use standard ASCII. Avoid smart quotes or hidden control characters.
const char* ssid = "YourNetworkSSID";
const char* password = "YourLegalP@ssw0rd!"; 

// --- STATE VARIABLES ---
bool isConnected = false;
unsigned long lastBlink = 0;

// --- WIFI EVENT HANDLER ---
void WiFiEvent(WiFiEvent_t event, WiFiEventInfo_t info) {
    switch (event) {
        case ARDUINO_EVENT_WIFI_STA_CONNECTED:
            Serial.println("[WiFi] Connected to AP. Waiting for IP...");
            break;
            
        case ARDUINO_EVENT_WIFI_STA_GOT_IP:
            Serial.print("[WiFi] IP Address: ");
            Serial.println(WiFi.localIP());
            isConnected = true;
            digitalWrite(LED_PIN, HIGH); // Solid ON
            break;
            
        case ARDUINO_EVENT_WIFI_STA_DISCONNECTED:
            isConnected = false;
            digitalWrite(LED_PIN, LOW); // OFF
            
            // Extract exact ESP-IDF disconnect reason
            uint8_t reason = info.wifi_sta_disconnected.reason;
            Serial.printf("[WiFi] Disconnected. Reason Code: %d\n", reason);
            
            if (reason == 15) {
                Serial.println("[ERROR] 4WAY_HANDSHAKE_TIMEOUT: Check password ASCII encoding!");
            } else if (reason == 2) {
                Serial.println("[ERROR] AUTH_FAIL: Check MAC filtering or WPA2/WPA3 mismatch.");
            } else if (reason == 201) {
                Serial.println("[ERROR] NO_AP_FOUND: Check SSID spelling and 2.4GHz band.");
            }
            
            // Auto-reconnect logic
            Serial.println("[WiFi] Attempting reconnect in 2 seconds...");
            delay(2000);
            WiFi.begin(ssid, password);
            break;
            
        default:
            break;
    }
}

void setup() {
    Serial.begin(115200);
    delay(1000); // Allow serial monitor to attach
    
    pinMode(LED_PIN, OUTPUT);
    pinMode(BTN_PIN, INPUT_PULLUP);
    
    Serial.println("\n--- ESP32 WiFi Legal Character Debugger ---");
    
    // Validate password length locally before attempting connection
    int pwdLen = strlen(password);
    if (pwdLen < 8 || pwdLen > 63) {
        Serial.printf("[FATAL] Password length is %d. Must be 8-63 ASCII chars.\n", pwdLen);
        while(1) { // Halt execution
            digitalWrite(LED_PIN, !digitalRead(LED_PIN));
            delay(100); // Fast blink indicates fatal config error
        }
    }
    
    // Register WiFi Event Hook
    WiFi.onEvent(WiFiEvent);
    
    // Disable power saving to prevent DHCP timeouts on some routers
    WiFi.setSleep(false);
    
    Serial.printf("[WiFi] Connecting to SSID: %s\n", ssid);
    WiFi.begin(ssid, password);
}

void loop() {
    // Visual feedback: Slow blink while connecting, solid when connected
    if (!isConnected && (millis() - lastBlink > 500)) {
        digitalWrite(LED_PIN, !digitalRead(LED_PIN));
        lastBlink = millis();
    }
    
    // Manual disconnect trigger via BOOT button for testing
    if (digitalRead(BTN_PIN) == LOW) {
        delay(50); // Debounce
        if (digitalRead(BTN_PIN) == LOW) {
            Serial.println("[BTN] Disconnect triggered manually.");
            WiFi.disconnect(true);
            while(digitalRead(BTN_PIN) == LOW); // Wait for release
        }
    }
}

First Three Things to Check When Connection Fails

If you have flashed the code above and are still staring at a WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT in your serial monitor, execute these three numbered troubleshooting steps:

1. Hex-Dump the Password Variable: Copy-pasting from a word processor or iOS Notes app often injects invisible Unicode formatting characters. Add this temporary loop to your setup() to print the exact hex bytes of your password string:

   for(int i=0; i<strlen(password); i++) {
       Serial.printf("%02X ", password[i]);
   }

   If you see anything outside the 20 to 7E range, your password contains illegal non-ASCII bytes.
2. Verify Router WPA2/WPA3 Transition Mode: Modern mesh routers (like Eero or Asus ZenWiFi) default to "WPA2/WPA3 Transition Mode". The ESP32 Arduino core v3.x supports WPA3-SAE, but the handshake negotiation can fail if the router's firmware has a buggy transition implementation. Log into your router and force WPA2-Personal Only temporarily to isolate the variable.
3. Check for C++ String Truncation: If you are reading the password from a JSON config file on LittleFS or SPIFFS, ensure the parser isn't appending a carriage return (\r or 0x0D) to the end of the string. A 10-character password with a hidden \r becomes 11 characters, and the router will reject it. Use String.trim() before converting to a C-string via .c_str().

Extending and Simplifying the Build

Hardcoding WiFi credentials is acceptable for a one-off bench test, but it violates the core principle of scalable IoT deployment. Here is how to evolve this debugging rig into a production-ready node.

To Simplify (The Provisioning Path):
Integrate the WiFiManager library by AlexT. Instead of hardcoding the SSID and password, WiFiManager spins up an Access Point (e.g., ESP32_Setup) and a captive portal web server. You connect your phone to the ESP32's AP, type the WiFi credentials into a clean HTML form, and the library handles the ASCII validation and connection. This entirely eliminates the "smart quote" copy-paste error, as mobile browsers submit standard UTF-8/ASCII form data.

To Extend (The Secure IoT Path):
Once your WiFi connection is stable and you have verified the legal character boundaries, the next bottleneck is usually DHCP latency and MQTT TLS handshakes. Extend the build by:

• Assigning a Static IP via WiFi.config() to skip the DHCP discovery phase, saving ~1.5 seconds on boot.
• Implementing MQTT over TLS using the WiFiClientSecure class. Note that TLS requires accurate time for certificate validation; you must add an NTP sync step via configTime() immediately after the ARDUINO_EVENT_WIFI_STA_GOT_IP event fires.

For deeper architectural details on the ESP32's underlying WiFi state machine and memory allocation for the TCP/IP stack, refer to the official Espressif ESP-IDF WiFi API Guide and the Arduino WiFi Library Reference. Understanding the boundary between the Arduino C++ wrapper and the ESP-IDF C core is the hallmark of a proficient embedded engineer.