A production-ready WiFi provisioning and recovery library for ESP32 devices. Designed for real IoT products with robust error handling, multiple reset mechanisms, and configurable UX features.

• ✅ Non-blocking operation - Fully asynchronous state machine
• ✅ Captive portal - Responsive web interface for configuration
• ✅ Persistent storage - Credentials stored in NVS (Non-Volatile Storage)
• ✅ Automatic retry - Configurable retry logic with exponential backoff option
• ✅ WiFi network scanning - List available networks in configuration UI
• ✅ State callbacks - Hooks for application integration

• 🔄 Hardware button - Long-press physical button to reset
• 🔄 HTTP endpoint - Simple or authenticated remote reset
• 🔄 Double-reboot detection - Emergency recovery mechanism
• 🔄 Auto-wipe on max retries - Optional credential clearing

• 💡 LED status indicator - Visual feedback for device state
• 🌐 mDNS support - Access device via http://device-name.local
• 📱 Mobile-friendly UI - Responsive design works on all devices
• ⚡ Fast configuration - Network scanning and one-click selection

• 🔐 Password hashing - SHA-256 hashing for reset passwords
• 🔐 Authenticated reset - Require password for remote operations
• 🔐 Configurable AP security - Open or password-protected configuration AP
• 🔐 Credential isolation - Separate storage for WiFi and reset passwords

1. Download this repository as ZIP
2. In Arduino IDE: Sketch → Include Library → Add .ZIP Library
3. Select the downloaded ZIP file

Add to platformio.ini:

lib_deps =
    https://github.com/ferdiu/ESP32ProvisionToolkit.git

#include <ESP32ProvisionToolkit.h>

ESP32ProvisionToolkit provisioner;

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

  provisioner
    .setAPName("MyDevice")  // Custom AP name
    .setLed(2)              // Enable LED on GPIO 2
    .onConnected([]() {
      Serial.println("Connected!");
    })
    .begin();
}

void loop() {
  provisioner.loop();

  // Your application code here
  if (provisioner.isConnected()) {
    // Do something
  }
}

The library uses a fluent API for easy configuration:

provisioner
  .setAPName("MyESP32")
  .setAPPassword("config123")
  .setMaxRetries(10)
  .setRetryDelay(3000)
  .enableHardwareReset(GPIO_NUM_0, 5000)
  .enableAuthenticatedHttpReset(true)
  .setLed(GPIO_NUM_2)
  .enableMDNS("my-device")
  .setLogLevel(LOG_INFO)
  .onConnected(onConnectedCallback)
  .begin();

Example:

// BOOT button (GPIO 0), hold for 5 seconds, active low
provisioner.enableHardwareReset(0, 5000, true);

HTTP Reset Usage:

Simple (unauthenticated):

curl -X POST http://device-ip/reset

Authenticated:

curl -X POST http://device-ip/reset -d "password=YOUR_RESET_PASSWORD"

NOTE: If any time you reset the software you change this password it can still be considered secure to send the password in plain-text.

LED Patterns:

• Fast blink (100ms on/off): Provisioning mode
• Slow blink (100ms on, 900ms off): Connecting
• Solid on: Connected
• Off: Idle/Error

Log Levels:

• LOG_NONE - No output
• LOG_ERROR - Errors only
• LOG_INFO - Normal operation info
• LOG_DEBUG - Detailed debugging

Example:

provisioner.onConnected([]() {
  Serial.println("Connected to WiFi!");
  Serial.println(WiFi.localIP());
});

provisioner.onFailed([](uint8_t retryCount) {
  Serial.printf("Connection failed, retry %d\n", retryCount);
});

provisioner.onAPMode([](const char* ssid, const char* ip) {
  Serial.printf("AP Mode: %s at %s\n", ssid, ip);
});

Example:

// Programmatically set credentials
provisioner.setCredentials("MyNetwork", "password123", true);

// Clear and reboot
provisioner.clearCredentials(true);

// Trigger reset
provisioner.reset();

┌─────────────┐
│    INIT     │
└──────┬──────┘
       │
       v
┌─────────────┐      No Credentials      ┌──────────────┐
│ LOAD_CONFIG │─────────────────────────>│ PROVISIONING │
└──────┬──────┘                          └───────┬──────┘
       │                                         │
       │ Has Credentials                         │
       v                                         │
┌─────────────┐      Success         ┌───────────v─────────┐
│ CONNECTING  │─────────────────────>│ PROVISIONING_ACTIVE │
└──────┬──────┘                      └─────────────────────┘
       │
       │ Failure
       v
