tzapu / WiFiManager安装和配置详细教程WiFiManager 开发版本 Espressif ESPx的

开发版本

Espressif ESPx的WiFi连接管理器与回退的网络配置门户

⚠️本文档已过期，见下面的注释

会员对会员支持/聊天

该配置门户是俘虏式的，所以在各种设备上，只要你连接到创建的接入点，它就会出现配置对话。

这适用于ESP8266 Arduino平台

github.com/esp8266/Ard…

这适用于ESP32 Arduino平台

github.com/espressif/a…

已知问题

文档需要更新，见#500

内容

它是如何工作的

当你的ESP启动时，它会将其设置为站模式，并尝试连接到先前保存的接入点。
如果不成功（或没有保存先前的网络），它会将ESP移动到接入点模式，并启动DNS和Web服务器（默认IP 192.168.4.1）。
使用任何带有浏览器的wifi设备（电脑、手机、平板电脑）连接到新创建的接入点。
因为有了专属门户和DNS服务器，你会收到一个 "加入网络 "类型的弹出窗口，或者你试图访问的任何域都会被重定向到配置门户。
选择一个被扫描的接入点，输入密码，点击保存。
ESP将尝试进行连接。如果成功，它将控制权交还给你的应用程序。如果不成功，则重新连接到接入点并重新配置。
有一些选项可以改变这种行为，或者手动启动独立的配置门户和网络门户，以及以非阻塞模式运行它们。

它看起来如何

希望列表

删除对EEPROM库的依赖
将HTML字符串移至PROGMEM
清理和精简代码（尽管这正在进行）。
如果设置了超时，在AP模式下获取页面时延长超时时间
增加配置比ssid/password更多参数的能力
也许允许在重启后设置ESP的IP
添加到Arduino库管理器
添加到PlatformIO
增加多套网络凭证
允许用户自定义CSS
根据方案/目标，重写文档，使之简单化

开发

支持ESP32
依靠SDK内置的自动连接功能，而不是强制进行连接
增加非阻塞模式
轻松定制字符串
支持主机名
修复各种错误和esp SDK问题的解决方法
增加信息页项目
最后状态显示/失败原因
可定制的菜单
单独的自定义参数页面
随需应变的网络门户
完全重构代码以分割功能
wiif扫描图标或百分比显示
为黑暗模式反转类
更多的模板标记
所有字符串的内存
新的回调
新的呼出/过滤器
共享网络服务器实例
最新的esp idf/sdk支持
wm现在是非持久性的，不会擦除或改变esp8266上存储的esp配置
大量的调试输出/水平
禁用captiveportal
预先加载wiifscans，加快页面加载速度
在没有连接的情况下，softap的稳定性得到了修复。

快速入门

安装

你可以通过Arduino库管理器进行安装，也可以从github上查看最新的修改或发布。

通过库管理器安装

目前0.8+版本适用于2.4.0版或更新的Arduino的ESP8266核心。

在Arduino IDE中找到Sketch/Include Library/Manage Libraries
搜索WiFiManager
点击安装并开始使用它

从github签出

Github版本适用于2.4.0版或更新的Arduino的ESP8266核心。

签出库到你的Arduino库文件夹中

使用

包含在你的草图中

#include <WiFiManager.h>          //https://github.com/tzapu/WiFiManager WiFi Configuration Magic

初始化库，在你的设置函数中添加，注意如果你使用非阻塞，你将确保你在全局范围内创建这个，或者适当地处理，如果在设置和使用非阻塞模式，它将不会工作。

WiFiManager wifiManager;

同样在设置函数中添加

//first parameter is name of access point, second is the password
wifiManager.autoConnect("AP-NAME", "AP-PASSWORD");

如果你只是想要一个不安全的接入点

wifiManager.autoConnect("AP-NAME");

或者如果你想使用从 "ESP "自动生成的名称和esp的芯片ID，请使用

wifiManager.autoConnect();

在你写完你的草图并启动ESP后，它将尝试连接到WiFi。如果它失败了，它就会以接入点模式启动。在AP模式下，连接到它，然后打开浏览器到网关IP，默认192.168.4.1，配置wifi，保存，它应该重新启动并连接。

也请看例子。

使用PlatformIO安装

PlatformIO是一个新兴的物联网开发生态系统，是使用Arduino IDE的一个替代方案。使用编辑器中的platformio库管理器安装WiFiManager ，或使用PlatformIO核心CLI，或通过添加到你的platformio.ini ，如下图所示（推荐方法）。

