解决ESP8266/ESP32网络配置痛点：WiFiManager一站式解决方案-CSDN博客

解决ESP8266/ESP32网络配置痛点：WiFiManager一站式解决方案

【免费下载链接】WiFiManager ESP8266 WiFi Connection manager with web captive portal 项目地址: https://gitcode.com/gh_mirrors/wi/WiFiManager

你是否还在为ESP8266/ESP32设备的网络配置烦恼？每次更换WiFi环境都要重新烧录固件？本文将介绍WiFiManager——一个专为解决这些问题设计的开源库，只需简单几步，即可实现设备的自动网络配置，让你的物联网项目部署效率提升10倍。读完本文，你将掌握WiFiManager的基本使用方法、高级功能配置以及实际应用场景，彻底告别繁琐的硬编码网络配置。

什么是WiFiManager？

WiFiManager是一个针对ESP8266和ESP32开发板的WiFi连接管理库，它提供了一个自动连接已知WiFi网络的功能，当连接失败时，会自动创建一个配置门户（Captive Portal），允许用户通过网页界面轻松配置新的WiFi网络。这种"先尝试连接，失败则创建配置门户"的机制，完美解决了物联网设备的网络配置难题。

WiFiManager的核心优势在于：

无需硬编码WiFi凭据，设备部署更灵活
自动创建配置门户，支持手机、电脑等多种设备访问
支持自定义参数配置，满足复杂项目需求
轻量级设计，对资源占用小
同时支持ESP8266和ESP32平台

官方文档：README.md

工作原理

WiFiManager的工作流程设计得非常巧妙，既保证了设备的自动连接能力，又提供了灵活的配置方式：

mermaid

当设备启动时，WiFiManager首先会检查是否有保存的WiFi凭据。如果有，它会尝试连接到这些网络；如果连接成功，设备就会正常启动应用程序。如果连接失败（例如密码错误或网络不可用），或者没有保存的凭据，WiFiManager会自动将设备切换到AP模式，创建一个名为"AutoConnectAP"的WiFi热点，并启动一个Web服务器和DNS服务器。

当用户的设备连接到这个热点后，会被自动重定向到配置门户（通常是192.168.4.1），在这里用户可以选择附近的WiFi网络并输入密码。配置完成后，设备会保存这些凭据并重启，然后尝试连接到新配置的网络。

快速开始：5分钟上手WiFiManager

安装方法

WiFiManager支持多种安装方式，选择最适合你的方式：

Arduino库管理器安装（推荐）

打开Arduino IDE
点击「工具」>「管理库...」
在搜索框中输入"WiFiManager"
选择最新版本并点击「安装」

手动安装

从GitCode仓库克隆或下载库文件：

git clone https://gitcode.com/gh_mirrors/wi/WiFiManager.git

然后将下载的文件夹复制到Arduino的libraries文件夹中。

PlatformIO安装

在platformio.ini文件中添加：

[env]
lib_deps = WiFiManager

基础示例代码

WiFiManager的使用非常简单，以下是一个基本示例：

#include <WiFiManager.h> // 引入WiFiManager库

void setup() {
  Serial.begin(115200);
  
  // 创建WiFiManager实例
  WiFiManager wm;
  
  // 自动连接WiFi，如果失败则启动配置门户
  // 参数1: AP名称，参数2: AP密码（可选）
  bool res = wm.autoConnect("MyESPDevice", "password123");
  
  if(!res) {
    Serial.println("WiFi连接失败，重启设备...");
    ESP.restart();
  } 
  else {
    // 连接成功，打印IP地址
    Serial.println("WiFi连接成功!");
    Serial.print("IP地址: ");
    Serial.println(WiFi.localIP());
  }
}

void loop() {
  // 你的应用代码
}

完整示例代码：examples/Basic/Basic.ino

高级功能详解

按需配置门户

除了自动启动配置门户外，WiFiManager还支持按需启动，例如通过按键触发。这种方式特别适合需要在设备运行过程中重新配置网络的场景。

#include <WiFiManager.h>

// 定义触发引脚（例如连接到GND的按键）
#define TRIGGER_PIN 0

void setup() {
  Serial.begin(115200);
  pinMode(TRIGGER_PIN, INPUT_PULLUP);
  WiFi.mode(WIFI_STA); // 设置为STA模式
}

void loop() {
  // 当触发引脚被拉低时启动配置门户
  if (digitalRead(TRIGGER_PIN) == LOW) {
    WiFiManager wm;
    
    // 设置配置门户超时时间（秒）
    wm.setConfigPortalTimeout(120);
    
    // 启动配置门户
    if (!wm.startConfigPortal("OnDemandAP")) {
      Serial.println("配置超时或用户退出");
      delay(3000);
      ESP.restart();
    }
    
    // 配置成功，打印连接信息
    Serial.println("WiFi配置成功!");
    Serial.print("IP地址: ");
    Serial.println(WiFi.localIP());
  }
  
  // 你的应用代码
}

完整示例代码：examples/OnDemand/OnDemandConfigPortal/OnDemandConfigPortal.ino

自定义配置参数

WiFiManager不仅可以配置WiFi凭据，还支持添加自定义参数，例如MQTT服务器地址、设备名称等。这使得它成为一个完整的设备配置解决方案。

#include <WiFiManager.h>

