wangbeihong/BotanicalBuddy

Fork 0

Files

Wang Beihong 6782af2d4a feat: 添加 console_user_cmds 组件，提供用户命令支持

2026-03-06 13:21:11 +08:00

9.0 KiB

Raw Blame History

ESP32 配网组件设计实践：聚焦功能与实现，而不是项目绑定

很多 ESP32 设备在开发阶段都把“配网”当成一个小功能，但真正落地后会发现：

用户第一次接入要顺畅
失败后要能恢复
日志要便于现场排障

这篇文章只讲配网组件本身，聚焦能力设计和实现思路，不依赖具体业务项目。

一、目标能力定义

一个可落地的配网组件，建议至少包含以下能力：

按键触发配网
常驻配网模式（可选）
SoftAP + Web Portal 配网
DNS 劫持与常见 Captive Portal 兼容
凭据持久化（NVS）与重启自动重连
清除历史配置（API + Web）
状态机与可读日志

这几项组合起来，才能覆盖“首次成功 + 失败恢复 + 现场维护”三个关键场景。

图示（整体功能目标关联）：

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

二、组件架构（通用）

[按键任务] --> [进入配网]
			   |
			   +--> 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

图示（状态机）：

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 设计建议

推荐保持“少而稳”的接口：

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 提供失败恢复通道

可以展示一段“典型调用顺序”代码：

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 生命周期时序）：

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 到配网页

这样手机系统弹门户页面成功率会明显提高。

示例代码（伪代码）：

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 重定向路径）：

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()，并对异常返回做日志记录。

示例代码：

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
页面按钮：清除已保存

这样现场人员无需改固件即可恢复设备。

建议把清除动作写成“存储层 + 运行态”两段：

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）：

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=...
【状态】连接失败：原因=...

这样做的收益是：

开发调试快
测试可直接定位阶段
现场人员无需先理解底层驱动日志

可展示一个统一日志函数风格：

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

七、测试清单（可复用）

建议每次迭代最少覆盖：

首次配网成功
密码错误后重试成功
连接旧网状态下切换新网成功
清除配置后重新配网成功
重启后自动重连
空闲超时与手动停止路径可用

这 6 条通过后，组件稳定性通常会显著提升。

八、可继续增强的方向

配网页面安全增强（鉴权/会话）
多语言提示
更细粒度错误码映射
BLE 辅助配网
命令行/远程维护接口联动

结语

配网组件的核心价值，不是“让设备连上一次网”，而是：

功能完整
异常可恢复
排障可落地

当这三件事做好后，它才是一个能复用、能维护、能上线的基础能力组件。

9.0 KiB Raw Blame History Unescape Escape