┌─────────────┐      Max Retries     ┌──────────────┐
│ RETRY_WAIT  │─────────────────────>│  WIPE & AP   │
└──────┬──────┘                      └──────────────┘
       │
       │ Retry
       v
┌─────────────┐
│  CONNECTED  │◄─── Main operation state
└─────────────┘

Namespace: wifiprov

1. Always use authenticated reset in untrusted environments:

   provisioner.enableAuthenticatedHttpReset(true);

2. Secure the configuration AP with a strong password:

   provisioner.setAPPassword("Strong!Pass123");

3. Use hardware reset for field deployment:

   provisioner.enableHardwareReset(BUTTON_PIN, 10000); // 10 sec

4. Disable debug logging in production:

   provisioner.setLogLevel(LOG_ERROR);

• Reset passwords are hashed using SHA-256 before storage
• Original passwords are never stored in plaintext
• Hash verification is constant-time to prevent timing attacks

• The library does not implement WPA3 or certificate pinning
• Use WPA2-PSK or better for production networks
• Consider implementing additional application-level encryption
• For highly sensitive applications, use VPN or TLS for all communications

Causes:

• Credentials are stored from previous session
• Double-reboot window not met

Solutions:

// Check if credentials exist
if (!provisioner.isProvisioning()) {
  // Manually trigger reset
  provisioner.clearCredentials(true);
}

// Or use hardware button
// Hold BOOT button for configured duration

Causes:

• Wrong password
• Network out of range
• Router MAC filtering

Solutions:

• Check router logs
• Verify SSID and password
• Increase max retries:

  provisioner.setMaxRetries(20);

• Enable auto-wipe to re-enter provisioning:

  provisioner.setAutoWipeOnMaxRetries(true);

Causes:

• Mobile device doesn't support captive portal detection
• DNS server not starting properly

Solutions:

• Manually navigate to AP IP address (usually 192.168.4.1)
• Check Serial output for DNS server status
• Ensure DNS server is enabled in your network settings

Causes:

• Reset feature not enabled
• Using authenticated endpoint without password

Solutions:

// Enable simple reset
provisioner.enableHttpReset(true);

// OR enable authenticated reset
provisioner.enableAuthenticatedHttpReset(true);
// Then set password during configuration

Causes:

• LED not enabled
• Wrong GPIO pin
• Active-low setting incorrect

Solutions:

// For most ESP32 boards (active-low built-in LED)
provisioner.setLed(2, true); // GPIO 2, active low

// For external LED (active-high)
provisioner.setLed(LED_PIN, false);

The library uses the wifiprov namespace by default. To avoid conflicts:

// Currently not configurable, but you can modify the source:
// In ESP32ProvisionToolkit.cpp:
// #define NVS_NAMESPACE "myapp_wifi"

#include <ESP32ProvisionToolkit.h>
#include <PubSubClient.h>

ESP32ProvisionToolkit provisioner;
WiFiClient wifiClient;
PubSubClient mqtt(wifiClient);

void setup() {
  provisioner
    .onConnected([]() {
      // Connect to MQTT when WiFi connects
      mqtt.setServer("mqtt.example.com", 1883);
      mqtt.connect("esp32-client");
    })
    .begin();
}

void loop() {
  provisioner.loop();

  if (provisioner.isConnected()) {
    mqtt.loop();
  }
}

#include <ESP32ProvisionToolkit.h>
#include <ArduinoOTA.h>

void setup() {
  provisioner
    .onConnected([]() {
      ArduinoOTA.begin();
    })
    .begin();
}

void loop() {
  provisioner.loop();

  if (provisioner.isConnected()) {
    ArduinoOTA.handle();
  }
}

void loop() {
  provisioner.loop();

  if (provisioner.isConnected()) {
    // Do work
    sendSensorData();

    // Sleep until next transmission
    esp_sleep_enable_timer_wakeup(60 * 1000000); // 60 seconds
    esp_light_sleep_start();
  }
}

The library includes four complete examples:

1. Basic - Minimal setup for getting started
2. SecureReset - All security features enabled
3. Headless - Production IoT device configuration
4. CustomRoutes - The basic example with additional user-defined routes

See /examples directory for complete code.

See the header file ESP32ProvisionToolkit.h for complete API documentation with detailed comments.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests if applicable
4. Submit a pull request

MIT License - See LICENSE file for details

• Issues: GitHub Issues

• Documentation update

• Initial release
• Complete WiFi provisioning system
• Multiple reset mechanisms
• Production-ready features
• Comprehensive documentation

Developed with ❤️ for the ESP32 community

• Espressif for the ESP32 platform
• Arduino community for the excellent ecosystem