junhui93/wifi_provisioner

Readme

# WiFi Provisioner / WiFi 配网组件

**EN** — Commercial-friendly WiFi provisioning component for ESP-IDF with captive-portal fallback and persistent auto-reconnect.

**中文** — 面向 ESP-IDF 的商用级 WiFi 配网组件，支持 Soft-AP 强制门户配网与断连持续自动重连。

> **EN | Why this component?** The original `esp-idf-wifi-provisioner` is licensed under GPL-3.0, which requires the entire project to be open-sourced. This component is written from scratch under the **MIT license** — safe for commercial and closed-source products.
>
> **中文 | 为什么选它？** 原始的 `esp-idf-wifi-provisioner` 采用 GPL-3.0 协议，要求整个工程开源。本组件基于 **MIT 协议**从头实现——可安全用于商用及闭源产品。

---

## Features / 功能特性

**EN**
- **STA auto-connect** from credentials stored in NVS
- **Soft-AP + captive portal** fallback when no credentials are stored or connection fails
- **WiFi network scan** with signal strength display in the captive portal
- **Credential verification** — submitted credentials are tested before being saved
- **Persistent auto-reconnect** — after a successful connection, if the link drops the component keeps reconnecting with exponential back-off
- **Non-blocking API** — `wifi_prov_start()` returns immediately; all work happens in a background task
- **Configurable** via menuconfig or runtime `wifi_prov_config_t`
- **Event callbacks** for connect, disconnect, and portal start

**中文**
- **STA 自动连接**：从 NVS 读取已保存的凭证自动联网
- **Soft-AP + 强制门户回退**：无凭证或连接失败时自动开启配网门户
- **WiFi 扫描**：配网页面展示附近网络及信号强度
- **凭证校验**：用户提交的密码先尝试连接验证，成功才保存
- **断连持续重连**：连接成功后若链路断开，以指数退避持续重连
- **非阻塞 API**：`wifi_prov_start()` 立即返回，所有工作在后台任务中进行
- **灵活配置**：支持 menuconfig 或运行时 `wifi_prov_config_t` 配置
- **事件回调**：连接、断开、门户启动三种回调

---

## Requirements / 运行环境

**EN**
- ESP-IDF >= 5.0
- Targets: ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6

**中文**
- ESP-IDF >= 5.0
- 支持目标：ESP32、ESP32-S2、ESP32-S3、ESP32-C3、ESP32-C6

---

## Installation / 安装

**EN** — Add the component to your project's `idf_component.yml`:

**中文** — 在工程的 `idf_component.yml` 中添加依赖：

```yaml
dependencies:
  junhui93/wifi_provisioner: "^1.0.0"
```

**EN** — Or copy the `wifi_provisioner` folder into your project's `components/` directory.

**中文** — 也可以将 `wifi_provisioner` 文件夹拷贝到工程的 `components/` 目录下。

---

## Quick Start / 快速开始

```c
#include "wifi_provisioner.h"

void app_main(void)
{
    /* EN: Initialise config with Kconfig defaults.
       中文: 用 Kconfig 默认值初始化配置。 */
    wifi_prov_config_t config = WIFI_PROV_DEFAULT_CONFIG();
    config.ap_ssid = "MyDevice-Setup";

    /* EN: Enable persistent auto-reconnect after disconnection.
       中文: 开启断连后持续自动重连。 */
    config.auto_reconnect          = true;
    config.reconnect_interval_ms   = 5000;    /* base retry interval / 基础重试间隔 */
    config.reconnect_max_delay_ms  = 60000;   /* cap back-off at 60 s / 退避上限 60 秒 */

    ESP_ERROR_CHECK(wifi_prov_start(&config));

    /* EN: wifi_prov_start() returns immediately. Use the on_connected
       callback or wifi_prov_wait_for_connection() to know when WiFi is ready.
       中文: wifi_prov_start() 立即返回，通过 on_connected 回调或
       wifi_prov_wait_for_connection() 获知 WiFi 就绪。 */

    while (1) {
        if (wifi_prov_is_connected()) {
            /* do your network work here / 在此执行业务逻辑 */
        }
        vTaskDelay(pdMS_TO_TICKS(5000));
    }
}
```

---

## How It Works / 工作原理

**EN**
1. On `wifi_prov_start()`, the component reads the SSID and password stored in NVS.
2. If credentials exist, it tries to connect as a station (up to `max_retries` times).
3. On success, the device is online and auto-reconnect is armed.
4. On failure (or if no credentials are stored), the component starts a Soft-AP and a captive portal HTTP server.
5. The user connects to the AP, opens any URL (or `192.168.4.1`), selects a network, enters the password, and submits.
6. The component verifies the credentials by connecting; on success it saves them to NVS and switches to STA mode.

**中文**
1. 调用 `wifi_prov_start()` 后，组件从 NVS 读取已保存的 SSID 和密码。
2. 若存在凭证，尝试以 STA 模式连接（最多重试 `max_retries` 次）。
3. 连接成功后设备上线，同时启用断连自动重连。
4. 连接失败（或无凭证）时，组件启动 Soft-AP 和强制门户 HTTP 服务器。
5. 用户连接该 AP，打开任意网址（或直接访问 `192.168.4.1`），选择网络并输入密码提交。
6. 组件先尝试连接验证凭证，成功后将其保存到 NVS 并切换为 STA 模式。

---

## Persistent Auto-Reconnect / 断连持续重连

