EasyWiFiMDNS

EasyWiFiMDNS is a clean, minimal, and reusable Arduino library for ESP32 projects that encapsulates WiFi connection management using WiFiManager (by tzapu) and local host registration using ESPmDNS.

• Saved Credentials Connection: Automatically connects to the previously stored WiFi network on boot.
• Captive Portal Provisioning: Automatically starts an Access Point (AP) captive portal if connection fails or no credentials exist.
• Sanitized mDNS Hostname Registration: Registers the device on the local network (http://hostname.local) with input hostname sanitization (lowercased, spaces/underscores replaced with hyphens, symbols stripped, max 32 chars).
• Non-blocking Reconnect Monitoring: Checks connection status inside loop() and attempts non-blocking reconnects every 10 seconds if disconnected.
• WiFi Credential Reset: Built-in helper to clear saved settings, disconnect the radio, and safely reboot the ESP32.

1. Download or clone this repository:

   git clone https://github.com/mahdi-misk/EasyWiFiMDNS.git

2. Move the EasyWiFiMDNS folder into your Arduino libraries directory (e.g., Documents/Arduino/libraries/ on Windows or ~/Arduino/libraries/ on macOS/Linux).
3. Restart your Arduino IDE or PlatformIO.

• ESP32 Arduino Core (v2.0.0 or newer recommended)
• WiFiManager library by tzapu (installable directly via Arduino Library Manager)

#include <Arduino.h>
#include <EasyWiFiMDNS.h>

EasyWiFiMDNS wifi;

void setup() {
  Serial.begin(115200);

  // Configure portal parameters (optional, call before begin)
  wifi.setApPassword("setup123"); // Password for setup AP (min 8 chars)
  wifi.setPortalTimeout(180);     // Portal active duration in seconds (default: 180)
  wifi.setConnectTimeout(20);     // WiFi connection attempt timeout (default: 20)
  wifi.setDebug(true);            // Enable debug outputs (default: true)

  // Start WiFi connection & mDNS
  wifi.begin("myrobot");

  Serial.println("Device Ready");
  Serial.print("Open: ");
  Serial.println(wifi.url());
  Serial.print("IP: ");
  Serial.println(wifi.ip());
}

void loop() {
  // Call in loop to handle reconnection and mDNS status
  wifi.loop();

  // User project code here
}

If there are no saved WiFi credentials or if the ESP32 fails to connect to the saved network within the connect timeout (default 20 seconds):

1. The ESP32 opens a temporary Access Point.
2. The AP name is based on the hostname, suffixed with -setup (e.g., if hostname is myrobot, AP name is myrobot-setup).
3. The AP password defaults to setup123 (unless configured differently).
4. Connect to this AP from your phone or PC, open a browser, choose your WiFi SSID from the scan list, enter the password, and hit Save.
5. The credentials are saved permanently in ESP32 flash/NVS, and the device will restart and connect automatically.

Once WiFi is successfully connected:

1. The library starts mDNS with the sanitized hostname.
2. The device registers the HTTP service (http, tcp, port).
3. The device becomes reachable on your local network at http://<sanitized-hostname>.local (e.g., http://myrobot.local).

To clear saved credentials programmatically, call:

wifi.resetWiFi();

This method will clear all saved WiFiManager credentials, disconnect from the network, wait shortly, and restart the ESP32. Check the ResetWiFi.ino example for a hardware-based button reset implementation using the boot button (GPIO 0).

• No MDNS.update() on ESP32: On the ESP32 platform, the ESPmDNS responder runs completely in the background via a FreeRTOS task. It does not require or support MDNS.update(). Calling it will lead to compilation errors.
• AP Password Rule: The AP password must be at least 8 characters long. If a password shorter than 8 characters is supplied, it is automatically replaced with "setup123". If the password is empty or NULL, an open setup AP is created.

This library is prepared and structured for Arduino Library Manager submission.

This project is licensed under the MIT License - see the LICENSE file for details. Copyright (c) 2026 Mahdi Misk.