SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsesp32-wifi-provision

esp32-wifi-provision

General & other

View repository

Updated 10-15 21:48

About this skill

ESP32 Wi-Fi Provisioning

Provisioning is the process of securely delivering Wi-Fi credentials into the device. This Skill first does mode selection, then gives the state machine and security red lines;do not fabricate transport-layer details from memory— any parameters not captured in the baseline are marked "verify at runtime".

Determine Task Type

  1. Product mass-production selection: no provisioning mode has been decided yet, need to choose from the four official modes → first read the selection table + provisioning-comparison。
  2. Mode already decided, need to implement: e.g. "Unified Provisioning + BLE + Security 2" → start from Step 3 of the Workflow, for security scheme details read security-scheme。
  3. Provisioning troubleshooting: provisioning succeeds but cannot connect, re-provisioning does not take effect, Security handshake fails → Step 5 of the Workflow + Pitfalls.
  4. Credential lifecycle: re-provisioning strategy after changing password/changing router → state machine "credential invalid" branch.

Prerequisites / Preflight

Verify at runtime first; if any item is missing, ask, do not guess:

idf.py --version          # 确认 IDF 版本（基线见 Offline Baseline）
idf.py list-targets 2>/dev/null | head -5 || echo "IDF not in PATH"
  1. Target chip: Does it have Wi-Fi? Does it have Bluetooth? (red lines see Contracts—H2/P4 have no Wi-Fi radio, S2 has no Bluetooth)
  2. Companion phone App: Can users be required to install the official ESP BLE Provisioning / ESP SoftAP Provisioning App?
  3. RAM budget: BLE transport requires about 110KB RAM (baseline high confidence)—confirm first for low-memory solutions.
  4. Component status: whether the project uses the current component network_provisioning or the old component wifi_provisioning(see the migration section in references/comparison).

Offline Baseline

  • ESP-IDF baseline = v6.1(latest stable, as of walkthrough 2026-09-02, not auto-updated); the four provisioning modes, Security 0/1/2, and SoftAP/BLE transport are cited from baseline §7 (captured from official provisioning documentation, high confidence).
  • NVS persistent credentials: baseline marks "verify at runtime"—the official captured page does not directly confirm it; this Skill keeps that marking, and after implementation it must be verified on a real device that credentials are still present after reboot (Validation Gate 3).
  • Behavior changes after version are subject to the official provisioning documentation; do not assert from memory.

Contracts (device contract)

  • Chip wireless capability red lines (high-frequency error points, baseline high confidence)：ESP32-H2 no Wi-Fi；ESP32-P4 no on-chip radio(requires companion solutions such as ESP-Hosted); ESP32-S2 no Bluetooth(cannot choose BLE transport). Check this before selection; if it does not match, stop.
  • Do not hardcode credentials: SSID/password must not be hardcoded in firmware source code or sdkconfig default values and distributed with the image (see security red lines).
  • Provisioning writes to NVS/Flash: when performing batch operations or recycling devices, pay attention to credential remnants; do not perform actions that "silently clear user data"; inform before executing.
  • Specific phone-side App versions, exact package names and version numbers on the component registry: base them on runtime idf.py add-dependency query results.

Selection among the four official modes (baseline §7, high confidence)

Mode Mechanism Transport Applicable Notes
Unified Provisioning (recommended) Unified provisioning protocol based on protocomm SoftAP(+HTTP) or BLE(GATT) The vast majority of mass-production products Security 0/1/2 selectable (default 2); official iOS/Android App available
SmartConfig legacy, UDP broadcast-type mechanism over-the-air broadcast existing stock compatibility only weak reliability, depends on network environment, not recommended for new products; refer to official documentation for details
Wi-Fi Easy Connect (DPP) Wi-Fi Alliance Easy Connect scan QR code/channel introduction strong interoperability requirements baseline only confirms "existence"; parameter details verified at runtime
protocomm direct use underlying transport + security scheme foundation custom has custom App/protocol team lower layer of Unified Provisioning; when used directly, you bear the protocol design yourself

For selection criteria details (RAM, App threshold, migrating legacy components, exception retry design) read provisioning-comparison。

