特性：新增 Wi-Fi 连接模块并集成至主应用

实现连接功能：在 wifi-connect.c 中实现了 Wi-Fi 连接逻辑，支持设备连接无线网络并管理相关配置。
更新依赖配置：修改 CMakeLists.txt，将新增的 wifi-connect 组件添加为项目依赖。
修改主程序入口：调整 main.c，在应用启动阶段初始化 Wi-Fi 连接模块。
新增分区表：添加 partitions.csv 文件，定义 NVS（非易失性存储）和应用程序的内存分区，确保数据正确存储。

components/wifi-connect/CMakeLists.txt

@@ -0,0 +1,5 @@
+idf_component_register(
+    SRCS "wifi-connect.c"
+    INCLUDE_DIRS "include"
+    REQUIRES esp_wifi esp_timer  esp_event esp_netif nvs_flash esp_http_server lwip driver
+)

components/wifi-connect/Kconfig.projbuild

@@ -0,0 +1,18 @@
+menu "WiFi 连接"
+
+config WIFI_CONNECT_CONNECT_TIMEOUT_SEC
+    int "Wi-Fi 连接超时 (秒)"
+    range 5 180
+    default 30
+
+config WIFI_CONNECT_MAX_SCAN_RESULTS
+    int "最大扫描结果数"
+    range 5 50
+    default 20
+
+config WIFI_CONNECT_AP_MAX_CONNECTIONS
+    int "软AP最大连接数"
+    range 1 10
+    default 4
+
+endmenu

components/wifi-connect/README.md

@@ -0,0 +1,165 @@
+# 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`：
+
+```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）

components/wifi-connect/include/wifi-connect.h

@@ -0,0 +1,34 @@
+#pragma once
+
+#include <stdbool.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+	WIFI_CONNECT_STATUS_IDLE = 0,
+	WIFI_CONNECT_STATUS_PROVISIONING,
+	WIFI_CONNECT_STATUS_CONNECTING,
+	WIFI_CONNECT_STATUS_CONNECTED,
+	WIFI_CONNECT_STATUS_FAILED,
+	WIFI_CONNECT_STATUS_TIMEOUT,
+} wifi_connect_status_t;
+
+typedef struct {
+	bool has_config;
+	char ssid[33];
+	char password[65];
+} wifi_connect_config_t;
+
+esp_err_t wifi_connect_init(void);
+esp_err_t wifi_connect_start(void);
+esp_err_t wifi_connect_stop(void);
+wifi_connect_status_t wifi_connect_get_status(void);
+esp_err_t wifi_connect_get_config(wifi_connect_config_t *config);
+esp_err_t wifi_connect_clear_config(void);
+
+#ifdef __cplusplus
+}
+#endif

main/CMakeLists.txt

@@ -1,3 +1,3 @@
 idf_component_register(SRCS "main.c"
                     INCLUDE_DIRS "."
-                    REQUIRES ws2812)
+                    REQUIRES ws2812 wifi-connect)

main/main.c

@@ -1,10 +1,14 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
-
+#include "wifi-connect.h"
 #include "ws2812.h"
 
 void app_main(void)
 {
-	ws2812_start_task();
+    wifi_connect_init();    // 初始化 Wi-Fi 配网模块
-	vTaskDelete(NULL);
+	ws2812_start_task();    // 启动 WS2812 LED 灯控制任务
+    for(;;)
+    {
+        vTaskDelay(100000);
+    }
 }

partitions.csv

@@ -0,0 +1,4 @@
+# Name,Type,SubType,Offset,Size,Flags
+nvs,data,nvs,0x9000,0x6000,
+phy_init,data,phy,0xf000,0x1000,
+factory,app,factory,0x10000,0x390000,