ESP32 WiFi Bootstrap: Simple Wi-Fi Provisioning with HomeKit Integration

Blog, HomeKit /

Configuring Wi-Fi on an ESP32 can be challenging—especially if you want the device to work across different networks without re-flashing the firmware each time. Fortunately, the ESP32 WiFi Bootstrap project offers an elegant solution. In this blog post, we’ll explore how this project works, how to integrate it into your own ESP32 projects, and how the HomeKit LED example demonstrates the full provisioning + integration flow.

What is ESP32 WiFi Bootstrap?

ESP32 WiFi Bootstrap is a lightweight, high-performance Wi-Fi provisioning component for the ESP32. It offers a user-friendly captive portal experience with fast configuration, persistent storage, and full compatibility with ESP-IDF 5.4 and newer.

ESP32 WIFI

Key Features:

  • Captive Portal with CNA Detection: Compatible with iOS/macOS for seamless onboarding.
  • DNS Redirect: Automatically redirects browsers to the configuration page.
  • Wi-Fi Scan: Lists nearby networks and indicates whether they are secured.
  • Persistent Storage: Stores credentials in NVS so the device reconnects automatically after reboot.
  • SoftAP Fallback: If no known network is found, the device falls back to SoftAP mode with a configurable SSID.
  • Lightweight Embedded UI: Uses Jinja2 and chunked HTML output for efficiency.

How Does It Work?

Upon boot, the device checks for previously saved Wi-Fi credentials. If found, it connects and starts the main app. If not, it switches to SoftAP mode and opens a captive portal where the user can select a network and enter credentials. Once configured, the ESP32 saves the settings to NVS and reboots in station mode.

The diagram below summarizes how the wifi_config API works:

  1. The program starts and checks for stored credentials.
  2. If credentials exist, it connects and runs the main app.
  3. If not, it starts SoftAP and opens a captive portal with the defined SSID.
  4. The user connects, selects a Wi-Fi network, and enters a password.
  5. Credentials are stored in NVS.
  6. The device restarts and connects to the selected network.

To start SoftAP mode with a custom SSID and optional password, use:

wifi_config_init("SSID_NAME", "PASSWORD", on_wifi_ready);

If you want an open network (no password), simply use NULL:

wifi_config_init(DEVICE_NAME, NULL, on_wifi_ready);

To reset credentials and restart the captive portal: This clears the saved settings and triggers a reboot.

Example Project: HomeKit LED

The homekit-led example included in the esp32-wifi-bootstrap repository demonstrates how to seamlessly combine Wi-Fi provisioning with a HomeKit accessory. It uses a basic ESP32 setup with one LED and one push button, showing how to create a fully functional HomeKit lightbulb in minutes.

GPIO Configuration

Two GPIO’s are defined—one for the LED, one for the button: The LED is configured as output, and the button as input with a pull-up resistor.

Wi-Fi Reset with Button Press

When the button is pressed, the ESP32 resets its stored Wi-Fi credentials:

if (!state) {
    wifi_config_reset(); // Includes esp_restart()
}

Metadata

#define DEVICE_NAME "LED"
#define DEVICE_MANUFACTURER "StudioPieters®"
#define DEVICE_SERIAL "NLDA4SQN1466"
#define DEVICE_MODEL "SD466NL/A"
#define FW_VERSION "0.0.1"

Application Startup Logic

The app_main() function defines the boot logic, including starting Wi-Fi provisioning:

wifi_config_init(DEVICE_NAME, NULL, on_wifi_ready);

In this case, the SoftAP SSID will be “LED” and it will be open (no password) because the second argument is NULL. Once Wi-Fi is configured, the on_wifi_ready() callback starts the HomeKit server.

Summary

ESP32 WiFi Bootstrap offers a robust and user-friendly way to configure Wi-Fi on ESP32 devices. Combined with the HomeKit LED example, it shows how easy it is to pair Wi-Fi provisioning with HomeKit functionality. It’s an ideal starting point for developers looking to make their projects easier to set up—and ready for Apple’s HomeKit ecosystem.

Explore or download the full project here: github.com/AchimPieters/esp32-wifi-bootstrap

Scroll to Top