provisioning state machine

未配网(UNPROVISIONED)
    -> 收到配网请求 -> 配网中(PROVISIONING)   [指示灯/提示用户]
    -> 凭据下发 + 尝试连接
    ├── 连上并确认在线 -> 已配网(PROVISIONED)
    └── 连接失败(密码错/信号弱) -> 停留并回报错误 -> 回到 配网中 或 未配网
已配网
    └── 凭据失效(改密/路由器更换/认证超时) -> 凭据失效重配(RE-PROVISION)
        -> 重新进入 配网中（旧凭据失效处理策略见 references/comparison §4）

Each device must persist the "whether provisioned" state; after reboot, use it to decide whether to connect directly to Wi-Fi or enter provisioning mode.

Capability Boundaries + Hand-off

User Intent Skill
use as firmware upgrade channel after provisioning is complete esp32-ota
chip has no Wi-Fi/Bluetooth or selection is undecided esp32-variants
provisioning service task/queue design esp32-freertos
provisioning window under low power (deep sleep wake then provision) esp32-lowpower
engineering skeleton/partition table/flashing esp32-idf
full provisioning flow acceptance on real hardware fw-hil-testing

Out of scope: custom transport protocol design beyond BLE/SoftAP, and mobile App development itself—this Skill only provides protocol selection and the device side; for the App side it only points to the official App.

Workflow

  1. Verify environment: Preflight command + chip wireless capability check (Contracts red line).
  2. Selection: determine "transport + security scheme" per the selection table; mass production default Unified Provisioning + Security 2, transport chosen as BLE or SoftAP per App/RAM budget.
  3. Integrate components：idf.py add-dependency <network_provisioning 组件名=版本>(the exact namespace and version are subject to runtime registry query, write into idf_component.yml); legacy component wifi_provisioning projects evaluated for migration per references/comparison §5.
  4. Implement state machine: persist provisioning state; provide user-perceivable indication during provisioning; on failure must report a specific error (error code passed through to the App), no silent retry.
  5. Real hardware verification: pass Validation Gates 1–4; NVS persisted items perform "runtime verification" per baseline annotations.
  6. Before mass production: recheck security scheme against security-scheme red line; full-flow acceptance on real hardware → fw-hil-testing。

Validation Gates

  1. Normal path: official App completes provisioning, device connects to target router and gets online confirmation (e.g. MQTT/HTTP heartbeat).
  2. Exception path: deliberately enter wrong password → device reports an error instead of "pretending success"; timeout has an upper limit.
  3. Persistence verification (runtime verification item): after power cycle and reboot, the device automatically reconnects without needing to provision again—this item is not directly confirmed in the baseline and may only be claimed as supported after actual testing on the target real hardware passes.
  4. Security verification: confirm the Production build did not compile in Security 0; confirm via packet capture/logs that credentials do not appear in plaintext in serial logs.
  5. When no real hardware is available: mark all conclusions as Build Verification Only, and do not claim "provisioning verified".

Pitfalls

  1. Do nothardcode the SSID/password into the firmware (source code,Kconfig Default values and test firmware all count) — a production image with credentials is equivalent to selling off the user's network.
  2. Don'tUse Security 0 (no encryption) in a Production environment — credentials can be intercepted directly on the provisioning channel.
  3. Don'tChoose BLE transport for S2, or assign Wi-Fi provisioning tasks to H2/P4 — first verify the chip's wireless capabilities (Contracts).
  4. Don'tAssume that "writing to NVS will definitely persist successfully" — this is a runtime verification item flagged in the baseline, and must not be promised before real-device reboot verification.
  5. Don'tChoose SmartConfig for a new product and promise reliability — it is a legacy compatibility option.
  6. Don'tSwallow provisioning failure error codes — both the user and the App need to know whether it is a wrong password or a timeout.

Official Sources

Privacy

The SSID/password handled by this Skill are the user's network credentials: do not collect, store, or send them externally; examples and logs must always use placeholders (such as SSID_PLACEHOLDER), and users are required not to paste real credentials into issues, logs, or code repositories.