最简单的方法是在你的项目根部打开platformio.ini 文件，WifiManager 到公共顶层的envlib_deps 键，像这样。

[env]
lib_deps =
	WiFiManager

[env]
lib_deps =
	https://github.com/tzapu/WiFiManager.git

文件

密码保护配置的接入点

你可以而且应该用密码保护配置访问点。只需将密码作为第二个参数加入到autoConnect 。一个短的密码似乎有不可预测的结果，所以使用一个大约8个字符或更多长度的密码。指导原则是，wifi密码必须由8到63个ASCII编码的字符组成，范围在32到126（十进制）。

wifiManager.setAPCallback(configModeCallback);

回调

进入配置模式

如果你需要在你的设备在WiFi连接尝试失败后进入配置模式时做一些事情，就使用这个。在autoConnect()

wifiManager.setAPCallback(configModeCallback);

configModeCallback 声明和例子

void configModeCallback (WiFiManager *myWiFiManager) {
  Serial.println("Entered config mode");
  Serial.println(WiFi.softAPIP());

  Serial.println(myWiFiManager->getConfigPortalSSID());
}

保存设置

当自定义参数被设置并且连接已经建立时，它会被调用。用它来设置一个标志，所以当所有的配置完成后，你可以在某个地方保存额外的参数。

如果你需要保存参数，即使在WIFI失败或空闲时，你必须将setBreakAfterConfig ，否则saveConfigCallback将不会被调用。

//if this is set, it will exit after config, even if connection is unsuccessful.
    void          setBreakAfterConfig(boolean shouldBreak);

参见AutoConnectWithFSParameters示例。

wifiManager.setSaveConfigCallback(saveConfigCallback);

saveConfigCallback 声明和例子

//flag for saving data
bool shouldSaveConfig = false;

//callback notifying us of the need to save config
void saveConfigCallback () {
  Serial.println("Should save config");
  shouldSaveConfig = true;
}

配置门户超时

如果你需要设置一个超时，这样ESP就不会挂起等待配置，例如在停电后，你可以添加

wifiManager.setConfigPortalTimeout(180);

这将等待3分钟（180秒）。当时间过去后，无论结果如何，自动连接功能都会返回。检查连接情况，如果仍然没有建立，做任何需要的事情（在一些模块上，我重新启动它们来重试，在其他模块上，我进入深度睡眠状态）

按需配置门户

如果你希望按需启动配置门户，而不是在连接失败时自动启动，那么这是为你准备的。

你需要使用startConfigPortal() ，而不是调用为你做所有连接和故障转移配置门户设置的autoConnect() 。请不要使用BOTH。

使用实例

void loop() {
  // is configuration portal requested?
  if ( digitalRead(TRIGGER_PIN) == LOW ) {
    WiFiManager wifiManager;
    wifiManager.startConfigPortal("OnDemandAP");
    Serial.println("connected...yeey :)");
  }
}

更复杂的版本见示例。OnDemandConfigPortal

从配置门户中退出

通常，一旦进入，配置门户将继续循环，直到WiFi凭证被成功输入或达到超时。如果你希望在不加入WiFi网络的情况下退出，比如说因为你要把ESP放入AP模式，那么请按主网页上的 "退出 "按钮。如果通过autoConnect 或startConfigPortal 启动，那么它将返回false (portalAbortResult)

自定义参数

你可以使用WiFiManager来收集更多的参数，而不仅仅是SSID和密码。这对配置MQTT主机和端口、blynk或emoncms令牌等东西可能很有帮助，仅举几例。你要负责保存和加载这些自定义值。这个库只是为你收集和显示这些数据，作为一种方便。使用场景是。

从某个地方（EEPROM/FS）加载数值或生成一些默认值
将自定义参数添加到WiFiManager中，使用

  // id/name, placeholder/prompt, default, length
 WiFiManagerParameter custom_mqtt_server("server", "mqtt server", mqtt_server, 40);
 wifiManager.addParameter(&custom_mqtt_server);

如果与AP的连接失败，配置门户启动，你可以设置/更改值（或使用按需配置门户）
一旦配置完成并且建立了连接，就会调用保存配置回调()。
一旦WiFiManager将控制权返回给你的应用程序，使用WiFiManagerParameter 对象读取和保存新值。

 mqtt_server = custom_mqtt_server.getValue();

