BotanicalBuddy/components/wifi-connect

wifi-connect 组件说明

wifi-connect 是一个基于 ESP-IDF 的 Wi-Fi 配网组件，支持：

• 长按按键进入配网模式
• 启动 SoftAP + Captive Portal（网页配网）
• 手机连接热点后，通过网页扫描并选择路由器
• 保存 Wi-Fi 凭据到 NVS
• 下次开机自动重连
• 支持两种配网模式：按键触发 / 常驻配网

面向最终用户的一页版操作说明见：USER_GUIDE.md 现场打印张贴版（四步卡）见：QUICK_POSTER.md

---

目录结构

• wifi-connect.c：组件主实现（按键、APSTA、HTTP、DNS、状态机）
• include/wifi-connect.h：对外 API
• Kconfig.projbuild：组件配置项
• CMakeLists.txt：组件构建依赖

---

对外 API

头文件：include/wifi-connect.h

• esp_err_t wifi_connect_init(void);

  • 初始化组件（NVS、Wi-Fi、事件、按键任务等）
  • 尝试自动连接已保存网络

• esp_err_t wifi_connect_start(void);

  • 启动配网（APSTA + HTTP + DNS）

• esp_err_t wifi_connect_stop(void);

  • 停止配网（关闭热点与相关服务）

• wifi_connect_status_t wifi_connect_get_status(void);

  • 获取当前状态：idle / provisioning / connecting / connected / failed / timeout

• esp_err_t wifi_connect_get_config(wifi_connect_config_t *config);

  • 读取已保存的 Wi-Fi 凭据

• esp_err_t wifi_connect_clear_config(void);

  • 清除已保存的 Wi-Fi 凭据（SSID/密码）

---

快速使用

在 main/main.c：

#include "esp_check.h"
#include "wifi-connect.h"

void app_main(void)
{
    ESP_ERROR_CHECK(wifi_connect_init());
}

运行后：

1. 选择配网模式：

• 按键触发模式：长按配置按键进入配网
• 常驻配网模式：上电自动进入配网

2. 手机连接 ESP32-xxxxxx 热点
3. 打开 http://192.168.4.1
4. 选择 Wi-Fi 并输入密码提交
5. 配网行为：

• 按键触发模式：连接成功后按配置自动关闭热点
• 常驻配网模式：配网热点保持开启，不自动关闭

如需清空历史凭据，可在配网页面点击“清除已保存”。

---

Kconfig 配置项

在 idf.py menuconfig 中：WiFi Connect 菜单

• Provisioning mode：配网模式（二选一）

  • Button triggered：按键触发配网（默认）
  • Always-on provisioning：常驻配网（上电自动进入且不自动关闭）

• WIFI_CONNECT_BUTTON_GPIO：进入配网的按键 GPIO

• WIFI_CONNECT_BUTTON_ACTIVE_LEVEL：按键有效电平

• WIFI_CONNECT_DEBOUNCE_MS：按键去抖时间

• WIFI_CONNECT_LONG_PRESS_MS：长按触发时长

• WIFI_CONNECT_BUTTON_STARTUP_GUARD_MS：上电保护窗口（该时间内忽略长按检测）

• WIFI_CONNECT_BUTTON_RELEASE_ARM_MS：松手解锁时间（先稳定松手再允许长按触发）

• WIFI_CONNECT_CONNECT_TIMEOUT_SEC：连接路由器超时

• WIFI_CONNECT_IDLE_TIMEOUT_SEC：配网页面空闲超时

• WIFI_CONNECT_MAX_SCAN_RESULTS：扫描网络最大数量

• WIFI_CONNECT_AP_MAX_CONNECTIONS：SoftAP 最大连接数

• WIFI_CONNECT_AP_GRACEFUL_STOP_SEC：联网成功后 AP 延迟关闭秒数

---

日志与状态说明（中文）

组件会输出统一中文状态日志，例如：

• 【状态】wifi-connect 初始化完成
• 【状态】检测到按键长按：开始进入配网模式
• 【状态】配网已启动：配网热点已开启，SSID=...
• 【状态】开始连接路由器：收到配网请求，目标网络=...
• 【状态】联网成功：已连接 ...，获取 IP=...
• 【状态】配网已停止：热点已关闭，设备继续以 STA 模式运行

说明：ESP-IDF 驱动层（如 wifi:、esp_netif_lwip:）仍会输出英文日志，这是框架默认行为。

---

常见问题

1) 手机连上热点但不自动弹出页面

• 手动访问：http://192.168.4.1
• 确认手机没有强制使用 HTTPS
• 查看串口是否有 配网已启动、DNS 劫持服务已启动 日志

2) 提交后连接失败

• 检查密码是否正确
• 查看日志中的失败原因码（连接失败，原因=...）
• 检查路由器是否禁用了新设备接入
• 若曾保存过旧配置，可先在页面点击“清除已保存”后再重试

4) 按键未按下却误触发配网

• 常见原因是按键引脚与 LCD/外设复用，初始化期间电平抖动被误判为长按
• 可增大 WIFI_CONNECT_BUTTON_STARTUP_GUARD_MS（如 8000~10000）
• 可增大 WIFI_CONNECT_BUTTON_RELEASE_ARM_MS（如 300~500）
• 若硬件允许，优先给配网按键使用独立 GPIO

5) 成功后热点消失是否正常

• 在按键触发模式下：正常，可通过 WIFI_CONNECT_AP_GRACEFUL_STOP_SEC 调整关闭延时
• 在常驻配网模式下：热点不会自动关闭

---

依赖

由 CMakeLists.txt 声明：

• esp_wifi
• esp_timer
• esp_event
• esp_netif
• nvs_flash
• esp_http_server
• lwip
• driver

---

版本建议

• 推荐 ESP-IDF v5.5.x
• 当前项目验证环境：esp-idf v5.5.2（ESP32-C3）