How Do You Provision Wi-Fi Credentials on an Embedded IoT Device?

Detailed Explanation

Wi-Fi provisioning is one of the first user-facing interactions with an IoT product — and one of the most common sources of negative reviews if it is unreliable, slow, or confusing. A product that cannot easily join the user's network is perceived as broken, regardless of how well the rest of the firmware works. Choosing the right provisioning approach depends on the product's hardware (BLE radio availability), whether a companion mobile app exists, and the target user's technical sophistication.

Why Credentials Cannot Be Hardcoded

Hardcoding Wi-Fi credentials in firmware creates three problems:

1. The product only works on one network — it cannot be deployed to a different household or site without a firmware reflash
2. Credentials are recoverable from the firmware binary — strings are trivially extracted from flat binaries with strings or a hex editor
3. Factory-default or demo credentials shipped to end users — a common cause of data breaches where all units share a known password

Provisioning at first setup solves all three problems: each unit learns its own network credentials, credentials are not in the firmware image, and the user explicitly consents to network access.

SoftAP Provisioning

The device boots into access point mode, creating a Wi-Fi network (typically named something like Device-Setup-XXXX). The user connects their phone to this temporary network, opens a captive portal in a browser (typically http://192.168.4.1), and submits their home Wi-Fi SSID and password via an HTML form. The device stores the credentials, disconnects the SoftAP, and connects to the home network. The phone reconnects to its normal network automatically.

Advantages:

• Works without a mobile app — any device with a browser is sufficient
• No additional radio hardware required beyond Wi-Fi
• Familiar to users who have set up home routers

Disadvantages:

• The user must manually switch their phone's Wi-Fi network (to the device's AP), submit credentials, and switch back — three steps that confuse non-technical users
• No confirmation of success visible to the user (phone switched away before device confirmed connection)
• Captive portal detection on modern iOS and Android sometimes opens a special captive portal browser rather than the user's default browser

ESP32 SoftAP provisioning with Wi-Fi Manager (ESP-IDF):

wifi_prov_mgr_config_t config = {
    .scheme = wifi_prov_scheme_softap,
    .scheme_event_handler = WIFI_PROV_EVENT_HANDLER_NONE,
};
wifi_prov_mgr_init(config);

bool provisioned = false;
wifi_prov_mgr_is_provisioned(&provisioned);

if (!provisioned) {
    /* Start SoftAP provisioning — service_name is the AP SSID */
    wifi_prov_mgr_start_provisioning(WIFI_PROV_SECURITY_1, pop, service_name, NULL);
} else {
    wifi_prov_mgr_deinit();
    /* Connect with stored credentials */
}

WIFI_PROV_SECURITY_1 enables SRP-based challenge-response authentication of the provisioning endpoint — use this to prevent unauthorised devices from submitting credentials to the AP.

BLE-Assisted Provisioning

The device advertises over BLE while in the unprovisioned state. The companion mobile app (iOS or Android) scans for the device, connects, and transfers the Wi-Fi SSID and password over a GATT service. The device acknowledges receipt, attempts the Wi-Fi connection, and sends the result (success or failure with reason code) back over BLE before the connection closes.

Advantages:

• Seamless user experience: the user never switches Wi-Fi networks — provisioning happens through the app while the phone stays on its normal Wi-Fi
• Real-time success confirmation: the app receives confirmation that the device joined the target network
• Works on iOS without the need for the user to navigate Wi-Fi settings

Disadvantages:

• Requires a companion mobile app with BLE support
• ESP32 and other dual-radio SoCs must manage BLE and Wi-Fi simultaneously during the provisioning transition — this requires handling the co-existence window during the final Wi-Fi join
• Slightly more complex firmware implementation

ESP32 BLE provisioning (ESP-IDF Wi-Fi Provisioning Manager):

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);

/* The manager handles GATT service definition and BLE advertising */
wifi_prov_mgr_start_provisioning(
    WIFI_PROV_SECURITY_1,
    pop,              /* Proof of possession — device-specific string */
    service_name,     /* BLE device name shown in mobile app scan      */
    NULL
);

The pop (proof of possession) is a device-specific token that the mobile app must supply to authenticate the provisioning session. Derive it from a device serial number, hardware ID, or a random value printed on a QR code label — this prevents a rogue app from provisioning the device to an attacker's network.

nRF Wi-Fi provisioning (Zephyr NCS): Nordic's nRF9160 and nRF7002 support a Zephyr-based Wi-Fi provisioning library that implements a similar BLE-assisted flow using a standardised GATT service, compatible with the nRF Connect for Mobile app.

SmartConfig / ESP-TOUCH

The device enters promiscuous mode on the Wi-Fi radio and monitors all 802.11 frames on each channel. A companion app on the phone — which is already connected to the target Wi-Fi network — sends UDP broadcast packets to a multicast address, encoding the SSID and password in the sequence of packet lengths. The unprovisioned device decodes the length pattern and extracts the credentials.

/* ESP32 SmartConfig — simplified */
esp_smartconfig_start(SC_TYPE_ESPTOUCH);

/* SC_EVENT_GOT_SSID_PSWD event delivers the credentials: */
void sc_event_handler(void* arg, esp_event_base_t event_base,
                      int32_t event_id, void* event_data)
{
    if (event_id == SC_EVENT_GOT_SSID_PSWD) {
        smartconfig_event_got_ssid_pswd_t *evt = event_data;
        /* evt->ssid and evt->password contain the decoded credentials */
        esp_wifi_set_config(WIFI_IF_STA, &wifi_config);
        esp_wifi_connect();
    }
}