这个功能比其他所有的功能都要复杂得多，所以这里有一些例子来充分展示它是如何完成的。你也应该看一看在你的表单中添加自定义HTML。

以json形式保存和加载自定义参数到文件系统AutoConnectWithFSParameters
保存和加载自定义参数到EEPROM（还没有完成）

自定义IP配置

你可以为AP（接入点，配置模式）和STA（站台模式，客户端模式，正常项目状态）设置一个自定义IP

自定义接入点IP配置

如果你需要/希望有这样的功能，这将把你的俘虏式门户设置为一个特定的IP。之前添加以下片段autoConnect()

//set custom ip for portal
wifiManager.setAPStaticIPConfig(IPAddress(10,0,1,1), IPAddress(10,0,1,1), IPAddress(255,255,255,0));

自定义站（客户端）静态IP配置

这将使用指定的IP配置，而不是在站点模式下使用DHCP。

wifiManager.setSTAStaticIPConfig(IPAddress(192,168,0,99), IPAddress(192,168,0,1), IPAddress(255,255,255,0)); // optional DNS 4th argument

在例子文件夹中有几个例子，告诉你如何设置静态IP，甚至如何通过Web配置门户进行配置。

注意：如果你有带主机名的HTTP请求或同步化时间（NTP），你应该填入DNS服务器。这与网关ip或一个流行的（谷歌DNS：8.8.8.8）是一样的。

自定义HTML、CSS、Javascript

有多种方法可以将自定义HTML、CSS或Javascript注入到配置门户中。这些选项是。

inject custom head element 你可以用它来给配置门户的头部注入任何html位。如果你添加一个<style> 元素，请记住它将覆盖所包含的css，而不是替换。

wifiManager.setCustomHeadElement("<style>html{filter: invert(100%); -webkit-filter: invert(100%);}</style>");

在配置/参数表格中注入一个自定义的HTML位

WiFiManagerParameter custom_text("<p>This is just a text paragraph</p>");
wifiManager.addParameter(&custom_text);

在配置表格元素中注入一个自定义的html位，只需将你想要添加的位作为最后一个参数添加到自定义参数构造器中。

WiFiManagerParameter

命名

你可以用一些内置的类来定制默认模板的某些元素

WiFiManagerParameter custom_mqtt_server("server", "mqtt server", "iot.eclipse", 40, " readonly");
wifiManager.addParameter(&custom_mqtt_server);

在css中还有一些额外的类，你可以在你的自定义html中使用，见模板示例。

过滤网络

你可以根据信号质量过滤网络，显示/隐藏重复的网络。

如果你想过滤低信号质量的网络，你可以告诉WiFiManager不显示低于任意质量%的网络。

wifiManager.setClass("invert"); // dark theme
wifiManager.setScanDispPerc(true); // display percentages instead of graphs for RSSI

将不显示低于10%信号质量的网络。如果你省略该参数，则默认为8%。

你还可以删除或显示重复的网络（默认为删除）。使用这个函数来显示（或隐藏）所有的网络。

wifiManager.setMinimumSignalQuality(10);

调试

在非稳定版本的Serial ，调试是默认启用的。要在自动连接/启动ConfigPortal之前禁用添加

wifiManager.setDebugOutput(false);

你可以通过构造函数传入一个自定义流

WiFiManager wifiManager(Serial1);

你可以通过改变源选项中的_debugLevel ，自定义调试级别。

DEBUG_ERROR
DEBUG_NOTIFY
DEBUG_VERBOSE
DEBUG_DEV
DEBUG_MAX

疑难解答

如果你遇到编译错误，通常情况下，你可能需要为Arduino安装一个新版本的ESP8266内核。

在0.8版本上添加的变化应该可以使最新的主干部分在没有编译错误的情况下工作。测试下来，ESP8266核心2.0.0。请更新到0.8版本

我正在努力使发布的版本与核心的发布版本一起工作，所以它们可以通过板卡管理器安装，但如果你直接从github检查最新版本，有时，只有当你将ESP8266核心更新到最新版本时，库才能工作，因为我正在使用一些新添加的功能。

如果你连接到创建的配置接入点，但配置门户没有显示出来，只要打开浏览器，输入网络门户的IP，默认为192.168.4.1 。

如果尝试连接的结果是无休止的循环，可以尝试在autoConnect(); 之前添加setConnectTimeout(60) 。参数是尝试连接的超时，单位是秒。

