ESP32 Arduino Wi-Fi API 全解析STA 客户端、Soft-AP 热点、事件回调与网络扫描实战指南【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32本指南以 arduino-esp32 仓库官方文档 Wi-Fi API 为骨架系统讲解 ESP32 在 Arduino 环境下的 Wi-Fi 驱动接口包括 StationSTA与 Soft-AP 两种工作模式、事件回调、主机名与双天线配置以及 WiFiMulti 多热点切换与 Wi-Fi 扫描等进阶能力。读完本文你将能够独立完成ESP32 连接互联网与ESP32 开放热点供设备接入两类典型工程并掌握用事件机制编写健壮网络代码的正确姿势。一、Wi-Fi API 概览与支持能力arduino-esp32 的 Wi-Fi API 封装了 ESP32 系列 SoC 内置的 802.11b/g/n 协议驱动对应源码位于 libraries/WiFi/src 目录主要能力包括Station 模式STA 模式 / Wi-Fi 客户端模式ESP32 作为客户端连接外部的接入点AP是联网项目HTTP 请求、MQTT、云平台上报等的基础AP 模式Soft-AP 模式 / 接入点模式ESP32 自身广播一个 Wi-Fi 网络其他设备站点连接进来可配合内置 HTTP/HTTPS 服务器提供配置页、固件升级等服务安全模式支持 WPA2、WPA3 等多种认证方式源码中 AP 默认认证模式为WIFI_AUTH_WPA2_PSK见 WiFiAP.h 中的WIFI_AP_DEFAULT_AUTH_MODE定义接入点扫描主动扫描周围可用的 Wi-Fi 网络。从源码结构看Wi-Fi 库被拆分为WiFiGeneric通用能力、WiFiAP、WiFiSTA、WiFiScan、WiFiMulti等多个类并通过 WiFi.h 对外暴露统一的WiFi全局对象。本文后续章节将按照官方文档的组织方式从通用 API 到 AP/STA 专属 API 逐一展开。二、两种核心工作模式2.1 工作为 APSoft-AP 模式在此模式下ESP32 被配置为接入点通过提供一个 Wi-Fi 网络来接收来自其他设备站点的入站连接。典型应用是在 ESP32 内部托管 HTTP 或 HTTPS 服务器——例如设备配网页面、局域网内的 Web 控制台。2.2 工作为 STA客户端模式STA 模式用于让 ESP32 连接到一个由接入点提供的 Wi-Fi 网络。如果你的项目需要接入互联网就必须使用该模式。两种模式并非互斥ESP32 支持同时开启 STA 与 AP如 Wi-Fi 中继场景参考 WiFiExtender.ino 示例。三、通用 APIAP 与 STA 共用3.1 onEvent 与 removeEvent事件驱动的核心机制onEvent用于注册一个由调用方提供的回调函数在 Wi-Fi 事件发生时被调用。库中提供了多种回调形式完整声明见 WiFiGeneric.h形式一仅接收事件 ID 的函数指针回调typedef void (*WiFiEventCb)(arduino_event_id_t); wifi_event_id_t onEvent(WiFiEventCb, arduino_event_id_t ARDUINO_EVENT_MAX);形式二接收事件 ID 信息结构体的回调typedef struct{ arduino_event_id_t event_id; arduino_event_info_t event_info; } arduino_event_t; typedef void (*WiFiEventSysCb)(arduino_event_t *); wifi_event_id_t onEvent(WiFiEventSysCb, arduino_event_id_t ARDUINO_EVENT_MAX);形式三使用std::function分别接收事件 ID 与信息typedef std::functionvoid(arduino_event_id_t, arduino_event_info_t) WiFiEventFuncCb; wifi_event_id_t onEvent(WiFiEventFuncCb, arduino_event_id_t ARDUINO_EVENT_MAX);对应的移除回调接口void removeEvent(WiFiEventCb, arduino_event_id_t ARDUINO_EVENT_MAX); void removeEvent(WiFiEventSysCb, arduino_event_id_t ARDUINO_EVENT_MAX); void removeEvent(wifi_event_id_t ARDUINO_EVENT_MAX);在所有形式中注册函数都接受一个可选的事件类型参数传入具体事件类型时回调只在发生该特定事件时被触发使用默认值ARDUINO_EVENT_MAX时回调将收到所有 Wi-Fi 事件。任何回调函数都会在参数中拿到事件类型部分形式还额外提供arduino_event_info_t或包含 ID 与 info 两者的arduino_event_t——这是一个联合体针对不同事件类型包含不同的附加信息结构例如断开原因、获得的 IP 等。事件类型的完整列表及 info 子结构可查阅 WiFiGeneric.h完整的事件处理示例见 WiFiClientEvents.ino。从该示例可以直观看到常用事件枚举部分ARDUINO_EVENT_WIFI_READY // ESP32 WiFi ready ARDUINO_EVENT_WIFI_SCAN_DONE // ESP32 finish scanning AP ARDUINO_EVENT_WIFI_STA_START // ESP32 station start ARDUINO_EVENT_WIFI_STA_CONNECTED // ESP32 station connected to AP ARDUINO_EVENT_WIFI_STA_DISCONNECTED // ESP32 station disconnected from AP ARDUINO_EVENT_WIFI_STA_GOT_IP // ESP32 station got IP from connected AP ARDUINO_EVENT_WIFI_AP_START // ESP32 soft-AP start ARDUINO_EVENT_WIFI_AP_STACONNECTED // a station connected to ESP32 soft-AP ARDUINO_EVENT_WIFI_AP_STAIPASSIGNED // ESP32 soft-AP assign an IP to a connected station ARDUINO_EVENT_WIFI_STA_GOT_IP6 // ESP32 station interface v6IP addr is preferred⚠️ 回调线程安全性必须遵守事件回调函数是在独立线程FreeRTOS task上被调用的与运行setup()和loop()的主应用线程相互独立。因此回调函数必须是线程安全的不得在未加锁的情况下直接访问共享/全局变量只能调用同样线程安全的函数某些核心操作如Serial.print()是线程安全的但很多函数不是。特别注意WiFi.onEvent()和WiFi.removeEvent()本身不是线程安全的绝不能在回调线程中调用它们。3.2 setHostname 与 getHostname设置 DHCP 客户端主机名setHostname用于设置 DHCP 客户端向网络标识自己的名称。在典型的家庭/办公网络中该名称会显示在路由器的设备列表里。主机名长度不得超过 32 个字符。setHostname(const char *hostname);如果从未设置过主机名系统会根据芯片型号与 MAC 地址分配一个默认名称。可通过getHostname()获取当前默认或自定义主机名const char *getHostname();⚠️ 调用时机限制setHostname()必须在 Wi-Fi 启动之前调用——即在WiFi.begin()、WiFi.softAP()、WiFi.mode()或WiFi.run()之前。如需在运行中修改名称必须先调用WiFi.mode(WIFI_MODE_NULL)重置 Wi-Fi再执行WiFi.setHostname(...)最后重新启动 Wi-Fi。3.3 useStaticBuffers控制 Wi-Fi 缓冲区的内存分配模式该函数用于设置 Wi-Fi 缓冲区的内存分配模式static void useStaticBuffers(bool bufferMode);传true将 Wi-Fi 缓冲区内存分配设为静态传false将缓冲区内存分配设为动态。动态分配被推荐用于节省内存、降低资源占用但性能略慢于静态分配静态分配适合对性能有更高要求、且应用是多任务multi-tasking的场景。如果完全不调用本函数默认采用动态分配。3.4 setDualAntennaConfig双天线/RF 开关配置配置双天线功能仅适用于 ESP32-WROOM-DA 模块或其他带有 RF 开关的 ESP32bool setDualAntennaConfig(uint8_t gpio_ant1, uint8_t gpio_ant2, wifi_rx_ant_t rx_mode, wifi_tx_ant_t tx_mode);参数说明gpio_ant1连接到 RF 开关的天线 1 的 GPIO 号ESP32-WROOM-DA 上默认为GPIO2gpio_ant2连接到 RF 开关的天线 2 的 GPIO 号ESP32-WROOM-DA 上默认为GPIO25rx_mode设置 RX 天线模式可选值见wifi_rx_ant_ttx_mode设置 TX 天线模式可选值见wifi_tx_ant_t。配置成功返回true。rx_mode可选值定义见 WiFiGeneric.hWIFI_RX_ANT0所有 RX 活动使用天线 1WIFI_RX_ANT1所有 RX 活动使用天线 2WIFI_RX_ANT_AUTO自动选择 RX 天线。tx_mode可选值WiFiGeneric.hWIFI_TX_ANT0所有 TX 活动使用天线 1WIFI_TX_ANT1所有 TX 活动使用天线 2WIFI_TX_ANT_AUTO自动选择 TX 天线。双天线扫描的完整用法可参考 WiFiScanDualAntenna.ino 示例。四、WiFiAP配置与管理 Soft-APWiFiAP用于配置和管理 ESP32 作为接入点AP运行所有相关函数集中于此。4.1 基本用法启动 Wi-Fi 接入点只需一行代码WiFi.softAP(ssid, password);完整示例见 WiFiAccessPoint.ino。该示例还展示了软 AP 的经典配套用法在192.168.4.1上启动一个NetworkServer客户端通过浏览器访问http://192.168.4.1/H与http://192.168.4.1/L即可远程开关 LED。4.2 softAP配置 AP 特性bool softAP(const char* ssid, const char* passphrase NULL, int channel 1, int ssid_hidden 0, int max_connection 4, bool ftm_responder false);参数说明参数含义说明ssidWi-Fi 网络 SSID最长 63 字符passphraseWi-Fi 密码开放网络设为NULLWPA2 密码最短 8 字符channelWi-Fi 信道范围 1–13ssid_hidden是否隐藏网络0 广播 SSID1 隐藏 SSIDmax_connection最大并发连接数默认 4范围 1–4ftm_responderFTM 响应方特性仅 ESP32-S2 与 ESP32-C3 SoC 支持配置成功返回true。从源码实现看WiFiAP.cppsoftAP实际上是AP.begin()与AP.create()的组合调用并且create内部还带有默认的认证模式WIFI_AUTH_WPA2_PSK与加密方式WIFI_CIPHER_TYPE_CCMP见 WiFiAP.h。F- TM 相关完整示例见 FTM_Responder.ino。4.3 softAPConfig配置静态 IP 等网络参数用于将 AP 的 IP 配置为静态固定同时设置网关与子网掩码bool softAPConfig(IPAddress local_ip, IPAddress gateway, IPAddress subnet);local_ip设置本地 IP 地址gateway设置网关 IPsubnet设置子网掩码。配置成功返回true。源码中该函数还支持额外的dhcp_lease_start与dns参数见 WiFiAP.h未指定时使用默认值。4.4 AP 连接管理函数softAPdisconnect强制断开 AP。bool softAPdisconnect(bool wifioff false);wifioff设为true时同时关闭 Wi-Fi 无线电。从 WiFiAP.cpp 的实现可见该函数会先清除 AP 配置AP.clear()再根据wifioff决定是否调用AP.end()彻底关闭。softAPgetStationNum返回连接到 AP 的客户端数量。uint8_t softAPgetStationNum();softAPIP获取 AP 的 IPv4 地址。IPAddress softAPIP();softAPBroadcastIP获取 AP 的 IPv4 广播地址。IPAddress softAPBroadcastIP();softAPNetworkID获取 softAP 网络地址网络 ID。IPAddress softAPNetworkID();softAPSubnetCIDR获取 softAP 子网的 CIDR 前缀长度。uint8_t softAPSubnetCIDR();softAPSubnetMask获取 softAP 子网掩码。IPAddress softAPSubnetMask();softAPenableIPv6启用 IPv6 支持需在配置中开启CONFIG_LWIP_IPV6。bool softAPenableIPv6(bool enabletrue);配置成功返回true。softAPlinkLocalIPv6获取 AP 的 IPv6 链路本地地址。IPAddress softAPlinkLocalIPv6();softAPgetHostname / softAPsetHostname获取 / 设置 AP 主机名。const char * softAPgetHostname(); bool softAPsetHostname(const char * hostname);softAPmacAddress设置或获取 AP 的 MAC 地址提供两种重载。uint8_t* softAPmacAddress(uint8_t* mac); // 设置 MAC写入 mac 数组 String softAPmacAddress(void); // 获取 MAC返回字符串softAPSSID获取 AP 的 SSID。String softAPSSID(void) const;五、WiFiSTA配置与管理 StationWiFiSTA用于配置和管理 ESP32 作为站点Station运行。5.1 基本用法WiFi.begin(ssid, password);其中ssid和password来自你要连接的 Wi-Fi 网络。检查连接是否成功while (WiFi.status() ! WL_CONNECTED) { delay(500); Serial.print(.); }连接成功后打印网络分配的 IP 地址Serial.println(IP address: ); Serial.println(WiFi.localIP());完整示例见 WiFiClient.ino——该示例演示了连接 Wi-Fi 后通过NetworkClient向 ThingSpeak 云平台写入/读取数据的完整流程。5.2 begin配置并启动 Wi-Fibegin系列函数用于配置并启动 Wi-Fi提供多种重载wl_status_t begin(const char* ssid, const char *passphrase NULL, int32_t channel 0, const uint8_t* bssid NULL, bool tryConnect true);参数说明ssid设置 AP 的 SSIDpassphrase设置 AP 密码开放网络设为NULLchannel设置 Wi-Fi 信道bssid设置 AP 的 BSSID绑定指定 APtryConnect设为true时自动连接已配置的网络。另有等价的重载版本接受char*类型wl_status_t begin(char* ssid, char *passphrase NULL, int32_t channel 0, const uint8_t* bssid NULL, bool tryConnect true);注意begin函数也接受String类型的ssid与passphrase参数提供与 ArduinoString对象配合的便捷重载见 WiFiSTA.h。配置完成后可用无参版本启动连接wl_status_t begin();5.3 connect主动发起连接connect用于连接到 Wi-Fi 网络。它会被begin内部调用也可以直接使用以获得更多控制权bool connect(const char* ssid, const char *passphrase NULL, int32_t channel 0, const uint8_t* bssid NULL, bool tryConnect true);参数含义与begin完全一致同样支持String重载。5.4 config配置静态 IPconfig用于配置 Wi-Fi 网络参数静态 IP 等。配置完成后可调用begin启动 Wi-Fi 流程bool config(IPAddress local_ip, IPAddress gateway, IPAddress subnet, IPAddress dns1 (uint32_t)0x00000000, IPAddress dns2 (uint32_t)0x00000000);local_ip设置本地 IPgateway设置网关 IPsubnet设置子网掩码dns1设置主 DNSdns2设置备用 DNS。配置成功返回true。IPAddress格式由 4 个字节定义IPAddress(uint8_t first_octet, uint8_t second_octet, uint8_t third_octet, uint8_t fourth_octet);示例IPAddress local_ip(192, 168, 10, 20);静态 IP 的完整用法参见 WiFiClientStaticIP.ino。5.5 连接状态与重连管理reconnect重新连接 Wi-Fi。bool reconnect();disconnect强制断开连接。bool disconnect(bool wifioff false, bool eraseap false);wifioff设为true关闭 Wi-Fi 无线电eraseap设为true从 NVS 存储器中擦除 AP 配置下次上电不再自动重连。配置成功返回true。源码中该函数还支持第三个可选参数timeoutLength默认 100ms见 WiFiSTA.h。isConnected获取连接状态。bool isConnected();返回连接状态true表示已连接。setAutoConnect / getAutoConnect这两个函数已弃用deprecated不建议在新代码中使用。setAutoReconnect设置连接丢失后的自动重连。bool setAutoReconnect(bool autoReconnect);autoConnect设为true以启用该选项。getAutoReconnect查询自动重连是否开启。bool getAutoReconnect();返回true表示该设置已启用。setMinSecurity设置 AP 可被连接的最低安全等级。bool setMinSecurity(wifi_auth_mode_t minSecurity);minSecurity为最低可连接安全模式默认值为WIFI_AUTH_WPA2_PSK。从 WiFiSTA.h 的注释可知该函数必须在WiFi.begin()之前调用同组的还有setScanMethod默认WIFI_FAST_SCAN与setSortMethod默认WIFI_CONNECT_AP_BY_SIGNAL。六、WiFiMulti多热点自动切换WiFiMulti允许你在 STA 模式下为 AP 连接添加多个候选网络库会自动处理连接与切换逻辑非常适合设备在家连家庭路由、外出连手机热点的便携场景。6.1 添加候选 APbool addAP(const char *ssid, const char *passphrase NULL);可以添加多个 AP库会按优先级尝试连接。如果启用了 WPA2-Enterprise 支持CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT还提供带用户名与匿名身份的扩展重载bool addAP(const char *ssid, const char *passphrase NULL, const char *username NULL, const char *identity NULL);针对不同网络类型的参数填写规则开放网络只需设置ssid口令网络如 WPA2-PSK必须设置ssid与passphraseWPA2-EnterprisePEAPv0/EAP-MSCHAPv2username与passphrase分别设置为内层认证MSCHAPv2所需的用户名和密码identity设置为 PEAP 所需的匿名身份若网络无要求则设为空字符串。需要特别说明的限制源码注释亦明确见 WiFiMulti.h基于证书的 WPA2-Enterprise如 EAP-TLS目前不受支持且当前无法为 PEAP 提供 CA 证书来校验服务器证书。鉴于这些限制请自行评估该方案是否满足你的安全需求。从源码实现看WiFiMulti.cppaddAP会对入参做校验SSID 缺失或超过 31 字符、passphrase 超过 63 字符都会拒绝添加并返回false。6.2 运行多 AP 连接添加完 AP 后调用run启动连接流程uint8_t run(uint32_t connectTimeout5000);connectTimeout为每次连接尝试的超时时间毫秒默认 5000。WiFiMulti还提供了setStrictMode默认true仅保持/连接列表内的 AP、setAllowOpenAP默认false禁止连接不在列表中的开放 AP等高级控制见 WiFiMulti.h。使用示例参考 WiFiMulti.ino、WiFiMultiAdvanced.ino 与 WiFiMultiEnterprise.ino。七、WiFiScan扫描周围网络执行 Wi-Fi 网络扫描可使用以下函数声明见 WiFiScan.h。scanNetworks开始扫描可用的 Wi-Fi 网络。int16_t scanNetworks(bool async false, bool show_hidden false, bool passive false, uint32_t max_ms_per_chan 300, uint8_t channel 0);async设为true时异步扫描立即返回show_hidden是否扫描隐藏网络passive是否使用被动扫描更省电但更慢max_ms_per_chan每个信道最多停留的毫秒数默认 300channel限定扫描的信道0表示扫描所有信道。scanComplete在异步模式下获取扫描状态/结果数量。int16_t scanComplete();扫描进行中返回WIFI_SCAN_RUNNING完成后返回找到的网络数量。scanDelete从 RAM 中删除上一次的扫描结果释放内存。void scanDelete();getNetworkInfo将扫描到的网络信息加载到指针参数中。bool getNetworkInfo(uint8_t networkItem, String ssid, uint8_t encryptionType, int32_t RSSI, uint8_t* BSSID, int32_t channel);此外 WiFiScan.h 还提供SSID(uint8_t)、encryptionType(uint8_t)、RSSI(uint8_t)、BSSID(uint8_t)、channel(uint8_t)等按索引读取扫描结果的便捷方法。完整示例见 WiFiScan.ino 与 WiFiScanAsync.ino。若需要进一步控制扫描行为还可参考 WiFiScanTime.ino基于setScanActiveMinTime/setScanTimeout调整扫描时间。八、示例清单与进一步阅读Wi-Fi 库的全部示例位于 libraries/WiFi/examples涵盖本文提到的 AP、STA、事件、多热点、扫描、FTM、WPS、SmartConfig、IPv6 与双天线等全部功能。其中官方文档重点推荐的三个入门示例为示例文件学习要点Wi-Fi AP 示例WiFiAccessPoint.inosoftAP建热点 内置 Web 服务器Wi-Fi STA 示例WiFiClient.inobegin连网 NetworkClient发起 HTTP 请求Wi-Fi 事件示例WiFiClientEvents.inoonEvent注册三种回调、事件枚举与 info 使用事件类型的完整枚举与 info 子结构清单可进一步查阅 WiFiGeneric.h其中WiFiEventCb、WiFiEventSysCb等别名统一映射到网络层Network模块的对应类型以便为你的应用挑选精确的事件订阅粒度。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考