**EN** — After a successful connection, if the WiFi link drops, the component automatically attempts to reconnect:
- A single background task handles reconnection (no duplicate `esp_wifi_connect()` calls).
- **Exponential back-off**: `delay = min(interval × 2^attempts, max_delay_ms)`.
- Can be toggled at runtime with `wifi_prov_set_auto_reconnect(bool)`.
- An `on_disconnected` callback notifies the application with the disconnect reason.

**中文** — 连接成功后若 WiFi 链路断开，组件自动尝试重连：
- 单一后台任务处理重连（避免重复调用 `esp_wifi_connect()`）。
- **指数退避**：`delay = min(interval × 2^attempts, max_delay_ms)`。
- 可通过 `wifi_prov_set_auto_reconnect(bool)` 运行时开关。
- `on_disconnected` 回调通知应用层断开原因。

---

## API Reference / API 参考

| Function | EN Description | 中文说明 |
|---|---|---|
| `wifi_prov_init()` | Initialise NVS, netif, event loop. Called automatically by `wifi_prov_start()`. | 初始化 NVS、网络接口、事件循环，`wifi_prov_start()` 会自动调用。 |
| `wifi_prov_start(config)` | Start the provisioner. Returns immediately; work runs in a background task. | 启动配网器，立即返回，工作在后台任务中运行。 |
| `wifi_prov_stop()` | Stop and release all resources. | 停止并释放所有资源。 |
| `wifi_prov_wait_for_connection(ticks)` | Block until connected (with timeout). Returns `ESP_OK` or `ESP_ERR_TIMEOUT`. | 阻塞等待连接（带超时），返回 `ESP_OK` 或 `ESP_ERR_TIMEOUT`。 |
| `wifi_prov_is_connected()` | Check if connected with a valid IP. | 查询是否已连接并获得有效 IP。 |
| `wifi_prov_get_ip_info(ip_info)` | Get current station IP information. | 获取当前 STA 的 IP 信息。 |
| `wifi_prov_erase_credentials()` | Erase stored WiFi credentials from NVS. | 清除 NVS 中保存的 WiFi 凭证。 |
| `wifi_prov_set_auto_reconnect(enable)` | Enable or disable persistent auto-reconnect at runtime. | 运行时开启或关闭断连持续重连。 |
| `wifi_prov_get_auto_reconnect()` | Query whether auto-reconnect is enabled. | 查询重连是否已开启。 |

---

## Configuration / 配置

**EN** — All parameters can be set via **menuconfig** (`Component config → WiFi Provisioner`) or by overriding fields in `wifi_prov_config_t` at runtime.

**中文** — 所有参数可通过 **menuconfig**（`Component config → WiFi Provisioner`）或运行时覆盖 `wifi_prov_config_t` 字段设置。

### Soft-AP

| Field / 字段 | Kconfig | Default / 默认值 |
|---|---|---|
| `ap_ssid` | `CONFIG_WIFI_PROV_AP_SSID` | `"ESP32-Setup"` |
| `ap_password` | `CONFIG_WIFI_PROV_AP_PASSWORD` | `""` (open / 开放) |
| `ap_channel` | `CONFIG_WIFI_PROV_AP_CHANNEL` | `1` |
| `ap_max_connections` | `CONFIG_WIFI_PROV_AP_MAX_CONNECTIONS` | `4` |

### STA Connection / STA 连接

| Field / 字段 | Kconfig | Default / 默认值 |
|---|---|---|
| `max_retries` | `CONFIG_WIFI_PROV_STA_MAX_RETRIES` | `5` |

### Auto-Reconnect / 自动重连

| Field / 字段 | Kconfig | Default / 默认值 |
|---|---|---|
| `auto_reconnect` | `CONFIG_WIFI_PROV_AUTO_RECONNECT` | `true` |
| `reconnect_interval_ms` | `CONFIG_WIFI_PROV_RECONNECT_INTERVAL_MS` | `5000` |
| `reconnect_max_delay_ms` | `CONFIG_WIFI_PROV_RECONNECT_MAX_DELAY_MS` | `60000` |

### Portal / 配网门户

| Field / 字段 | Kconfig | Default / 默认值 |
|---|---|---|
| `portal_timeout` | `CONFIG_WIFI_PROV_PORTAL_TIMEOUT` | `300` (s) |
| `http_port` | `CONFIG_WIFI_PROV_HTTP_PORT` | `80` |

---

## Callbacks / 回调函数

```c
typedef void (*wifi_prov_on_connected_cb_t)(void);
typedef void (*wifi_prov_on_disconnected_cb_t)(uint8_t reason);
typedef void (*wifi_prov_on_portal_start_cb_t)(void);
```

**EN** — Set them in `wifi_prov_config_t`:

**中文** — 在 `wifi_prov_config_t` 中设置：

```c
config.on_connected    = my_on_connected;
config.on_disconnected = my_on_disconnected;
config.on_portal_start = my_on_portal_start;
```

---

## Examples / 示例

**EN** — A complete example is available in [`examples/basic/`](examples/basic/). It demonstrates:
- Non-blocking startup
- Persistent auto-reconnect configuration
- Connect/disconnect/portal callbacks
- Main loop with connection state polling

**中文** — 完整示例见 [`examples/basic/`](examples/basic/)，演示：
- 非阻塞启动
- 断连持续重连配置
- 连接 / 断开 / 门户启动回调
- 主循环中轮询连接状态

---

## License / 许可证

**EN** — MIT — free for commercial and closed-source use. See [LICENSE](LICENSE).

**中文** — MIT 协议——可免费用于商用及闭源项目。详见 [LICENSE](LICENSE)。