Join Wi-Fi

Wi-Fi Provisioning

How a production unit receives its SSID. Required to ship.

Join Wi-Fi First-time Wi-Fi setupPhone connects in ESP32 Wi-Fi parts

Official path: examples/provisioning/wifi_prov_mgr

01 Overview

Official provisioning manager that can deliver Wi-Fi credentials to the device over BLE or SoftAP.

Solves the out-of-box experience: users can provision without a PC or serial cable, just a phone.

Ideal for consumer, commercial, and industrial devices like smart home gadgets, sensors, and gateways.

Not for lab prototypes with hardcoded credentials; skip provisioning in that case.

Supports multiple transports, allowing flexibility to choose BLE or SoftAP, and can be extended.

MCU: ESP32 series with BLE support (e.g., ESP32, ESP32-S3); ESP32-S2 lacks BLE, so only SoftAP works.
Power: 3.3V supply, mind peak current, add decoupling capacitors.
Button: Add a GPIO button to trigger provisioning or reset credentials.
LED: Add a status LED to indicate provisioning state (e.g., fast blink = waiting).
Antenna: Keep antenna area clear of metal for good Wi-Fi/BLE performance.
Connector: If using external antenna, use IPEX connector with impedance matching.
Reset: Ensure reliable reset circuit on EN pin for factory reset capability.

1. Initialize NVS to store provisioning data.

2. Start Wi-Fi and BLE (if using BLE transport) or SoftAP.

3. Call esp_wifi_prov_mgr_start_provisioning(), selecting transport and security scheme.

4. Phone app sends SSID/password via BLE GATT or SoftAP HTTP.

5. On success, prov manager saves credentials to NVS and stops provisioning service.

6. After reboot, device reads NVS and auto-connects to Wi-Fi.

7. If connection fails or re-provisioning is needed, trigger via button or command.

8. Handle timeouts and errors, provide user feedback (e.g., LED patterns).

No provisioning, no shippable Wi-Fi product.
Security: Enable secure provisioning (e.g., SRP) in production to prevent credential leakage.
NVS corruption: Handle NVS corruption gracefully; provide re-provisioning mechanism.
BLE coexistence: If device uses BLE for other purposes, allocate resources carefully to avoid conflicts.
Custom work: App protocol, reset logic, share with GATT.
Testing: Cover success, failure, timeout, and re-provisioning scenarios.

中文

连上 Wi-Fi

量产设备第一次如何把 SSID 交给芯片。出货必做。

连上 Wi-Fi 第一次配网被手机连接 ESP32 Wi-Fi parts

官方路径: examples/provisioning/wifi_prov_mgr

官方配网管理器，可用 BLE 或 SoftAP 把 Wi-Fi 凭据送进设备。

解决开箱即用问题：用户无需电脑或串口，用手机即可完成配网。

适用于消费/工商业设备，如智能家居、传感器、工业网关等。

不适用于实验室样机或密码固定的场景，此时可跳过配网。

支持多种传输方式，可灵活选择 BLE 或 SoftAP，甚至可扩展其他传输。

1. 初始化 NVS，用于存储配网信息。

2. 启动 Wi-Fi 和 BLE（若使用 BLE 传输）或 SoftAP。

3. 调用 esp_wifi_prov_mgr_start_provisioning()，选择传输方式和安全方案。

4. 手机 App 通过 BLE GATT 或 SoftAP HTTP 发送 SSID/密码。

5. 配网成功后，prov manager 自动保存凭据到 NVS，并停止配网服务。

6. 设备重启后，自动读取 NVS 并连接 Wi-Fi。

7. 若连接失败或需要重新配网，可通过按键或命令触发重新配网。

8. 处理配网超时和错误，提供用户反馈（如 LED 变化）。