尧图网站建设 
ESP-IDF Wi-Fi Station 场景完全指南从初始化、扫描到连接与原因代码解析【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本指南基于乐鑫 ESP-IDF 官方文档 Station 场景系统讲解 ESP32 系列芯片作为 Wi-Fi Station站点时的完整生命周期——包括 Wi-Fi/LwIP 初始化、配置、启动、连接、获取 IP、断开、IP 更改与清理八个阶段深入剖析 Wi-Fi 扫描的六种类型与八种组合方式、扫描配置参数、连接过程中各阶段的事件与原因代码并给出可落地的重连策略与工程实践建议。读完本文你将能够基于 ESP-IDF 正确编写 station 模式的连接逻辑、事件处理与扫描程序并能依据WIFI_EVENT_STA_DISCONNECTED携带的原因代码快速定位故障。一、Station 通用场景总览八阶段生命周期在 station 模式下一个完整的 Wi-Fi 应用生命周期包含八个阶段初始化、配置、启动、连接、获取 IP、断开、IP 更改与清理。这些阶段由四个关键任务协作完成Main task主任务负责调用初始化、配置、启动类 APIApp task应用程序任务承载业务逻辑例如创建套接字、发起连接、执行重连Event task事件任务由esp_event_loop_create()创建负责接收并分发各类 Wi-Fi/IP 事件LwIP taskLwIP 任务由esp_netif_init()创建负责 TCP/IP 协议栈相关工作。上图对应的 seqdiag 源码位于 station-scenarios.rst展示了上述任务之间在初始化、配置、启动、连接、获取 IP、断开、IP 更改、清理八个阶段的交互时序是理解 station 编程模型的核心参考。下文将逐一展开每个阶段的标准做法、事件流转与易错点。二、Wi-Fi/LwIP 初始化阶段阶段 1初始化阶段共 5 个步骤推荐按如下顺序执行顺序并非强制步骤动作关键 APIs1.1创建 LwIP 核心任务并初始化 TCP/IP 相关工作esp_netif_init()s1.2创建系统事件任务并注册事件回调esp_event_loop_create()s1.3创建绑定 station/AP 的默认网络接口实例esp_netif_create_default_wifi_sta()/esp_netif_create_default_wifi_ap()s1.4创建 Wi-Fi 驱动程序任务并初始化驱动esp_wifi_init()s1.5通过 OS API 创建应用程序任务xTaskCreate()等关键说明s1.1 中esp_netif_init()会创建一个 LwIP 核心任务事件回调在 s1.2 中初始化此回调的唯一动作通常是将事件中继到应用程序任务。s1.3 中esp_netif_create_default_wifi_sta()创建带 TCP/IP 协议栈的默认 station 网络接口实例其实现位于 esp_wifi_default.h。推荐顺序并不强制你可以在 s1.1 之前先创建应用程序任务并在该任务中完成其余全部初始化。但若应用程序任务依赖套接字过早创建任务可能不适用——此时应等收到 IP 之后再创建任务。三、Wi-Fi 配置阶段阶段 2Wi-Fi 驱动初始化成功后进入配置阶段。station 场景下首先要将模式配置为 stationesp_wifi_set_mode(WIFI_MODE_STA);之后可通过其他esp_wifi_set_xxxAPI 进行更多设置例如协议模式esp_wifi_set_protocol()、国家代码esp_wifi_set_country()、带宽等。重要约束配置应在建立连接之前完成但这并非强制——只要驱动已成功初始化可在任意阶段配置。若连接建立后不再更改配置务必先在连接前配置完毕。因为调用配置类 API如esp_wifi_set_protocol()会导致 Wi-Fi 连接断开带来不便。若 menuconfig 已使能 Wi-Fi NVS flashCONFIG_ESP_WIFI_NVS_ENABLED当前及后续的 Wi-Fi 配置信息都会存储至 NVS flash。这样上电/重启时无需从头配置 Wi-Fi 驱动只需调用esp_wifi_get_xxx系列 API 获取此前存储的配置。若不想沿用旧配置也可重新配置。四、Wi-Fi 启动阶段阶段 3s3.1调用esp_wifi_start()声明见 esp_wifi.h启动 Wi-Fi 驱动。s3.2驱动向事件任务发布WIFI_EVENT_STA_START事件事件任务执行常规处理后调用应用程序的事件回调。s3.3应用程序的事件回调将事件中继到应用程序任务。推荐在此事件发生后调用esp_wifi_connect()发起连接也可以等待其他时机再调用。五、Wi-Fi 连接阶段阶段 4s4.1调用esp_wifi_connect()声明见 esp_wifi.h后驱动启动内部扫描/连接过程。s4.2若内部扫描/连接成功产生WIFI_EVENT_STA_CONNECTED事件事件任务随即启动 DHCP 客户端服务触发 DHCP 流程。s4.3事件回调将WIFI_EVENT_STA_CONNECTED中继到应用程序任务。通常应用无需特别操作可执行打印日志等任意动作。易失败点s4.2 中连接可能因密码错误、未找到 AP 等原因失败此时会触发WIFI_EVENT_STA_DISCONNECTED事件并携带错误原因代码详见下文「Wi-Fi 原因代码」章节。六、Wi-Fi 获取 IP 阶段阶段 5s5.1DHCP 客户端初始化完成后进入获取 IP阶段。s5.2成功从 DHCP 服务器收到 IP 后触发IP_EVENT_STA_GOT_IP事件事件任务执行正常处理。s5.3事件回调将IP_EVENT_STA_GOT_IP中继到应用程序任务。这是基于 LwIP 构建的应用程序最关键的信号——它意味着应用已就绪可以开始创建 TCP/UDP 套接字等操作。⚠️常见错误在收到IP_EVENT_STA_GOT_IP之前就初始化套接字。切忌在接收到 IP 之前启动任何套接字相关操作。七、Wi-Fi 断开阶段阶段 6s6.1因 AP 掉电、RSSI 较弱等原因连接中断时产生WIFI_EVENT_STA_DISCONNECTED事件该事件也可能在阶段 3 就发生。此时事件任务会通知 LwIP 任务清除/移除所有 UDP/TCP 连接所有应用程序套接字进入错误状态——断开事件发生时任何套接字都无法正常工作。s6.2事件回调将事件中继到应用程序任务。推荐调用esp_wifi_connect()重新连接同时关闭所有套接字并在必要时重新创建。八、Wi-Fi IP 更改阶段阶段 7s7.1IP 地址发生更改时再次触发IP_EVENT_STA_GOT_IP事件此时事件中的ip_change字段为true。s7.2此事件对应用程序至关重要。事件发生时适合关闭所有已创建的套接字并重新创建。九、Wi-Fi 清理阶段阶段 8按顺序调用以下 API 完成清理esp_wifi_disconnect(); // s8.1 断开 Wi-Fi 连接 esp_wifi_stop(); // s8.2 终止 Wi-Fi 驱动见 esp_wifi.h L458 esp_wifi_deinit(); // s8.3 清理 Wi-Fi 驱动见 esp_wifi.h L400十、Wi-Fi 扫描类型、组合与配置esp_wifi_scan_start()声明见 esp_wifi.h目前仅支持 station 模式或 station/AP 共存模式。10.1 六种扫描类型模式描述主动扫描通过发送 probe request 进行扫描默认扫描模式被动扫描不发送 probe request跳至特定信道等待 beacon通过wifi_scan_config_t的scan_type字段使能前端扫描station 模式且 Wi-Fi 未连接时可进行由 Wi-Fi 驱动决定应用程序无法配置后端扫描station 模式或 station/AP 共存模式下 Wi-Fi 已连接时可进行同样由驱动决定全信道扫描扫描所有信道wifi_scan_config_t的channel字段为 0 时生效特定信道扫描仅扫描特定信道channel字段为 1–14 时生效以上类型可任意组合共 8 种扫描方式全信道/特定信道 × 前端/后端 × 主动/被动。10.2 扫描配置结构体wifi_scan_config_t扫描类型与其他属性通过esp_wifi_scan_start()传入的 wifi_scan_config_t 配置字段说明如下字段描述ssid非 NULL 时仅扫描具有相同 SSID 的 APbssid非 NULL 时仅扫描具有相同 BSSID 的 APchannel0 表示全信道扫描否则针对特定信道show_hidden0 表示忽略隐藏 SSID 的 AP非 0 则将其视为正常 APscan_typeWIFI_SCAN_TYPE_ACTIVE为主动扫描否则为被动扫描枚举定义见 esp_wifi_types_generic.hscan_time控制每个信道的扫描时间见下home_chan_dwell_time连续扫描信道之间停留在主信道的时间channel_bitmap通过位图指定要扫描的信道此时channel需置 0且只能扫描wifi_country_t允许的信道coex_background_scan使能后可在共存场景下返回主信道扫描其中scan_timewifi_scan_time_t的取值规则被动扫描时scan_time.passive为每个信道指定扫描时间1500 ms 的值可能导致 station 断开与 AP 的连接不建议使用主动扫描时每个信道的扫描时间由minscan_time_active_min与maxscan_time_active_max决定min0, max0每个信道扫描 120 msmin0, max0每个信道扫描 120 msmin0, max0每个信道扫描maxmsmin0, max0每个信道最短扫描minms若此期间未找到 AP 则跳转下一信道若找到 AP则该信道扫描maxms。如希望提升扫描性能可调整上述两个参数。此外调用esp_wifi_set_config()可全局配置部分扫描属性。10.3 三种扫描场景剖析1全信道前端扫描所有信道扫描全部 AP流程应用先调用esp_wifi_set_country()配置国家代码若默认国家信息有误→ 调用esp_wifi_scan_start()配置扫描信息SSID/BSSID/channel 均置 0→ 驱动依次扫描信道 1、2、…、NN 由国家代码决定每个信道主动发送 probe request 或被动等待 beacon默认停留 120 ms → 全部完成后产生WIFI_EVENT_SCAN_DONE事件。2全信道后端扫描与前端扫描的区别在跳至下一个信道之前Wi-Fi 驱动会先返回主信道停留 30 ms以便已有连接有一定时间发送/接收数据。3特定 AP 扫描流程与全信道前端扫描相似区别在于在扫描配置中将目标 AP 配置为 SSID/BSSID驱动扫描每个 AP 时检查是否为目标 AP。若扫描类型为WIFI_FAST_SCAN且确认找到目标 AP则产生扫描完成事件并结束扫描否则继续。第一个扫描的信道可能不是信道 1因为驱动会优化扫描顺序。多个匹配 AP 时的行为若碰巧存在两个 SSID 相同的 AP如两个名为 ap 的 APWIFI_FAST_SCAN只找到第一个扫描到的 ap而WIFI_ALL_CHANNEL_SCAN会找到全部两个 apstation 再根据配置规则选择连接目标。10.4 扫描完成事件后的记录读取WIFI_EVENT_SCAN_DONE事件的处理s3.1~s3.2调用esp_wifi_scan_get_ap_num()获取本次扫描找到的 AP 数量分配足够条目后调用esp_wifi_scan_get_ap_records()声明见 esp_wifi.h获取 AP 记录。注意一旦调用esp_wifi_scan_get_ap_records()驱动中的 AP 记录将被释放因此不要在单个扫描完成事件中重复调用两次反之若事件发生后未调用该函数驱动中的 AP 记录不会被释放务必确保调用且仅调用一次。十一、扫描的特殊场景与边界情况11.1 在 Wi-Fi 连接模式下扫描esp_wifi_connect()内部扫描调用esp_wifi_connect()后驱动首先尝试扫描已配置的 AP其过程与特定 AP 扫描相同但连接模式下扫描结束后不会产生扫描完成事件。找到目标 AP 则开始连接否则产生WIFI_EVENT_STA_DISCONNECTED事件。11.2 阻塞模式扫描esp_wifi_scan_start()的block参数为true时应用任务会被阻塞直到扫描完成。阻塞扫描与普通扫描相似但完成后不触发扫描完成事件。11.3 并行扫描不可行两个应用任务同时调用esp_wifi_scan_start()或某任务在收到扫描完成事件前再次调用该 API都不被 Wi-Fi 驱动支持——驱动不足以支持多个并行扫描应避免上述并行扫描。11.4 连接 Wi-Fi 时扫描失败与重试策略若 Wi-Fi 正在连接调用esp_wifi_scan_start()会立即失败因为连接优先级高于扫描。推荐策略是等待一段时间后重试——连接完成后扫描会立即成功。但延时重试并非万无一失文档描述了一个扫描永不成功的经典死循环station 正在连接不存在的 AP 或用错误密码连接 AP → 产生WIFI_EVENT_STA_DISCONNECTED应用收到断开事件后调用esp_wifi_connect()重连另一应用任务如控制任务调用esp_wifi_scan_start()扫描 → 因 station 一直处于连接状态每次扫描都立即失败扫描失败后等待一段时间重新扫描——如此循环扫描永远无法成功。解决方案为应用配置更佳的重连策略例如定义连续重连次数上限达到上限立即停止重连前 N 次连续重连立即执行之后延迟一段时间再尝试重连。应用可定义自己特有的重连策略防止扫描无法成功。十二、Wi-Fi Station 连接场景详解以下场景仅针对扫描阶段只找到一个目标 AP 的情况多个相同 SSID AP 的策略见 station-scenarios.rst 中发现多个 AP 时的连接策略一节。通常应用无需关心连接过程的内部细节以下为感兴趣者提供的简介。连接过程分为四个阶段12.1 扫描阶段s1.1驱动以Wi-Fi 连接模式扫描见 11.1s1.2未找到目标 AP 时产生WIFI_EVENT_STA_DISCONNECTED原因代码可能为WIFI_REASON_NO_AP_FOUND、WIFI_REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY、WIFI_REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD或WIFI_REASON_NO_AP_FOUND_IN_RSSI_THRESHOLD具体取决于 station 配置。12.2 认证阶段s2.1发送认证请求数据包并使能认证计时器s2.2计时器超时未收到认证响应 →WIFI_REASON_AUTH_EXPIREs2.3收到认证响应计时器终止s2.4AP 拒绝认证 →WIFI_REASON_AUTH_FAIL或 AP 指定的其他原因。12.3 关联阶段s3.1发送关联请求并使能关联计时器s3.2超时未收到关联响应 →WIFI_REASON_DISASSOC_DUE_TO_INACTIVITYs3.3收到关联响应计时器终止s3.4AP 拒绝关联 → 原因代码在关联响应中指定。12.4 四次握手阶段WPA/WPA2 加密场景s4.1使能握手定时器超时未收到 1/4 EAPOL →WIFI_REASON_HANDSHAKE_TIMEOUTs4.2收到 1/4 EAPOLs4.3station 回复 2/4 EAPOLs4.4握手定时器终止前未收到 3/4 EAPOL →WIFI_REASON_HANDSHAKE_TIMEOUTs4.5收到 3/4 EAPOLs4.6station 回复 4/4 EAPOLs4.7station 产生WIFI_EVENT_STA_CONNECTED事件连接成功。十三、Wi-Fi 原因代码全表与故障定位原因代码定义于 esp_wifi_types_generic.h宏名前缀为WIFI_REASON数值与 IEEE 802.11-2020 第 9.4.1.7 节一致从 200 开始为乐鑫自定义原因代码。以下为表格中部分宏的较短重命名TRANSMISSION_LINK_ESTABLISHMENT_FAILED→TX_LINK_EST_FAILEDNO_AP_FOUND_W_COMPATIBLE_SECURITY→NO_AP_FOUND_SECURITYNO_AP_FOUND_IN_AUTHMODE_THRESHOLD→NO_AP_FOUND_AUTHMODENO_AP_FOUND_IN_RSSI_THRESHOLD→NO_AP_FOUND_RSSI13.1 标准原因代码IEEE 802.11-2020原因代码数值描述UNSPECIFIED1内部错误如内存已满、内部发送失败、原因已被远端接收等AUTH_EXPIRE2先前的 authentication 失效。ESP station认证超时或从 AP 收到该代码ESP AP五分钟内未收到 station 数据包、调用esp_wifi_stop()终止 AP、调用esp_wifi_deauth_sta()取消认证AUTH_LEAVE3authentication 取消因为发送端 station 正在离开或已经离开。ESP station从 AP 收到该代码DISASSOC_DUE_TO_INACTIVITY4因 AP 不活跃association 取消。ESP station关联超时或从 AP 收到该代码ASSOC_TOOMANY5AP 无法同时处理所有已关联 STA。ESP AP关联数量已达上限CLASS2_FRAME_FROM_NONAUTH_STA6从未认证 station 收到 class-2 frameCLASS3_FRAME_FROM_NONASSOC_STA7从未关联 station 收到 class-3 frameASSOC_LEAVE8发送端 station 正在离开或已经离开BSS。ESP station从 AP 收到该代码或调用esp_wifi_disconnect()等 API 主动断开ASSOC_NOT_AUTHED9station 的 re(association) 请求未被响应 station 认证DISASSOC_PWRCAP_BAD10无法接收功率能力Power Capability元素中的信息DISASSOC_SUPCHAN_BAD11无法接收支持的信道Supported Channels元素中的信息BSS_TRANSITION_DISASSOC12AP 作为 BTM 过程的一部分希望切换到另一 AP。station 发送 BTM 请求并切换 AP 时报告 ROAMING 而非此代码IE_INVALID13无效元素内容不符合协议帧格式标准MIC_FAILURE14消息完整性代码MIC出错4WAY_HANDSHAKE_TIMEOUT15四次握手超时。由于历史原因ESP 中该代码实为WIFI_REASON_HANDSHAKE_TIMEOUTGROUP_KEY_UPDATE_TIMEOUT16组密钥Group-Key握手超时IE_IN_4WAY_DIFFERS17四次握手中的元素与 (re-)association 后的 request/probe 及 response/beacon frame 中的信息不同GROUP_CIPHER_INVALID18无效组密文PAIRWISE_CIPHER_INVALID19无效成对密文AKMP_INVALID20无效 AKMPUNSUPP_RSN_IE_VERSION21不支持的 RSNE 版本INVALID_RSN_IE_CAP22无效的 RSNE 性能802_1X_AUTH_FAILED23IEEE 802.1X authentication 失败CIPHER_SUITE_REJECTED24因安全策略安全密钥算法套件被拒TDLS_PEER_UNREACHABLE25通过 TDLS 直连无法到达对端 STATDLS_UNSPECIFIED26不明原因的 TDLS 直连中断SSP_REQUESTED_DISASSOC27会话被 SSP request 终止NO_SSP_ROAMING_AGREEMENT28缺乏 SSP 漫游认证BAD_CIPHER_OR_AKM29因 SSP 密码套件或 AKM 需求请求服务被拒NOT_AUTHORIZED_THIS_LOCATION30请求的服务在此位置未得到授权SERVICE_CHANGE_PRECLUDES_TS31BSS 服务特性或运行模式改变导致 QoS AP 带宽不足如 HT BSS 从 40 MHz 切到 20 MHzUNSPECIFIED_QOS32不明 QoS 相关原因取消 associationNOT_ENOUGH_BANDWIDTH33QoS AP 带宽不足MISSING_ACKS34大量帧需被确认但未被确认AP 传输或信道条件差EXCEEDED_TXOP35STA 传输超过 TXOPs 限制STA_LEAVING36请求 STA 离开 BSS 或重置END_BA37请求 STA 不再使用该流或会话UNKNOWN_BA38请求 STA 使用未完成的机制接收帧TIMEOUT39对端 STA 的请求超时Reserved40–45按 IEEE 802.11-2020 协议保留PEER_INITIATED46Disassociation 帧中已达到授权访问限制AP_INITIATED47Disassociation 帧中外部服务需求INVALID_FT_ACTION_FRAME_COUNT48无效的 FT Action 帧计数INVALID_PMKID49无效的成对主密钥标识符PMKIDINVALID_MDE50无效的 MDEINVALID_FTE51无效的 FTETX_LINK_EST_FAILED67在备用信道中建立传输链路失败ALTERATIVE_CHANNEL_OCCUPIED68备用信道被占用13.2 乐鑫自定义原因代码200 起原因代码数值描述BEACON_TIMEOUT200station 连续失去 N 个 beacon 后中断连接NO_AP_FOUND201station 未扫描到目标 AP。若因安全性或配置不匹配导致则报告 NO_AP_FOUND_XXX 系列AUTH_FAIL202authentication 失败但并非由超时引发ASSOC_FAIL203association 失败但并非由 DISASSOC_DUE_TO_INACTIVITY 或 ASSOC_TOOMANY 引发HANDSHAKE_TIMEOUT204握手失败与 4WAY_HANDSHAKE_TIMEOUT 失败原因相同CONNECTION_FAIL205AP 连接失败AP_TSF_RESET206因 AP 的 TSF 重置导致断开ROAMING207station 正在漫游到另一 AP仅供参考station 将自动切换ASSOC_COMEBACK_TIME_TOO_LONG208关联响应中的 Assoc 回来时间过长SA_QUERY_TIMEOUT209station 发送的 SA 查询未收到 AP 回复NO_AP_FOUND_SECURITY210找到符合标识条件如 SSID的 AP但安全配置不兼容导致连接被拒。可能情况包括AP 提供 WEP 但 station 密码不符合 WEP 要求station 配置为开放模式但 AP 以安全模式广播AP 使用企业安全但未设置对应企业配置station 配置 SAE-PK 但 AP 不支持station 配置 SAE-H2E 但 AP 仅支持 WPA3-PSK/WPA3-WPA2-PSKstation 配置为安全模式但扫描到的 AP 是开放模式station 配置 SAE HnP 但 AP 仅支持 H2Estation 禁用 H2E 但 AP 是需支持 H2E 的 WPA3-EXT-PSKAP 需 PMF 但 station 未配置支持station 要求 PMF 但 AP 未配置AP 使用不支持的组管理/对等加密算法station 未启用 OWE 但 AP 使用 OWEAP 在信标中广播无效 RSNXEAP 处于独立 BSS 模式NO_AP_FOUND_AUTHMODE211找到符合标识条件的 AP但未满足wifi_config_t中设置的身份验证模式阈值NO_AP_FOUND_RSSI212找到符合标识条件的 AP但未满足wifi_config_t中设置的 RSSI 阈值理解 NO_AP_FOUND_XXX 系列的优先级规则这些代码按重要性递增排列——若单个 AP 因多种原因连接失败报告其中较重要的原因代码若多个 AP 满足标识条件但分别因不同原因失败则报告最接近成功连接的 AP 的原因代码即最不重要原因的 AP。13.3 密码错误相关的常见原因代码原因代码数值典型场景4WAY_HANDSHAKE_TIMEOUT15STA 连接加密 AP 时设置了错误密码NO_AP_FOUND201连接未加密 AP 时设置了密码或连接加密 AP 时未设置密码HANDSHAKE_TIMEOUT204四次握手失败13.4 低 RSSI 相关的原因代码原因代码数值典型场景NO_AP_FOUND_IN_RSSI_THRESHOLD212低 RSSI 导致 station 无法扫描到目标 APHANDSHAKE_TIMEOUT204四次握手失败十四、发现多个 AP 时的连接策略该场景与单 AP 连接场景相似区别在于不会产生WIFI_EVENT_STA_DISCONNECTED事件除非 station 无法连接所有找到的 AP。station 会在多个候选 AP 中依据配置规则认证模式、RSSI 阈值等择优连接。十五、Wi-Fi 重新连接与 beacon 超时15.1 重新连接策略station 可能因多种原因断开如 AP 重启应用负责重新连接。推荐方法在收到WIFI_EVENT_STA_DISCONNECTED事件后调用esp_wifi_connect()。更复杂的重连场景需注意若断开事件由应用主动调用esp_wifi_disconnect()引发应用可能不希望重连若 station 随时可能调用esp_wifi_scan_start()扫描需要更佳的重连方法见「连接 Wi-Fi 时扫描」一节的重试策略。另一个关键点若存在多个相同 SSID 的 AP重连后可能不会回到之前的同一个 AP——重连时 station 永远选择最佳的 AP 进行连接。15.2 Beacon 超时机制ESP 使用 beacon 超时机制检测 AP 是否活跃若 station 在 inactive 时间内未收到所连接 AP 的 beacon将发生 beacon 超时。inactive 时间通过esp_wifi_set_inactive_time()声明见 esp_wifi.h设置。beacon 超时后station 向 AP 发送5 个 probe request若仍未收到 probe response 或 beacon则与 AP 断开并产生WIFI_EVENT_STA_DISCONNECTED事件。注意扫描过程会重置 beacon 超时定时器即扫描会影响WIFI_EVENT_STA_BEACON_TIMEOUT事件的触发时机。十六、工程实践小结初始化顺序esp_netif_init()→esp_event_loop_create()→esp_netif_create_default_wifi_sta()→esp_wifi_init()→ 创建应用任务任务依赖套接字时应在收到 IP 后再创建。配置时机连接建立前完成esp_wifi_set_mode(WIFI_MODE_STA)与协议、国家、带宽等配置连接后更改配置会导致断开。连接触发点在WIFI_EVENT_STA_START事件后调用esp_wifi_connect()。套接字创建务必等待IP_EVENT_STA_GOT_IPIP 更改ip_change true时关闭并重建套接字。断开处理收到WIFI_EVENT_STA_DISCONNECTED后按原因代码分类处理——密码错误15/201/204提示用户修正凭据RSSI 过低212提示改善信号随后执行重连注意重连上限与退避策略避免与扫描任务死锁。扫描纪律单次扫描完成事件内只调用一次esp_wifi_scan_get_ap_records()避免并行扫描连接过程中发起扫描会立即失败需配合重连上限等策略。清理流程esp_wifi_disconnect()→esp_wifi_stop()→esp_wifi_deinit()。如需查看本文引用的全部 API 原型与事件枚举定义可继续阅读 esp_wifi.h 与 esp_wifi_types_generic.h 源码。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ESP-IDF Wi-Fi Station 场景完全指南：从初始化、扫描到连接与原因代码解析
ESP-IDF Wi-Fi Station 场景完全指南从初始化、扫描到连接与原因代码解析【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本指南基于乐鑫 ESP-IDF 官方文档 Station 场景系统讲解 ESP32 系列芯片作为 Wi-Fi Station站点时的完整生命周期——包括 Wi-Fi/LwIP 初始化、配置、启动、连接、获取 IP、断开、IP 更改与清理八个阶段深入剖析 Wi-Fi 扫描的六种类型与八种组合方式、扫描配置参数、连接过程中各阶段的事件与原因代码并给出可落地的重连策略与工程实践建议。读完本文你将能够基于 ESP-IDF 正确编写 station 模式的连接逻辑、事件处理与扫描程序并能依据WIFI_EVENT_STA_DISCONNECTED携带的原因代码快速定位故障。一、Station 通用场景总览八阶段生命周期在 station 模式下一个完整的 Wi-Fi 应用生命周期包含八个阶段初始化、配置、启动、连接、获取 IP、断开、IP 更改与清理。这些阶段由四个关键任务协作完成Main task主任务负责调用初始化、配置、启动类 APIApp task应用程序任务承载业务逻辑例如创建套接字、发起连接、执行重连Event task事件任务由esp_event_loop_create()创建负责接收并分发各类 Wi-Fi/IP 事件LwIP taskLwIP 任务由esp_netif_init()创建负责 TCP/IP 协议栈相关工作。上图对应的 seqdiag 源码位于 station-scenarios.rst展示了上述任务之间在初始化、配置、启动、连接、获取 IP、断开、IP 更改、清理八个阶段的交互时序是理解 station 编程模型的核心参考。下文将逐一展开每个阶段的标准做法、事件流转与易错点。二、Wi-Fi/LwIP 初始化阶段阶段 1初始化阶段共 5 个步骤推荐按如下顺序执行顺序并非强制步骤动作关键 APIs1.1创建 LwIP 核心任务并初始化 TCP/IP 相关工作esp_netif_init()s1.2创建系统事件任务并注册事件回调esp_event_loop_create()s1.3创建绑定 station/AP 的默认网络接口实例esp_netif_create_default_wifi_sta()/esp_netif_create_default_wifi_ap()s1.4创建 Wi-Fi 驱动程序任务并初始化驱动esp_wifi_init()s1.5通过 OS API 创建应用程序任务xTaskCreate()等关键说明s1.1 中esp_netif_init()会创建一个 LwIP 核心任务事件回调在 s1.2 中初始化此回调的唯一动作通常是将事件中继到应用程序任务。s1.3 中esp_netif_create_default_wifi_sta()创建带 TCP/IP 协议栈的默认 station 网络接口实例其实现位于 esp_wifi_default.h。推荐顺序并不强制你可以在 s1.1 之前先创建应用程序任务并在该任务中完成其余全部初始化。但若应用程序任务依赖套接字过早创建任务可能不适用——此时应等收到 IP 之后再创建任务。三、Wi-Fi 配置阶段阶段 2Wi-Fi 驱动初始化成功后进入配置阶段。station 场景下首先要将模式配置为 stationesp_wifi_set_mode(WIFI_MODE_STA);之后可通过其他esp_wifi_set_xxxAPI 进行更多设置例如协议模式esp_wifi_set_protocol()、国家代码esp_wifi_set_country()、带宽等。重要约束配置应在建立连接之前完成但这并非强制——只要驱动已成功初始化可在任意阶段配置。若连接建立后不再更改配置务必先在连接前配置完毕。因为调用配置类 API如esp_wifi_set_protocol()会导致 Wi-Fi 连接断开带来不便。若 menuconfig 已使能 Wi-Fi NVS flashCONFIG_ESP_WIFI_NVS_ENABLED当前及后续的 Wi-Fi 配置信息都会存储至 NVS flash。这样上电/重启时无需从头配置 Wi-Fi 驱动只需调用esp_wifi_get_xxx系列 API 获取此前存储的配置。若不想沿用旧配置也可重新配置。四、Wi-Fi 启动阶段阶段 3s3.1调用esp_wifi_start()声明见 esp_wifi.h启动 Wi-Fi 驱动。s3.2驱动向事件任务发布WIFI_EVENT_STA_START事件事件任务执行常规处理后调用应用程序的事件回调。s3.3应用程序的事件回调将事件中继到应用程序任务。推荐在此事件发生后调用esp_wifi_connect()发起连接也可以等待其他时机再调用。五、Wi-Fi 连接阶段阶段 4s4.1调用esp_wifi_connect()声明见 esp_wifi.h后驱动启动内部扫描/连接过程。s4.2若内部扫描/连接成功产生WIFI_EVENT_STA_CONNECTED事件事件任务随即启动 DHCP 客户端服务触发 DHCP 流程。s4.3事件回调将WIFI_EVENT_STA_CONNECTED中继到应用程序任务。通常应用无需特别操作可执行打印日志等任意动作。易失败点s4.2 中连接可能因密码错误、未找到 AP 等原因失败此时会触发WIFI_EVENT_STA_DISCONNECTED事件并携带错误原因代码详见下文「Wi-Fi 原因代码」章节。六、Wi-Fi 获取 IP 阶段阶段 5s5.1DHCP 客户端初始化完成后进入获取 IP阶段。s5.2成功从 DHCP 服务器收到 IP 后触发IP_EVENT_STA_GOT_IP事件事件任务执行正常处理。s5.3事件回调将IP_EVENT_STA_GOT_IP中继到应用程序任务。这是基于 LwIP 构建的应用程序最关键的信号——它意味着应用已就绪可以开始创建 TCP/UDP 套接字等操作。⚠️常见错误在收到IP_EVENT_STA_GOT_IP之前就初始化套接字。切忌在接收到 IP 之前启动任何套接字相关操作。七、Wi-Fi 断开阶段阶段 6s6.1因 AP 掉电、RSSI 较弱等原因连接中断时产生WIFI_EVENT_STA_DISCONNECTED事件该事件也可能在阶段 3 就发生。此时事件任务会通知 LwIP 任务清除/移除所有 UDP/TCP 连接所有应用程序套接字进入错误状态——断开事件发生时任何套接字都无法正常工作。s6.2事件回调将事件中继到应用程序任务。推荐调用esp_wifi_connect()重新连接同时关闭所有套接字并在必要时重新创建。八、Wi-Fi IP 更改阶段阶段 7s7.1IP 地址发生更改时再次触发IP_EVENT_STA_GOT_IP事件此时事件中的ip_change字段为true。s7.2此事件对应用程序至关重要。事件发生时适合关闭所有已创建的套接字并重新创建。九、Wi-Fi 清理阶段阶段 8按顺序调用以下 API 完成清理esp_wifi_disconnect(); // s8.1 断开 Wi-Fi 连接 esp_wifi_stop(); // s8.2 终止 Wi-Fi 驱动见 esp_wifi.h L458 esp_wifi_deinit(); // s8.3 清理 Wi-Fi 驱动见 esp_wifi.h L400十、Wi-Fi 扫描类型、组合与配置esp_wifi_scan_start()声明见 esp_wifi.h目前仅支持 station 模式或 station/AP 共存模式。10.1 六种扫描类型模式描述主动扫描通过发送 probe request 进行扫描默认扫描模式被动扫描不发送 probe request跳至特定信道等待 beacon通过wifi_scan_config_t的scan_type字段使能前端扫描station 模式且 Wi-Fi 未连接时可进行由 Wi-Fi 驱动决定应用程序无法配置后端扫描station 模式或 station/AP 共存模式下 Wi-Fi 已连接时可进行同样由驱动决定全信道扫描扫描所有信道wifi_scan_config_t的channel字段为 0 时生效特定信道扫描仅扫描特定信道channel字段为 1–14 时生效以上类型可任意组合共 8 种扫描方式全信道/特定信道 × 前端/后端 × 主动/被动。10.2 扫描配置结构体wifi_scan_config_t扫描类型与其他属性通过esp_wifi_scan_start()传入的 wifi_scan_config_t 配置字段说明如下字段描述ssid非 NULL 时仅扫描具有相同 SSID 的 APbssid非 NULL 时仅扫描具有相同 BSSID 的 APchannel0 表示全信道扫描否则针对特定信道show_hidden0 表示忽略隐藏 SSID 的 AP非 0 则将其视为正常 APscan_typeWIFI_SCAN_TYPE_ACTIVE为主动扫描否则为被动扫描枚举定义见 esp_wifi_types_generic.hscan_time控制每个信道的扫描时间见下home_chan_dwell_time连续扫描信道之间停留在主信道的时间channel_bitmap通过位图指定要扫描的信道此时channel需置 0且只能扫描wifi_country_t允许的信道coex_background_scan使能后可在共存场景下返回主信道扫描其中scan_timewifi_scan_time_t的取值规则被动扫描时scan_time.passive为每个信道指定扫描时间1500 ms 的值可能导致 station 断开与 AP 的连接不建议使用主动扫描时每个信道的扫描时间由minscan_time_active_min与maxscan_time_active_max决定min0, max0每个信道扫描 120 msmin0, max0每个信道扫描 120 msmin0, max0每个信道扫描maxmsmin0, max0每个信道最短扫描minms若此期间未找到 AP 则跳转下一信道若找到 AP则该信道扫描maxms。如希望提升扫描性能可调整上述两个参数。此外调用esp_wifi_set_config()可全局配置部分扫描属性。10.3 三种扫描场景剖析1全信道前端扫描所有信道扫描全部 AP流程应用先调用esp_wifi_set_country()配置国家代码若默认国家信息有误→ 调用esp_wifi_scan_start()配置扫描信息SSID/BSSID/channel 均置 0→ 驱动依次扫描信道 1、2、…、NN 由国家代码决定每个信道主动发送 probe request 或被动等待 beacon默认停留 120 ms → 全部完成后产生WIFI_EVENT_SCAN_DONE事件。2全信道后端扫描与前端扫描的区别在跳至下一个信道之前Wi-Fi 驱动会先返回主信道停留 30 ms以便已有连接有一定时间发送/接收数据。3特定 AP 扫描流程与全信道前端扫描相似区别在于在扫描配置中将目标 AP 配置为 SSID/BSSID驱动扫描每个 AP 时检查是否为目标 AP。若扫描类型为WIFI_FAST_SCAN且确认找到目标 AP则产生扫描完成事件并结束扫描否则继续。第一个扫描的信道可能不是信道 1因为驱动会优化扫描顺序。多个匹配 AP 时的行为若碰巧存在两个 SSID 相同的 AP如两个名为 ap 的 APWIFI_FAST_SCAN只找到第一个扫描到的 ap而WIFI_ALL_CHANNEL_SCAN会找到全部两个 apstation 再根据配置规则选择连接目标。10.4 扫描完成事件后的记录读取WIFI_EVENT_SCAN_DONE事件的处理s3.1~s3.2调用esp_wifi_scan_get_ap_num()获取本次扫描找到的 AP 数量分配足够条目后调用esp_wifi_scan_get_ap_records()声明见 esp_wifi.h获取 AP 记录。注意一旦调用esp_wifi_scan_get_ap_records()驱动中的 AP 记录将被释放因此不要在单个扫描完成事件中重复调用两次反之若事件发生后未调用该函数驱动中的 AP 记录不会被释放务必确保调用且仅调用一次。十一、扫描的特殊场景与边界情况11.1 在 Wi-Fi 连接模式下扫描esp_wifi_connect()内部扫描调用esp_wifi_connect()后驱动首先尝试扫描已配置的 AP其过程与特定 AP 扫描相同但连接模式下扫描结束后不会产生扫描完成事件。找到目标 AP 则开始连接否则产生WIFI_EVENT_STA_DISCONNECTED事件。11.2 阻塞模式扫描esp_wifi_scan_start()的block参数为true时应用任务会被阻塞直到扫描完成。阻塞扫描与普通扫描相似但完成后不触发扫描完成事件。11.3 并行扫描不可行两个应用任务同时调用esp_wifi_scan_start()或某任务在收到扫描完成事件前再次调用该 API都不被 Wi-Fi 驱动支持——驱动不足以支持多个并行扫描应避免上述并行扫描。11.4 连接 Wi-Fi 时扫描失败与重试策略若 Wi-Fi 正在连接调用esp_wifi_scan_start()会立即失败因为连接优先级高于扫描。推荐策略是等待一段时间后重试——连接完成后扫描会立即成功。但延时重试并非万无一失文档描述了一个扫描永不成功的经典死循环station 正在连接不存在的 AP 或用错误密码连接 AP → 产生WIFI_EVENT_STA_DISCONNECTED应用收到断开事件后调用esp_wifi_connect()重连另一应用任务如控制任务调用esp_wifi_scan_start()扫描 → 因 station 一直处于连接状态每次扫描都立即失败扫描失败后等待一段时间重新扫描——如此循环扫描永远无法成功。解决方案为应用配置更佳的重连策略例如定义连续重连次数上限达到上限立即停止重连前 N 次连续重连立即执行之后延迟一段时间再尝试重连。应用可定义自己特有的重连策略防止扫描无法成功。十二、Wi-Fi Station 连接场景详解以下场景仅针对扫描阶段只找到一个目标 AP 的情况多个相同 SSID AP 的策略见 station-scenarios.rst 中发现多个 AP 时的连接策略一节。通常应用无需关心连接过程的内部细节以下为感兴趣者提供的简介。连接过程分为四个阶段12.1 扫描阶段s1.1驱动以Wi-Fi 连接模式扫描见 11.1s1.2未找到目标 AP 时产生WIFI_EVENT_STA_DISCONNECTED原因代码可能为WIFI_REASON_NO_AP_FOUND、WIFI_REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY、WIFI_REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD或WIFI_REASON_NO_AP_FOUND_IN_RSSI_THRESHOLD具体取决于 station 配置。12.2 认证阶段s2.1发送认证请求数据包并使能认证计时器s2.2计时器超时未收到认证响应 →WIFI_REASON_AUTH_EXPIREs2.3收到认证响应计时器终止s2.4AP 拒绝认证 →WIFI_REASON_AUTH_FAIL或 AP 指定的其他原因。12.3 关联阶段s3.1发送关联请求并使能关联计时器s3.2超时未收到关联响应 →WIFI_REASON_DISASSOC_DUE_TO_INACTIVITYs3.3收到关联响应计时器终止s3.4AP 拒绝关联 → 原因代码在关联响应中指定。12.4 四次握手阶段WPA/WPA2 加密场景s4.1使能握手定时器超时未收到 1/4 EAPOL →WIFI_REASON_HANDSHAKE_TIMEOUTs4.2收到 1/4 EAPOLs4.3station 回复 2/4 EAPOLs4.4握手定时器终止前未收到 3/4 EAPOL →WIFI_REASON_HANDSHAKE_TIMEOUTs4.5收到 3/4 EAPOLs4.6station 回复 4/4 EAPOLs4.7station 产生WIFI_EVENT_STA_CONNECTED事件连接成功。十三、Wi-Fi 原因代码全表与故障定位原因代码定义于 esp_wifi_types_generic.h宏名前缀为WIFI_REASON数值与 IEEE 802.11-2020 第 9.4.1.7 节一致从 200 开始为乐鑫自定义原因代码。以下为表格中部分宏的较短重命名TRANSMISSION_LINK_ESTABLISHMENT_FAILED→TX_LINK_EST_FAILEDNO_AP_FOUND_W_COMPATIBLE_SECURITY→NO_AP_FOUND_SECURITYNO_AP_FOUND_IN_AUTHMODE_THRESHOLD→NO_AP_FOUND_AUTHMODENO_AP_FOUND_IN_RSSI_THRESHOLD→NO_AP_FOUND_RSSI13.1 标准原因代码IEEE 802.11-2020原因代码数值描述UNSPECIFIED1内部错误如内存已满、内部发送失败、原因已被远端接收等AUTH_EXPIRE2先前的 authentication 失效。ESP station认证超时或从 AP 收到该代码ESP AP五分钟内未收到 station 数据包、调用esp_wifi_stop()终止 AP、调用esp_wifi_deauth_sta()取消认证AUTH_LEAVE3authentication 取消因为发送端 station 正在离开或已经离开。ESP station从 AP 收到该代码DISASSOC_DUE_TO_INACTIVITY4因 AP 不活跃association 取消。ESP station关联超时或从 AP 收到该代码ASSOC_TOOMANY5AP 无法同时处理所有已关联 STA。ESP AP关联数量已达上限CLASS2_FRAME_FROM_NONAUTH_STA6从未认证 station 收到 class-2 frameCLASS3_FRAME_FROM_NONASSOC_STA7从未关联 station 收到 class-3 frameASSOC_LEAVE8发送端 station 正在离开或已经离开BSS。ESP station从 AP 收到该代码或调用esp_wifi_disconnect()等 API 主动断开ASSOC_NOT_AUTHED9station 的 re(association) 请求未被响应 station 认证DISASSOC_PWRCAP_BAD10无法接收功率能力Power Capability元素中的信息DISASSOC_SUPCHAN_BAD11无法接收支持的信道Supported Channels元素中的信息BSS_TRANSITION_DISASSOC12AP 作为 BTM 过程的一部分希望切换到另一 AP。station 发送 BTM 请求并切换 AP 时报告 ROAMING 而非此代码IE_INVALID13无效元素内容不符合协议帧格式标准MIC_FAILURE14消息完整性代码MIC出错4WAY_HANDSHAKE_TIMEOUT15四次握手超时。由于历史原因ESP 中该代码实为WIFI_REASON_HANDSHAKE_TIMEOUTGROUP_KEY_UPDATE_TIMEOUT16组密钥Group-Key握手超时IE_IN_4WAY_DIFFERS17四次握手中的元素与 (re-)association 后的 request/probe 及 response/beacon frame 中的信息不同GROUP_CIPHER_INVALID18无效组密文PAIRWISE_CIPHER_INVALID19无效成对密文AKMP_INVALID20无效 AKMPUNSUPP_RSN_IE_VERSION21不支持的 RSNE 版本INVALID_RSN_IE_CAP22无效的 RSNE 性能802_1X_AUTH_FAILED23IEEE 802.1X authentication 失败CIPHER_SUITE_REJECTED24因安全策略安全密钥算法套件被拒TDLS_PEER_UNREACHABLE25通过 TDLS 直连无法到达对端 STATDLS_UNSPECIFIED26不明原因的 TDLS 直连中断SSP_REQUESTED_DISASSOC27会话被 SSP request 终止NO_SSP_ROAMING_AGREEMENT28缺乏 SSP 漫游认证BAD_CIPHER_OR_AKM29因 SSP 密码套件或 AKM 需求请求服务被拒NOT_AUTHORIZED_THIS_LOCATION30请求的服务在此位置未得到授权SERVICE_CHANGE_PRECLUDES_TS31BSS 服务特性或运行模式改变导致 QoS AP 带宽不足如 HT BSS 从 40 MHz 切到 20 MHzUNSPECIFIED_QOS32不明 QoS 相关原因取消 associationNOT_ENOUGH_BANDWIDTH33QoS AP 带宽不足MISSING_ACKS34大量帧需被确认但未被确认AP 传输或信道条件差EXCEEDED_TXOP35STA 传输超过 TXOPs 限制STA_LEAVING36请求 STA 离开 BSS 或重置END_BA37请求 STA 不再使用该流或会话UNKNOWN_BA38请求 STA 使用未完成的机制接收帧TIMEOUT39对端 STA 的请求超时Reserved40–45按 IEEE 802.11-2020 协议保留PEER_INITIATED46Disassociation 帧中已达到授权访问限制AP_INITIATED47Disassociation 帧中外部服务需求INVALID_FT_ACTION_FRAME_COUNT48无效的 FT Action 帧计数INVALID_PMKID49无效的成对主密钥标识符PMKIDINVALID_MDE50无效的 MDEINVALID_FTE51无效的 FTETX_LINK_EST_FAILED67在备用信道中建立传输链路失败ALTERATIVE_CHANNEL_OCCUPIED68备用信道被占用13.2 乐鑫自定义原因代码200 起原因代码数值描述BEACON_TIMEOUT200station 连续失去 N 个 beacon 后中断连接NO_AP_FOUND201station 未扫描到目标 AP。若因安全性或配置不匹配导致则报告 NO_AP_FOUND_XXX 系列AUTH_FAIL202authentication 失败但并非由超时引发ASSOC_FAIL203association 失败但并非由 DISASSOC_DUE_TO_INACTIVITY 或 ASSOC_TOOMANY 引发HANDSHAKE_TIMEOUT204握手失败与 4WAY_HANDSHAKE_TIMEOUT 失败原因相同CONNECTION_FAIL205AP 连接失败AP_TSF_RESET206因 AP 的 TSF 重置导致断开ROAMING207station 正在漫游到另一 AP仅供参考station 将自动切换ASSOC_COMEBACK_TIME_TOO_LONG208关联响应中的 Assoc 回来时间过长SA_QUERY_TIMEOUT209station 发送的 SA 查询未收到 AP 回复NO_AP_FOUND_SECURITY210找到符合标识条件如 SSID的 AP但安全配置不兼容导致连接被拒。可能情况包括AP 提供 WEP 但 station 密码不符合 WEP 要求station 配置为开放模式但 AP 以安全模式广播AP 使用企业安全但未设置对应企业配置station 配置 SAE-PK 但 AP 不支持station 配置 SAE-H2E 但 AP 仅支持 WPA3-PSK/WPA3-WPA2-PSKstation 配置为安全模式但扫描到的 AP 是开放模式station 配置 SAE HnP 但 AP 仅支持 H2Estation 禁用 H2E 但 AP 是需支持 H2E 的 WPA3-EXT-PSKAP 需 PMF 但 station 未配置支持station 要求 PMF 但 AP 未配置AP 使用不支持的组管理/对等加密算法station 未启用 OWE 但 AP 使用 OWEAP 在信标中广播无效 RSNXEAP 处于独立 BSS 模式NO_AP_FOUND_AUTHMODE211找到符合标识条件的 AP但未满足wifi_config_t中设置的身份验证模式阈值NO_AP_FOUND_RSSI212找到符合标识条件的 AP但未满足wifi_config_t中设置的 RSSI 阈值理解 NO_AP_FOUND_XXX 系列的优先级规则这些代码按重要性递增排列——若单个 AP 因多种原因连接失败报告其中较重要的原因代码若多个 AP 满足标识条件但分别因不同原因失败则报告最接近成功连接的 AP 的原因代码即最不重要原因的 AP。13.3 密码错误相关的常见原因代码原因代码数值典型场景4WAY_HANDSHAKE_TIMEOUT15STA 连接加密 AP 时设置了错误密码NO_AP_FOUND201连接未加密 AP 时设置了密码或连接加密 AP 时未设置密码HANDSHAKE_TIMEOUT204四次握手失败13.4 低 RSSI 相关的原因代码原因代码数值典型场景NO_AP_FOUND_IN_RSSI_THRESHOLD212低 RSSI 导致 station 无法扫描到目标 APHANDSHAKE_TIMEOUT204四次握手失败十四、发现多个 AP 时的连接策略该场景与单 AP 连接场景相似区别在于不会产生WIFI_EVENT_STA_DISCONNECTED事件除非 station 无法连接所有找到的 AP。station 会在多个候选 AP 中依据配置规则认证模式、RSSI 阈值等择优连接。十五、Wi-Fi 重新连接与 beacon 超时15.1 重新连接策略station 可能因多种原因断开如 AP 重启应用负责重新连接。推荐方法在收到WIFI_EVENT_STA_DISCONNECTED事件后调用esp_wifi_connect()。更复杂的重连场景需注意若断开事件由应用主动调用esp_wifi_disconnect()引发应用可能不希望重连若 station 随时可能调用esp_wifi_scan_start()扫描需要更佳的重连方法见「连接 Wi-Fi 时扫描」一节的重试策略。另一个关键点若存在多个相同 SSID 的 AP重连后可能不会回到之前的同一个 AP——重连时 station 永远选择最佳的 AP 进行连接。15.2 Beacon 超时机制ESP 使用 beacon 超时机制检测 AP 是否活跃若 station 在 inactive 时间内未收到所连接 AP 的 beacon将发生 beacon 超时。inactive 时间通过esp_wifi_set_inactive_time()声明见 esp_wifi.h设置。beacon 超时后station 向 AP 发送5 个 probe request若仍未收到 probe response 或 beacon则与 AP 断开并产生WIFI_EVENT_STA_DISCONNECTED事件。注意扫描过程会重置 beacon 超时定时器即扫描会影响WIFI_EVENT_STA_BEACON_TIMEOUT事件的触发时机。十六、工程实践小结初始化顺序esp_netif_init()→esp_event_loop_create()→esp_netif_create_default_wifi_sta()→esp_wifi_init()→ 创建应用任务任务依赖套接字时应在收到 IP 后再创建。配置时机连接建立前完成esp_wifi_set_mode(WIFI_MODE_STA)与协议、国家、带宽等配置连接后更改配置会导致断开。连接触发点在WIFI_EVENT_STA_START事件后调用esp_wifi_connect()。套接字创建务必等待IP_EVENT_STA_GOT_IPIP 更改ip_change true时关闭并重建套接字。断开处理收到WIFI_EVENT_STA_DISCONNECTED后按原因代码分类处理——密码错误15/201/204提示用户修正凭据RSSI 过低212提示改善信号随后执行重连注意重连上限与退避策略避免与扫描任务死锁。扫描纪律单次扫描完成事件内只调用一次esp_wifi_scan_get_ap_records()避免并行扫描连接过程中发起扫描会立即失败需配合重连上限等策略。清理流程esp_wifi_disconnect()→esp_wifi_stop()→esp_wifi_deinit()。如需查看本文引用的全部 API 原型与事件枚举定义可继续阅读 esp_wifi.h 与 esp_wifi_types_generic.h 源码。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考