365 lines
9.0 KiB
Markdown
365 lines
9.0 KiB
Markdown
# ESP32 配网组件设计实践：聚焦功能与实现，而不是项目绑定
|
||
|
||
很多 ESP32 设备在开发阶段都把“配网”当成一个小功能，但真正落地后会发现：
|
||
|
||
- 用户第一次接入要顺畅
|
||
- 失败后要能恢复
|
||
- 日志要便于现场排障
|
||
|
||
这篇文章只讲配网组件本身，聚焦能力设计和实现思路，不依赖具体业务项目。
|
||
|
||
---
|
||
|
||
## 一、目标能力定义
|
||
|
||
一个可落地的配网组件，建议至少包含以下能力：
|
||
|
||
- 按键触发配网
|
||
- 常驻配网模式（可选）
|
||
- SoftAP + Web Portal 配网
|
||
- DNS 劫持与常见 Captive Portal 兼容
|
||
- 凭据持久化（NVS）与重启自动重连
|
||
- 清除历史配置（API + Web）
|
||
- 状态机与可读日志
|
||
|
||
这几项组合起来，才能覆盖“首次成功 + 失败恢复 + 现场维护”三个关键场景。
|
||
|
||
图示（整体功能目标关联）：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[按键任务/业务触发] --> B[进入 provisioning]
|
||
B --> C[启动 SoftAP]
|
||
B --> D[启动 HTTP Server]
|
||
B --> E[启动 DNS Hijack]
|
||
D --> F[/api/scan]
|
||
D --> G[/api/connect]
|
||
D --> H[/api/status]
|
||
D --> I[/api/clear]
|
||
G --> J[设置 STA 参数]
|
||
J --> K[发起 esp_wifi_connect]
|
||
K --> L{Wi-Fi/IP 事件}
|
||
L -->|成功| M[状态=connected]
|
||
L -->|失败| N[状态=failed]
|
||
I --> O[清除 NVS 凭据]
|
||
O --> P[清空运行态缓存]
|
||
P --> B
|
||
```
|
||
|
||
---
|
||
|
||
## 二、组件架构（通用）
|
||
|
||
```text
|
||
[按键任务] --> [进入配网]
|
||
|
|
||
+--> SoftAP + HTTP Server + DNS Hijack
|
||
|
||
[Web] -- /api/scan --> Wi-Fi 扫描
|
||
[Web] -- /api/connect --> 设置 STA 并发起连接
|
||
[Web] -- /api/status --> 轮询状态
|
||
[Web] -- /api/clear --> 清除已保存配置
|
||
|
||
[Wi-Fi/IP 事件] --> 更新状态机 + 打印日志 + 保存凭据
|
||
```
|
||
|
||
推荐状态机：
|
||
|
||
- `idle`
|
||
- `provisioning`
|
||
- `connecting`
|
||
- `connected`
|
||
- `failed`
|
||
- `timeout`
|
||
|
||
图示（状态机）：
|
||
|
||
```mermaid
|
||
stateDiagram-v2
|
||
[*] --> idle
|
||
idle --> provisioning: wifi_connect_start()
|
||
provisioning --> connecting: POST /api/connect
|
||
connecting --> connected: GOT_IP
|
||
connecting --> failed: AUTH_FAIL / NO_AP / ...
|
||
connecting --> timeout: connect timeout
|
||
failed --> provisioning: POST /api/clear
|
||
timeout --> provisioning: POST /api/clear
|
||
connected --> provisioning: 常驻配网继续开放入口(可选)
|
||
connected --> idle: stop provisioning(按策略)
|
||
```
|
||
|
||
上图展示了组件的主要数据流与恢复路径。
|
||
|
||
---
|
||
|
||
## 三、对外 API 设计建议
|
||
|
||
推荐保持“少而稳”的接口：
|
||
|
||
```c
|
||
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);
|
||
```
|
||
|
||
设计原则：
|
||
|
||
- `init` 只做初始化和基础恢复
|
||
- `start/stop` 控制配网生命周期
|
||
- `get_status` 作为 UI/接口层统一读取入口
|
||
- `clear_config` 提供失败恢复通道
|
||
|
||
可以展示一段“典型调用顺序”代码：
|
||
|
||
```c
|
||
ESP_ERROR_CHECK(wifi_connect_init());
|
||
|
||
// 按键触发或业务触发时
|
||
ESP_ERROR_CHECK(wifi_connect_start());
|
||
|
||
// UI 侧轮询状态
|
||
wifi_connect_status_t st = wifi_connect_get_status();
|
||
|
||
// 需要恢复出厂配网时
|
||
ESP_ERROR_CHECK(wifi_connect_clear_config());
|
||
```
|
||
|
||
图示（API 生命周期时序）：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant App as 应用层
|
||
participant WC as wifi-connect
|
||
participant WiFi as esp_wifi
|
||
participant Web as 配网页面
|
||
|
||
App->>WC: wifi_connect_init()
|
||
WC-->>App: ESP_OK
|
||
|
||
App->>WC: wifi_connect_start()
|
||
WC->>WiFi: 开启 APSTA / 事件注册
|
||
WC-->>App: ESP_OK
|
||
|
||
Web->>WC: POST /api/connect(ssid,pass)
|
||
WC->>WiFi: esp_wifi_disconnect()
|
||
WC->>WiFi: esp_wifi_set_config()
|
||
WC->>WiFi: esp_wifi_connect()
|
||
|
||
WiFi-->>WC: WIFI_EVENT / IP_EVENT
|
||
alt 获取到 IP
|
||
WC-->>Web: status=connected
|
||
else 连接失败或超时
|
||
WC-->>Web: status=failed|timeout
|
||
end
|
||
|
||
Web->>WC: POST /api/clear
|
||
WC-->>Web: status=provisioning
|
||
```
|
||
|
||
上图对应完整 API 生命周期（init -> start -> connecting -> connected/failed -> clear）。
|
||
|
||
---
|
||
|
||
## 四、关键实现点
|
||
|
||
### 1) Web 配网页面保持轻量
|
||
|
||
不一定要引入前端框架。对于资源受限设备，内嵌简洁 HTML/JS 往往更稳定。
|
||
|
||
建议页面只保留核心动作：
|
||
|
||
- 扫描网络
|
||
- 提交连接
|
||
- 查看状态
|
||
- 清除配置
|
||
|
||
### 2) Captive Portal 兼容是体验关键
|
||
|
||
仅提供首页 URL 通常不够。建议额外处理：
|
||
|
||
- 常见探测路径（如 `generate_204` 等）
|
||
- 未知路径统一 302 到配网页
|
||
|
||
这样手机系统弹门户页面成功率会明显提高。
|
||
|
||
示例代码（伪代码）：
|
||
|
||
```c
|
||
static esp_err_t captive_redirect_handler(httpd_req_t *req)
|
||
{
|
||
httpd_resp_set_status(req, "302 Found");
|
||
httpd_resp_set_hdr(req, "Location", "http://192.168.4.1/");
|
||
return httpd_resp_send(req, NULL, 0);
|
||
}
|
||
|
||
// 注册常见探测路径
|
||
httpd_register_uri_handler(server, &uri_generate_204);
|
||
httpd_register_uri_handler(server, &uri_hotspot_detect);
|
||
httpd_register_uri_handler(server, &uri_ncsi);
|
||
```
|
||
|
||
可直接使用以下流程图（对应 Captive Portal 重定向路径）：
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[手机连接设备 AP] --> B[访问任意域名]
|
||
B --> C[DNS Hijack 返回 192.168.4.1]
|
||
C --> D[HTTP 探测路径请求<br/>/generate_204 等]
|
||
D --> E[302 Location: http://192.168.4.1/]
|
||
E --> F[打开配网页面]
|
||
F --> G[扫描 / 连接 / 清除配置]
|
||
```
|
||
|
||
### 3) 连接前主动断开旧连接
|
||
|
||
这是一个高频坑：设备已有 STA 连接时，直接连接新 AP 可能导致超时或异常状态。
|
||
|
||
建议在 `esp_wifi_set_config + esp_wifi_connect` 前先执行 `esp_wifi_disconnect()`，并对异常返回做日志记录。
|
||
|
||
示例代码：
|
||
|
||
```c
|
||
esp_err_t err = esp_wifi_disconnect();
|
||
if (err != ESP_OK && err != ESP_ERR_WIFI_NOT_CONNECT) {
|
||
ESP_LOGW(TAG, "disconnect before reconnect failed: %s", esp_err_to_name(err));
|
||
}
|
||
|
||
ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, &cfg));
|
||
ESP_ERROR_CHECK(esp_wifi_connect());
|
||
```
|
||
|
||
### 4) “清除配置”必须打通全链路
|
||
|
||
建议同时提供：
|
||
|
||
- SDK API：`wifi_connect_clear_config()`
|
||
- HTTP API：`POST /api/clear`
|
||
- 页面按钮：`清除已保存`
|
||
|
||
这样现场人员无需改固件即可恢复设备。
|
||
|
||
建议把清除动作写成“存储层 + 运行态”两段：
|
||
|
||
```c
|
||
esp_err_t wifi_connect_clear_config(void)
|
||
{
|
||
// 1) 清 NVS 凭据
|
||
ESP_RETURN_ON_ERROR(nvs_erase_key(nvs, "ssid"), TAG, "erase ssid failed");
|
||
ESP_RETURN_ON_ERROR(nvs_erase_key(nvs, "pass"), TAG, "erase pass failed");
|
||
ESP_RETURN_ON_ERROR(nvs_commit(nvs), TAG, "nvs commit failed");
|
||
|
||
// 2) 清内存态并回到 provisioning
|
||
memset(&s_ctx.pending_cfg, 0, sizeof(s_ctx.pending_cfg));
|
||
s_ctx.status = WIFI_CONNECT_STATUS_PROVISIONING;
|
||
return ESP_OK;
|
||
}
|
||
```
|
||
|
||
可直接使用以下流程图（对应 clear 后状态回到 provisioning）：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[开始清除配置] --> B[擦除 NVS:ssid]
|
||
B --> C[擦除 NVS:pass]
|
||
C --> D[nvs_commit]
|
||
D --> E[清空 pending 配置缓存]
|
||
E --> F[清空错误原因/中间状态]
|
||
F --> G[状态切回 provisioning]
|
||
G --> H[前端轮询显示 可重新配网]
|
||
```
|
||
|
||
---
|
||
|
||
## 五、日志策略（非常重要）
|
||
|
||
建议日志遵循“状态 + 原因”格式，例如：
|
||
|
||
- `【状态】配网已启动：热点已开启，SSID=...`
|
||
- `【状态】开始连接路由器：目标网络=...`
|
||
- `【状态】联网成功：获取 IP=...`
|
||
- `【状态】连接失败：原因=...`
|
||
|
||
这样做的收益是：
|
||
|
||
- 开发调试快
|
||
- 测试可直接定位阶段
|
||
- 现场人员无需先理解底层驱动日志
|
||
|
||
可展示一个统一日志函数风格：
|
||
|
||
```c
|
||
static void log_state_i(const char *title, const char *detail)
|
||
{
|
||
ESP_LOGI(TAG, "【状态】%s：%s", title, detail ? detail : "-");
|
||
}
|
||
```
|
||
|
||
如需补充非 Mermaid 图，建议仅放一张关键串口日志截图（启动配网、连接中、成功/失败重试）。
|
||
|
||
---
|
||
|
||
## 六、常见问题与排障思路
|
||
|
||
### 问题 1：手机连上 AP 但页面不弹
|
||
|
||
排查：
|
||
|
||
- 手动访问 `http://192.168.4.1`
|
||
- 检查 DNS 劫持和门户探测路径是否启用
|
||
- 检查 HTTP 服务是否启动成功
|
||
|
||
### 问题 2：提交密码后长时间连接失败
|
||
|
||
排查：
|
||
|
||
- 是否先断开旧 STA
|
||
- 是否正确处理了连接超时和重试
|
||
- 失败原因是否上报到状态机和前端
|
||
|
||
### 问题 3：配网失败后无法恢复
|
||
|
||
排查：
|
||
|
||
- NVS 清除逻辑是否真正执行
|
||
- 内存态缓存是否同时清空
|
||
- 配网状态是否回到 `provisioning`
|
||
|
||
---
|
||
|
||
## 七、测试清单（可复用）
|
||
|
||
建议每次迭代最少覆盖：
|
||
|
||
1. 首次配网成功
|
||
2. 密码错误后重试成功
|
||
3. 连接旧网状态下切换新网成功
|
||
4. 清除配置后重新配网成功
|
||
5. 重启后自动重连
|
||
6. 空闲超时与手动停止路径可用
|
||
|
||
这 6 条通过后，组件稳定性通常会显著提升。
|
||
|
||
---
|
||
|
||
## 八、可继续增强的方向
|
||
|
||
- 配网页面安全增强（鉴权/会话）
|
||
- 多语言提示
|
||
- 更细粒度错误码映射
|
||
- BLE 辅助配网
|
||
- 命令行/远程维护接口联动
|
||
|
||
---
|
||
|
||
## 结语
|
||
|
||
配网组件的核心价值，不是“让设备连上一次网”，而是：
|
||
|
||
- 功能完整
|
||
- 异常可恢复
|
||
- 排障可落地
|
||
|
||
当这三件事做好后，它才是一个能复用、能维护、能上线的基础能力组件。 |