当停电或调制解调器复位时，我被卡在ap模式中，可以试试setConfigPortalTimeout(seconds)。这将导致configportal在没有活动后关闭，你可以在你的代码中重新启动或尝试重新连接。

发布

1.0.1 开发概述

增加了公共方法

setConfigPortalBlocking

setShowStaticFields

setCaptivePortalEnable

setRestorePersistent

setCaptivePortalClientCheck

setWebPortalClientCheck

startWebPortal

stopWebPortal

process

disconnect

erase

debugSoftAPConfig

debugPlatformInfo

setScanDispPerc

setHostname

setMenu(menu_page_t[])

setWiFiAutoReconnect

setSTAStaticIPConfig(..,dns)

setShowDnsFields

getLastConxResult

getWLStatusString

getModeString

getWiFiIsSaved

setShowInfoErase

setEnableConfigPortal

setCountry

setClass

htmleEtities

WiFiManagerParameter

WiFiManagerParameter(id,label)

WiFiManagerParameter.setValue(value,length)

getParameters

getParametersCount

构造函数

WiFiManager(Stream& consolePort)

定义标志

❗️定义不能在用户草图中设置 #define WM_MDNS // use MDNS

#define WM_FIXERASECONFIG // use erase flash fix, esp8266 2.4.0

#define WM_ERASE_NVS // esp32 erase(true) will erase NVS

#include <rom/rtc.h> // esp32 info page will show last reset reasons if this file is included

变化概述

支持ESP32（相当稳定）
完全重构了字符串strings_en.h
为wifiscan添加了新的标记，以及一些类（左，反转图标，MSG颜色）。
增加了状态呼出面板的默认颜色、主要颜色、特殊颜色
在信息页上增加了大量的信息，以及擦除功能
增加了信号图标，取代了百分比（有悬停标题）。
为所有输入添加标签（取代占位符）
所有的HTML（以及最终所有的字符串，除调试外）都被移至strings_en.h
增加了额外的调试功能，压缩了调试行，调试级别
持久性禁用，并通过 de/con-stuctor 恢复（使用setRestorePersistent)
应该保留所有的用户模式，包括AP，不应该覆盖或保留用户模式或配置，甚至STA (storeSTAmode) (BUGGY)
⚠️返回值可能已经改变，取决于门户中止，或超时 (portalTimeoutResult,portalAbortResult)
params的内存在超出时由WIFI_MANAGER_MAX_PARAMS(5) 的增量自动分配，用户不再需要指定这个。
addparameter现在返回bool，如果参数ID不是字母[0-9,A-Z,a-z,_]则返回false。
param字段ids允许{I}标记使用param_n而不是string，以防有人因i18n或字符问题而想改变它。
提供#DEFINE FIXERASECONFIG ，帮助处理esp8266/Arduino#3635的问题。
在门户网站上报告故障原因
设置esp8266 sta主机名，esp32 sta+ap主机名（DHCP客户端ID）。
在构造函数WiFiManager(Stream& consolePort)中传入调试流。
如果你设置_disableIpFields=true，你可以用showxfields(false)强制关闭ip区域。
param menu/page (setup) 被添加到wifi页面的独立参数中，由setMenu自动处理。
设置自定义根菜单
在自动连接时禁用配置入口
wm参数init现在是受保护的，允许子类，包括例子。
wifiscans是预存的和异步的，以加快页面加载速度，刷新会强制重新扫描
增加了esp32 gettemperature（目前已被注释，只对相对测量有用）。

0.12

删除了204头的响应
修正了与其他使用 isnan 和其他没有命名空间的 std::函数的lib的不兼容问题

0.11

更加可靠地重新连接到网络
自定义参数中的自定义HTML（对于只读参数）。
自定义参数表格中的自定义HTML（如标签）
自定义标题元素（像自定义css）。
基于信号质量的网络排序
删除重复的网络

0.10

一些css变化
错误修复和速度改进
增加了用于调试的 waitForConnectResult() 的替代方法
将setTimeout(seconds) 改为setConfigPortalTimeout(seconds)

贡献和感谢

我从社区得到的支持和帮助是非常惊人的。我不知道怎么感谢你们才好。这是我第一次真正尝试开发开源的东西，我必须说，现在我明白了为什么人们如此专注于此，这是因为所有参与的人都很出色。

tzapu / WiFiManager安装和配置详细教程