// 定义自定义参数
WiFiManagerParameter custom_mqtt_server("server", "MQTT服务器", "mqtt.example.com", 40);
WiFiManagerParameter custom_mqtt_port("port", "MQTT端口", "1883", 6);
WiFiManagerParameter custom_device_name("name", "设备名称", "MyESP8266", 20);

void setup() {
  Serial.begin(115200);
  
  WiFiManager wm;
  
  // 添加自定义参数到配置门户
  wm.addParameter(&custom_mqtt_server);
  wm.addParameter(&custom_mqtt_port);
  wm.addParameter(&custom_device_name);
  
  // 自动连接或启动配置门户
  if (!wm.autoConnect("ConfigPortal")) {
    Serial.println("配置失败，重启设备");
    ESP.restart();
  }
  
  // 获取并打印自定义参数值
  Serial.println("配置成功!");
  Serial.print("MQTT服务器: ");
  Serial.println(custom_mqtt_server.getValue());
  Serial.print("MQTT端口: ");
  Serial.println(custom_mqtt_port.getValue());
  Serial.print("设备名称: ");
  Serial.println(custom_device_name.getValue());
}

void loop() {
  // 你的应用代码
}

配置门户自定义

WiFiManager允许你自定义配置门户的外观和行为，例如修改HTML模板、添加自定义CSS等。

配置门户的HTML模板位于：extras/WiFiManager.template.html

你可以通过以下方法自定义页面样式：

// 添加自定义CSS
wm.setCustomHeadElement("<style>h1 { color: #ff0000; }</style>");

// 使用深色主题
wm.setClass("invert");

// 显示信号强度百分比而非图标
wm.setScanDispPerc(true);

回调函数

WiFiManager提供了多种回调函数，允许你在特定事件发生时执行自定义代码：

// 配置模式启动时的回调
void configModeCallback (WiFiManager *myWiFiManager) {
  Serial.println("进入配置模式");
  Serial.println("配置门户SSID: " + myWiFiManager->getConfigPortalSSID());
  Serial.println("配置门户IP: " + WiFi.softAPIP().toString());
}

// 保存配置时的回调
void saveConfigCallback () {
  Serial.println("应保存配置");
  // 在这里保存你的自定义参数
}

void setup() {
  // ...
  
  // 设置回调函数
  wm.setAPCallback(configModeCallback);
  wm.setSaveConfigCallback(saveConfigCallback);
  
  // ...
}

实际应用场景

智能家居设备

对于智能家居设备，WiFiManager可以让用户轻松配置设备连接到家庭WiFi网络，无需任何编程知识。设备首次启动时自动进入配置模式，用户通过手机连接后即可完成设置。

工业监控设备

在工业环境中，设备可能需要安装在没有显示器和键盘的位置。WiFiManager允许维护人员通过简单的按键操作，临时启动配置门户，快速更改网络设置。

公共场所部署

对于需要在不同地点部署的设备（如展览、会议等），WiFiManager可以大大简化部署流程，技术人员无需为每个设备单独配置网络。

电池供电设备

对于电池供电的低功耗设备，可以使用setConfigPortalTimeout()方法设置配置超时时间，确保在用户未配置时设备能及时进入休眠模式，节省电量。

// 设置配置门户超时时间为180秒（3分钟）
wm.setConfigPortalTimeout(180);

常见问题解决

配置门户无法打开

如果连接到配置门户后无法打开网页，请尝试以下解决方法：

确保已正确连接到设备创建的WiFi热点
手动在浏览器中输入配置门户IP：192.168.4.1
尝试使用不同的浏览器或设备
检查是否有防火墙或安全软件阻止了连接

设备无法保存WiFi凭据

如果设备在配置后仍然无法记住WiFi凭据：

确保没有调用wm.resetSettings()方法（该方法会清除保存的凭据）
检查ESP8266/ESP32的NVS（非易失性存储）是否正常工作
尝试在代码中添加WiFi.persistent(true);

连接不稳定或频繁断开

若WiFi连接不稳定：

尝试增加连接超时时间：wm.setConnectTimeout(60);
确保使用的WiFiManager版本与ESP8266/ESP32内核版本兼容
检查电源供应是否稳定，WiFi模块对电源波动比较敏感

自定义参数不生效

如果添加的自定义参数没有出现在配置页面：

确保在autoConnect()或startConfigPortal()之前添加了参数
检查参数变量是否声明为全局变量（非局部变量）
确保参数ID只包含字母、数字和下划线

总结

WiFiManager为ESP8266和ESP32设备提供了一个优雅的WiFi配置解决方案，它彻底改变了物联网设备的网络配置方式，使得"开箱即用"成为可能。无论是简单的家庭项目还是复杂的工业应用，WiFiManager都能大大简化设备的部署和维护过程。

通过本文介绍的基础使用、高级功能和实际应用场景，你应该已经掌握了WiFiManager的核心用法。想要了解更多细节，可以查阅官方文档和示例代码：

项目主页：gh_mirrors/wi/WiFiManager
示例代码：examples/
模板文件：extras/WiFiManager.template.html

WiFiManager是一个活跃的开源项目，欢迎通过贡献代码、报告问题或提供建议来参与项目开发！

如果你觉得本文对你有帮助，请点赞、收藏并分享给更多开发者，关注我们获取更多物联网开发技巧！

【免费下载链接】WiFiManager ESP8266 WiFi Connection manager with web captive portal 项目地址: https://gitcode.com/gh_mirrors/wi/WiFiManager

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考