ESP32 BLE Provisioning: Setting Up Wi-Fi on IoT Devices via Phone App

What "unified provisioning" actually means

Before unified provisioning landed in ESP-IDF, every team rolled their own. You'd write firmware that started a SoftAP, served a captive portal, accepted credentials over HTTP, then connected to the user's network. Or you'd write firmware that exposed a BLE GATT service, accepted credentials over a custom characteristic, then connected. Both approaches worked, both had subtle bugs, and every team was solving the same problem twice.

Espressif's unified provisioning is a thin abstraction layer over both. You write your firmware to use wifi_prov_mgr, declare which transport you want (BLE or SoftAP), and the manager handles the rest — advertising, credential exchange, security handshake, Wi-Fi connection attempt, and reporting the result back to the client app. The same client-side protocol works whether the transport is BLE or SoftAP underneath, so your mobile app code doesn't change when you switch transports.

The headline benefit isn't the abstraction — it's the protocol. Espressif also publishes a documented protocol (protobuf-encoded messages over the chosen transport) so any client app that speaks the protocol can provision any ESP32 device, regardless of who wrote the firmware. That's why our app and Espressif's own reference apps can both talk to a device that uses unified provisioning — they speak the same protocol.

In practice, here's what a firmware initialization looks like at the entry point:

wifi_prov_mgr_config_t config = {
    .scheme = wifi_prov_scheme_ble,
    .scheme_event_handler = WIFI_PROV_SCHEME_BLE_EVENT_HANDLER_FREE_BTDM
};

wifi_prov_mgr_init(config);
wifi_prov_mgr_start_provisioning(
    WIFI_PROV_SECURITY_1,
    "abcd1234",          // proof-of-possession PIN
    "DM-Device-1234",    // BLE device name
    NULL                 // BLE service UUID (NULL = default)
);

Four lines. The provisioning manager handles the rest — BLE advertising, GATT service registration, the security handshake, decrypting incoming credentials, attempting the Wi-Fi connection, and stopping the BLE stack once the device is online. The _FREE_BTDM flag tells the manager to release the Bluetooth Controller's memory after provisioning ends — important on a device that won't need BLE again, because it frees up around 30KB of heap.

What the security modes actually protect against

ESP-IDF's wifi_prov_mgr ships with three security modes. The docs name them and define them, but they don't always explain what each one protects against, which is what you need to know to pick the right one.

Security 0 is no security. Credentials are sent in cleartext over the chosen transport. The only legitimate use case is internal development on a controlled bench. If you ship Security 0, anyone within BLE range can passively sniff the customer's Wi-Fi password during provisioning. Don't ship it.

Security 1 uses a proof-of-possession (PoP) PIN plus a Curve25519 ECDH key exchange and AES-CTR encryption. The PoP is a short string (often printed on the device label, or shown on a sticker inside the box) that the client app has to provide alongside the credentials. Without the right PoP, the device rejects the session. This protects against two real attacks: a passive eavesdropper who sniffs the BLE traffic gets encrypted bytes that they can't decrypt, and an attacker within BLE range who tries to provision the device with their own credentials (to take over the device) is blocked unless they also have the PoP.

For most consumer IoT products, Security 1 is the right call. The PoP printed on the device label is the standard pattern.

Security 2 uses SRP6a (Secure Remote Password) instead of a static PoP. Instead of the device knowing a fixed PoP and matching it, the device and client perform a zero-knowledge password proof — meaning even if the device's flash is dumped, the password can't be extracted. Worth it for high-value or regulated products (medical devices, anything carrying credentials beyond Wi-Fi); overkill for a smart light.

Declaring security mode is one line:

wifi_prov_mgr_start_provisioning(
    WIFI_PROV_SECURITY_1,    // or _0 for dev, _2 for high-security
    "PROOF_TOKEN",
    service_name,
    service_key
);

The parts the documentation doesn't mention

Five things will bite you during real deployments. Worth knowing before you ship.

1. 2.4GHz vs 5GHz networks. The base ESP32 only supports 2.4GHz Wi-Fi. Modern home routers often default to 5GHz for the main SSID and put 2.4GHz on a separate SSID with a "-2.4" suffix — or worse, present them as a single SSID with band steering, where the router picks which band to advertise. The user sees their network in the list, selects it, types the password, and the device fails to connect with no clear explanation. Handle this in your client app: when displaying scan results, if the device returned an empty list or only 2.4GHz networks while the phone clearly sees 5GHz networks nearby, surface this honestly to the user. "Your device only supports 2.4GHz Wi-Fi. If you can't see your network here, you may need to enable a separate 2.4GHz network on your router."

2. Captive portals. Hotels, airports, coffee shops, and many corporate networks use captive portals — the device joins the SSID successfully but can't actually reach the internet until someone clicks "accept" on a web page. ESP32 provisioning will report a successful Wi-Fi connection even though the device can't reach your cloud. Worth probing your cloud endpoint during provisioning (before reporting success) and surfacing the captive portal case explicitly.

3. WPA3-only networks. Some newer routers default to WPA3-only mode, which the base ESP32 doesn't support. The provisioning will fail with an authentication error that's indistinguishable from a wrong password. If you're seeing high failure rates on what looks like correct credentials, this is often why.

4. Bonding state. If a user provisions the same device twice (e.g., during testing), iOS and Android will sometimes remember the previous BLE bond and refuse to re-pair. The honest fix is to make sure your firmware clears bonding state after a factory reset, and to instruct users to "forget" the device in their phone's Bluetooth settings if they hit this. Annoying but real.

5. Heap fragmentation. The provisioning manager allocates a non-trivial amount of heap during the session. If your firmware is already heap-constrained (large web server, lots of cloud SDKs loaded), you can hit allocation failures mid-handshake. Free what you can before calling wifi_prov_mgr_start_provisioning(), and use the _FREE_BTDM flag to release BT memory after provisioning completes.

When you're ready for the rest of it

Provisioning is the start of a device's life. After it, you have OTA updates (every shipped device eventually needs a firmware patch — we wrote about the ESP32 OTA approach we use), telemetry to a cloud backend, device-side power management, and field debugging. All of that has to be designed together — a provisioning flow that hands off cleanly to an OTA system that reports cleanly into a cloud dashboard.

That's the part where most one-person teams hit the wall. If you've built BLE provisioning before, you know the difference between a working demo and a production deployment isn't more code — it's the dozens of edge cases like the five above, multiplied across every subsystem.

We're DigitalMonk. We build ESP32 IoT products end-to-end — firmware, custom PCBs, BLE/Wi-Fi stacks, OTA, mobile, cloud. If you need a BLE mobile app built alongside your firmware, or you're past the provisioning stage and looking at the rest of the system, our ESP32 team is a reasonable place to start a conversation.

If you're not — keep building. The unified provisioning manager is good code, the app is free, and you're closer to shipping than you might think.