166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# 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）
|