Wi-Fi 连接与配置模式

设备有两条途径获取网络密码：通过网页安装器经由数据线（Improv 协议），以及通过 Android 和 iOS 上的 iDryer 手机应用经由空中传输（ESPTouch v2 协议）。此后密码保存在 NVS 中，重启后依然保留。

负责这件事的是 EspTouchProvisioner（platform/arduino/）。产品侧无需调用任何东西，Link 会自行启动并驱动它；回调只用于在屏幕上显示配置进度。

协议版本之间并不兼容：应用必须发送 ESPTouch v2。第一版通过帧长度承载数据，而当路由器在 2.4 GHz 与 5 GHz 之间转发广播时，这些长度就会被破坏——共用同一名称的单个 mesh 网络因此时灵时不灵。

理解这套行为只有一个理由：设备应当在能够自行恢复时保持安静，只有在确实无能为力时才叫人。两个方向都容易出错——要么路由器每次打嗝都去打扰主人，要么带着错误密码默默离线挂着。

四个阶段

配置器**只存活到第一次成功连接为止**。在 Wi-Fi 尚未建立期间由 Link::loop() 调用它；第一次 WL_CONNECTED 之后，云端状态机接管，配置模式再也不会启动——直到下一次重启。

阶段 1. 启动，内存中已有密码

坚持模式，不做诊断。

每隔 kBootRetryMs（6 秒）发起一次新的连接尝试，持续 kConnectFallbackMs（90 秒）。连上了就开始工作；连不上就启动配置模式。

为什么不做诊断：密码并不新，它曾经是有效的。没有必要去分辨是信号弱还是密码被改了——如果在这段时间内没有连接，就叫主人来，他会当场处理。

为什么需要重试：WiFi.begin() 只在 Link::begin() 中调用一次。云端状态机在 WL_CONNECTED 之前并不运行，而 Arduino 的自动重连并不覆盖 reason 202 和 205。没有重试就只有一次尝试，信号弱时设备会带着完全有效的密码进入配置模式。

为什么是 90 秒——从最坏情况倒推，也就是来电后所有设备同时启动的场景：

• 最多 60 秒——路由器启动。Broadband Forum 的行业要求 TR-124 Issue 9 第 GEN.OPS.9 条：「The RG MUST complete power up in 60 seconds or less」。需要说明的是，该要求针对网关的完整启动，其中并没有单独规定 SSID 出现的时限。对量产设备的实测显示，从上电到开始广播需要 34–49 秒，因此 60 秒是合理的上界而非平均值；
• 加上我们自身的连接——通常 2–5 秒，但当 RSSI 在 −85 dBm 左右时会拉长到二十秒。

于是得到 90 秒：路由器六十秒，我们自己三十秒。更短会有在网络即将出现时把主人叫来的风险；明显更长则会让主人长时间盯着一台既没有连接也没有解释的设备。

同时上电的路由器与接入点是并行启动的，而不是先后启动，因此它们的时间不应相加。若采用更严格的标准——「客户端拿到地址并能访问互联网」——数字会来到 90–120 秒：那里还包含 WAN、DHCP 或 PPPoE 以及调制解调器同步。我们不需要等这些——设备只要进入本地网络就够了。

阶段 2. 启动，内存中没有密码

立即启动配置模式——没有什么可等的。

阶段 3. 刚刚收到密码

智能模式，driveConnect()。

此时密码是**新的，而且可能是错的**——主人可能打错了。因此配置器会区分失败的原因：

• 统计连续的认证失败次数（kAuthFailLimit，8 次）；
• 第五次之后扫描空中信号，记住最好的 RSSI；
• 如果 RSSI 比 kWeakRssi（−80 dBm）更差，则取消返回配置模式：同样的 reason 15 和 202 在密码正确但 auth 帧丢失时同样会出现，而连接可能需要几分钟。那里适用另一个期限——kWeakSignalGiveUpMs（10 分钟）；
• 在信号良好且连续失败八次的情况下返回配置模式：否则一个打字错误就只能靠重新刷写才能摆脱。

此外还有针对完全静默的看门狗（kWatchdogMs，20 秒）：既没有事件也没有连接时，用 esp_wifi_disconnect() 推一下协议栈。

阶段 4. 运行中连接断开

配置器不再被调用。连接由云端状态机静默恢复，配置模式不会启动——不去打扰主人。从设备的角度看，「路由器夜间被关掉」和「路由器被换掉了」无法区分，它也不会去猜。

如何告诉设备网络已经更换

重启它。

重启后进入阶段 1：旧密码不匹配，90 秒白白过去，配置模式启动——此时可以用手机发送新密码，或者插上数据线。没有任何启发式判断，就是普通的关机再开机。

一个特性：处于配置模式时不会自行接入网络

当设备正在侦听空中信号时，它**不会尝试连接**已保存的网络：射频被接收占用，连接尝试会一直暂停，直到收到新密码。

实际后果：如果路由器启动超过 90 秒而设备已经进入配置模式，那么即使网络之后出现，它也不会自行回到网络。要么发送密码，要么重启设备。

这是该模式的特性而非疏漏：无法一边侦听空中信号一边建立连接。

超时

常量	取值	作用
kBootRetryMs	6 秒	阶段 1 的重试间隔
kConnectFallbackMs	90 秒	叫主人之前尝试多久
kReconnectDelayMs	700 毫秒	断开后到下次尝试的暂停（阶段 3）
kWatchdogMs	20 秒	协议栈静默多久后被推一下
kAuthFailLimit	8	返回配置模式前的连续认证失败次数
kWeakRssi	−80 dBm	「信号弱」的界限
kWeakSignalGiveUpMs	10 分钟	信号弱时坚持多久才放弃
kRestartMs	10 分钟	始终收不到密码时重启配置模式

主人看到什么

进入配置模式会触发 Notice 回调：

• Listening——普通配置：内存中没有网络，或者连接此前已经成功过；
• CheckPassword——网络已配置，但一次也没让设备进入。剩下的唯一解释就是密码错误。

如何呈现由产品决定。在 idryer-touch 中这是一条全屏通知。