SmartConfig requires both the phone and target network to be on 2.4 GHz. It does not work reliably on 5 GHz-only networks or in environments with dense Wi-Fi traffic. Use it as a backup method alongside SoftAP or BLE-assisted provisioning, not as the sole option.

Matter Commissioning

Matter is the application-layer standard for smart home devices, jointly developed by Apple, Google, Amazon, and others through the Connectivity Standards Alliance (CSA). The Matter commissioning flow uses BLE for initial device discovery and credential transfer, regardless of the device's final transport (Wi-Fi, Thread, or Ethernet).

Matter commissioning sequence (simplified):

1. Unprovisioned device advertises over BLE with a Matter-specific UUID
2. The Matter commissioner (phone, smart home hub, or voice assistant device) scans, connects, and performs PASE (Password Authenticated Session Establishment) using a device-specific PIN printed on the product
3. The commissioner transfers the Wi-Fi credentials (or Thread dataset) over the authenticated BLE session
4. The device joins the target network; the commissioner establishes a CASE (Certificate Authenticated Session Establishment) session over the final transport
5. The device is now part of the Matter fabric and can receive commands from any authorised Matter controller

Matter is the appropriate choice for products intended for the Apple HomeKit, Google Home, Amazon Alexa, or Samsung SmartThings ecosystems. It adds implementation complexity — the Matter SDK is substantial — but provides cross-platform interoperability without per-platform app development.

Credential Storage

Regardless of provisioning method, credentials must be stored in non-volatile memory:

• ESP32 (ESP-IDF): the Wi-Fi stack stores credentials automatically in the NVS partition after esp_wifi_set_config(). Enable NVS encryption (NVS_ENCRYPTION=y and a device-specific key burned to eFuse) for products with security requirements.
• nRF7002 / nRF9160 (Zephyr NCS): credentials are stored via the Settings subsystem. Enable encrypted flash (CONFIG_TRUSTED_EXECUTION_SECURE=y or FOTA-based key provisioning) for secure credential storage.
• Factory reset: always provide a mechanism to erase stored credentials (long button press, specific firmware reset command) that clears both the provisioning state and the NVS/Settings partition. A factory reset that only clears application state but leaves credentials creates a privacy problem when the device is sold or repurposed.

Design Considerations

• Provide a QR code or NFC tag for Matter products: Matter's PASE authentication requires a device-specific PIN or QR code. Print the QR code on the product label or packaging — users scan it with their phone's camera to begin commissioning. A QR code that is missing, damaged, or covers the PIN entry entirely blocks the provisioning flow.
• Timeout the provisioning mode: do not leave the device in SoftAP or BLE advertising mode indefinitely. After a provisioning timeout (typically 3–5 minutes), the device should return to normal operation or reset — an unprovisioned device in SoftAP mode consumes significantly more power than a connected device in normal operation.
• Derive the proof-of-possession token per device: a shared proof-of-possession string (same for all units) provides no security benefit. Generate per-device tokens during manufacturing from the device serial number or a factory-injected random seed, and print them on the device or its packaging.
• Test provisioning on the iOS and Android versions you actually ship to: iOS handles captive portal detection differently from Android, and the BLE connection behaviour during Wi-Fi joining differs across Android OEM variants. Build the provisioning test matrix into the firmware qualification plan.
• Handle re-provisioning gracefully: a device already provisioned to network A needs a path to switch to network B (user moves house, network password changes). A single factory-reset button held for 5 seconds is the simplest approach; alternatively, implement a re-provisioning command accessible through the normal connected state.
• Zeus Design develops companion iOS and Android apps with BLE-assisted and SoftAP provisioning flows, including QR code scanning, real-time provisioning status, and factory reset management for IoT products.

Common Mistakes

• No re-provisioning path: designing a product with no way to change the stored Wi-Fi credentials after initial setup forces users to factory-reset the device and re-configure everything when their router or password changes. A dedicated re-provisioning flow or a factory reset accessible without disassembly is a minimum requirement.
• Fixed proof-of-possession token across all units: a proof-of-possession string identical on every unit provides no protection against rogue provisioning from a malicious app. Use per-device tokens derived from serial numbers or factory-injected secrets.
• Starting provisioning mode after every boot until confirmed: the device should remember whether it has been successfully provisioned. A device that enters SoftAP mode on every boot until a "provisioned" flag is set will confuse users who power-cycle the device unexpectedly.
• Not verifying the Wi-Fi connection succeeds before closing BLE: in BLE-assisted provisioning, the BLE connection should remain open until the device confirms it joined the target network (or failed with an error code). Closing BLE as soon as credentials are received, before testing the connection, leaves the user with no feedback if credentials were wrong.
• Storing the SSID and password in plain-text firmware flash without NVS encryption: the Wi-Fi password is recoverable with a JTAG debug probe if stored in unencrypted NVS. For consumer products, enable NVS encryption tied to device-unique keys to prevent credential harvesting from returned or stolen units.
• Ignoring provisioning in the power budget: during SoftAP provisioning, the ESP32 runs both a Wi-Fi AP and a web server simultaneously. This uses significantly more power than normal connected operation. If the product is battery-powered, time-limit the provisioning mode and warn the user via an LED if battery is low.