【产出】 > 用 Arduino-ESP32 的 WiFi 库让 ESP32 以 STA 模式连上路由器、拿到 IP,路由器重启或信号中断后能自己连回来,并用事件回调掌握每一次连接、断开和断开原因。
【版本】 > 依据 arduino-esp32 官方文档"Wi-Fi API"一章,以及 github.com/espressif/arduino-esp32 主分支 WiFi 库源码(WiFiSTA.h、STA.cpp、WiFiGeneric.h/.cpp、WiFiType.h)和官方例程 WiFiClientEvents.ino 编写,适用于 arduino-esp32 3.x。
一、先弄清 STA 模式和频段限制
ESP32 的 Wi-Fi 有两种基本工作方式:
| 模式 | 作用 | 典型用途 |
|---|---|---|
| STA(Station,客户端) | ESP32 作为终端去连路由器 | 上传数据到服务器、接入家里的局域网 |
| AP(Soft-AP,热点) | ESP32 自己开一个热点,让手机等设备连进来 | 配网页面、现场调试 |
本文只讲 STA。要上互联网就用这个模式。
【注意】 > ESP32 的 Wi-Fi 只工作在 2.4 GHz 频段,看不到也连不上 5 GHz 网络。很多双频路由器默认把 2.4 GHz 和 5 GHz 合并成同一个名称("双频合一"),手机能连、ESP32 偶尔连不上,这时在路由器后台把 2.4 GHz 单独起一个名字最稳妥。其他型号的乐鑫芯片支持哪些频段,以该芯片的规格书为准。
另外,WiFi 库默认的最低安全等级是 WIFI_AUTH_WPA2_PSK。路由器如果还在用 WEP 或 WPA(第一代),默认会被认为"不可连接",需要调用 WiFi.setMinSecurity() 放宽,或者更建议把路由器改成 WPA2/WPA3。
二、最小连接程序
#include <WiFi.h>
const char *WIFI_SSID = "你的WiFi名称";
const char *WIFI_PASS = "你的WiFi密码";
void setup() {
Serial.begin(115200);
WiFi.mode(WIFI_STA); // 只开 STA,不顺带开热点
WiFi.begin(WIFI_SSID, WIFI_PASS);
Serial.print("正在连接");
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("已连接,IP 地址:");
Serial.println(WiFi.localIP());
}
void loop() {
}
这段代码能跑,但有一个明显缺陷:密码错了或者路由器不在,就会永远卡在 while 循环里,后面的程序一行都不执行。实际项目要加超时,见第四节。
三、begin() 的参数和连接状态
WiFi.begin() 的完整形式是:
wl_status_t begin(const char* ssid,
const char* passphrase = NULL,
int32_t channel = 0,
const uint8_t* bssid = NULL,
bool tryConnect = true);
| 参数 | 含义 |
|---|---|
ssid | 网络名称 |
passphrase | 密码,开放网络传 NULL |
channel | 指定信道,0 表示不指定 |
bssid | 指定连接某一台路由器的 MAC 地址(同名网络有多个 AP 时有用),NULL 表示不指定 |
tryConnect | true 时配置完立刻发起连接 |
ssid 和 passphrase 也接受 Arduino 的 String 类型。
WiFi.status() 的返回值定义在 WiFiType.h 里:
| 常量 | 值 | 含义 |
|---|---|---|
WL_IDLE_STATUS | 0 | 空闲,正在尝试 |
WL_NO_SSID_AVAIL | 1 | 找不到这个 SSID(名字写错、路由器关了、或者是 5 GHz 网络) |
WL_SCAN_COMPLETED | 2 | 扫描完成 |
WL_CONNECTED | 3 | 已连接并拿到 IP |
WL_CONNECT_FAILED | 4 | 连接失败,常见于密码错误 |
WL_CONNECTION_LOST | 5 | 连接丢失(如信标超时) |
WL_DISCONNECTED | 6 | 已断开 |
WL_STOPPED | 254 | Wi-Fi 未启动 |
判断"能不能上网"一律看 WL_CONNECTED,也可以用 WiFi.isConnected()。
四、带超时的连接
库里提供了 WiFi.waitForConnectResult(timeoutLength),默认超时 60000 ms。它每 100 ms 查一次状态,状态变成已连接或明确失败、或者超时,就返回当前状态。用它可以把连接写成:
bool connectWiFi(uint32_t timeoutMs) {
WiFi.mode(WIFI_STA);
WiFi.begin(WIFI_SSID, WIFI_PASS);
uint8_t st = WiFi.waitForConnectResult(timeoutMs);
if (st == WL_CONNECTED) {
Serial.printf("已连接,IP=%s,RSSI=%d dBm\n",
WiFi.localIP().toString().c_str(), WiFi.RSSI());
return true;
}
Serial.printf("连接失败,状态码 %u\n", st);
return false;
}
连接失败后程序继续往下走,可以选择点个灯报错、进入配网模式,或者稍后再试。
五、断线后会不会自己连回来
会,但有条件。WiFi 库内置了自动重连,开关是 WiFi.setAutoReconnect(bool),源码里默认是打开的。读一下 STA.cpp 里处理断开事件的逻辑,可以总结出它的行为:
| 情况 | 库的处理 |
|---|---|
程序主动调用 WiFi.disconnect()(断开原因为 ASSOC_LEAVE) | 不重连 |
begin() 之后的第一次连接失败 | 不管什么原因,都再试一次 |
| 已经连上过、之后断开,且自动重连开着 | 只有原因在"可重连"列表里才重连,比如信标超时、握手超时、找不到 AP、认证过期等 |
| 认证失败(通常是密码错) | 不在可重连列表里,第一次重试之后就不再尝试,状态变为 WL_CONNECT_FAILED |
所以,路由器重启这类情况,库一般会自己连回来;但如果长时间没连上(比如路由器断电半小时),或者遇到不在列表里的断开原因,就可能停在断开状态不再动。工程上的做法是在内置重连之外,再加一层自己的看门狗:
const uint32_t RETRY_INTERVAL_MS = 10000; // 断线后每 10 秒检查一次,可按需调整
uint32_t lastCheck = 0;
void loop() {
if (millis() - lastCheck >= RETRY_INTERVAL_MS) {
lastCheck = millis();
if (WiFi.status() != WL_CONNECTED) {
Serial.println("Wi-Fi 未连接,尝试重连");
WiFi.reconnect(); // 用已保存的配置重新连接
}
}
// 其他业务代码,不要在这里长时间阻塞
}
WiFi.reconnect() 是库提供的重连函数。如果 reconnect() 多次无效,可以退一步,先 WiFi.disconnect() 再 WiFi.begin(WIFI_SSID, WIFI_PASS) 完整重来一遍。
【提示】 > 不要每次
loop()都调用重连。连接本身需要几秒钟,频繁调用会打断正在进行的连接过程,反而永远连不上。用millis()做间隔判断,间隔取 5–30 秒比较合适。
六、用事件回调掌握连接状态
轮询 status() 只能看到"现在怎样",事件回调可以在状态变化的那一刻通知你,还能拿到断开原因码。注册函数是 WiFi.onEvent(),有三种写法:
// 1. 只拿事件 ID
void cb1(arduino_event_id_t event);
// 2. 拿事件 ID 和附加信息
void cb2(arduino_event_id_t event, arduino_event_info_t info);
// 3. 拿一个包含两者的结构体指针
void cb3(arduino_event_t *e);
onEvent() 的第二个参数是事件类型,默认 ARDUINO_EVENT_MAX 表示所有事件都回调;传入具体事件就只订阅那一种。返回值是一个 ID,以后可以用 WiFi.removeEvent(id) 取消。
STA 相关的常用事件:
| 事件 | 触发时机 |
|---|---|
ARDUINO_EVENT_WIFI_STA_START | STA 接口启动 |
ARDUINO_EVENT_WIFI_STA_CONNECTED | 和路由器完成关联(此时还没有 IP) |
ARDUINO_EVENT_WIFI_STA_GOT_IP | DHCP 分到 IP,到这一步才算能通信 |
ARDUINO_EVENT_WIFI_STA_DISCONNECTED | 与路由器断开,附加信息里有原因码 |
ARDUINO_EVENT_WIFI_STA_LOST_IP | IP 失效,被清零 |
【注意】 > 回调函数运行在 Wi-Fi 库自己的 FreeRTOS 任务里,和
setup()/loop()不在同一个线程。官方文档的要求是:回调必须线程安全,不能不加锁直接改共享变量;WiFi.onEvent()和WiFi.removeEvent()不是线程安全的,不能在回调里调用。Serial.print()是线程安全的,可以用来打日志。比较稳妥的做法是回调里只设置标志位,真正的处理放到loop()里。
七、完整示例:超时连接 + 事件 + 断线重连
#include <WiFi.h>
const char *WIFI_SSID = "你的WiFi名称";
const char *WIFI_PASS = "你的WiFi密码";
const uint32_t CONNECT_TIMEOUT_MS = 15000;
const uint32_t RETRY_INTERVAL_MS = 10000;
volatile bool gotIp = false; // 回调线程写、loop 读,单字节 bool 读写是原子的
volatile uint8_t lastReason = 0;
uint32_t lastCheck = 0;
void onWiFiEvent(arduino_event_id_t event, arduino_event_info_t info) {
switch (event) {
case ARDUINO_EVENT_WIFI_STA_CONNECTED:
Serial.println("[事件] 已关联路由器,等待分配 IP");
break;
case ARDUINO_EVENT_WIFI_STA_GOT_IP:
Serial.print("[事件] 获得 IP:");
Serial.println(IPAddress(info.got_ip.ip_info.ip.addr));
gotIp = true;
break;
case ARDUINO_EVENT_WIFI_STA_DISCONNECTED:
lastReason = info.wifi_sta_disconnected.reason;
Serial.printf("[事件] 断开,原因码 %u\n", lastReason);
gotIp = false;
break;
case ARDUINO_EVENT_WIFI_STA_LOST_IP:
Serial.println("[事件] IP 失效");
gotIp = false;
break;
default:
break;
}
}
void setup() {
Serial.begin(115200);
WiFi.onEvent(onWiFiEvent); // 在 begin 之前注册,才能收到第一次连接的事件
WiFi.setHostname("esp32-sensor-01"); // 必须在 mode()/begin() 启动 Wi-Fi 之前设置,不超过 32 个字符
WiFi.mode(WIFI_STA);
WiFi.setAutoReconnect(true); // 默认就是 true,写出来便于阅读
WiFi.begin(WIFI_SSID, WIFI_PASS);
if (WiFi.waitForConnectResult(CONNECT_TIMEOUT_MS) != WL_CONNECTED) {
Serial.println("首次连接超时,进入 loop 后继续重试");
}
}
void loop() {
if (millis() - lastCheck >= RETRY_INTERVAL_MS) {
lastCheck = millis();
if (WiFi.status() != WL_CONNECTED) {
Serial.printf("仍未连接(上次原因码 %u),调用 reconnect\n", lastReason);
WiFi.reconnect();
}
}
if (gotIp) {
// 这里放需要联网的业务,例如每隔一段时间上报一次数据
}
}
setHostname() 设置的是 DHCP 上报给路由器的设备名,在路由器的设备列表里能看到。官方文档要求它在 WiFi.begin()、WiFi.mode() 等启动 Wi-Fi 的函数之前调用;已经启动后想改名,需要先 WiFi.mode(WIFI_MODE_NULL) 关掉 Wi-Fi,再设名字、重新启动。不设置时,库会根据芯片型号和 MAC 地址自动生成一个默认名字。
断开原因码是 IEEE 802.11 标准和 ESP-IDF 定义的数字。库提供了 WiFi.disconnectReasonName((wifi_err_reason_t)code) 把它翻译成文字名称,排查时打印出来更直观。
八、固定 IP
需要固定 IP 时,在 begin() 之前调用 config():
IPAddress localIp(192, 168, 1, 50); // 按你的局域网网段修改
IPAddress gateway(192, 168, 1, 1);
IPAddress subnet(255, 255, 255, 0);
IPAddress dns1(192, 168, 1, 1);
WiFi.mode(WIFI_STA);
WiFi.config(localIp, gateway, subnet, dns1);
WiFi.begin(WIFI_SSID, WIFI_PASS);
dns1、dns2 两个参数可省略,但省略后域名解析可能失败。固定 IP 要选在路由器 DHCP 分配范围之外,避免和别的设备冲突。
九、其他要知道的设置
| 设置 | 说明 |
|---|---|
WiFi.persistent(bool) | 源码中默认 true,Wi-Fi 配置会存进 Flash 的 NVS 区。WiFi.disconnect(false, true) 第二个参数为 true 时会擦除保存的 AP 配置 |
WiFi.setSleep(bool) | Wi-Fi 省电模式。源码中 ESP32 默认开启最小省电模式(WIFI_PS_MIN_MODEM),ESP32-S2 默认关闭。对响应延迟敏感(如做 TCP 服务器)时可以 setSleep(false),代价是电流增大 |
WiFi.setTxPower(WIFI_POWER_xxx) | 发射功率,枚举从 WIFI_POWER_21dBm 到 WIFI_POWER_MINUS_1dBm。供电较弱的板子连接时频繁复位,可以适当降低 |
WiFi.RSSI() | 当前信号强度,单位 dBm,越接近 0 越强 |
WiFi.macAddress() | 本机 STA 的 MAC 地址,路由器做 MAC 绑定时要用 |
WiFiMulti | 预先 addAP() 多组网络,run() 时自动选可用的一个,适合设备会在多个地点使用 |
十、连不上时按这个顺序查
| 现象 | 优先检查 |
|---|---|
一直是 WL_NO_SSID_AVAIL | SSID 大小写、空格是否完全一致;网络是不是 5 GHz;路由器是否隐藏了 SSID |
WL_CONNECT_FAILED | 密码错误;路由器安全模式是否低于 WPA2 |
| 连上又断,反复循环 | 供电不足(Wi-Fi 发射时电流峰值大,详见本站 ESP32 入门教程的供电一节);信号太弱,看 RSSI |
| 能拿到 IP 但访问不了外网 | 固定 IP 时网关或 DNS 填错 |
| 路由器设备列表里显示的名字不对 | setHostname() 调用时机晚了 |
| 路由器开了 MAC 过滤 | 把 WiFi.macAddress() 打印出来加进白名单 |
参考资料
- arduino-esp32 Wi-Fi API 文档:https://docs.espressif.com/projects/arduino-esp32/en/latest/api/wifi.html
- WiFi 库源码目录:https://github.com/espressif/arduino-esp32/tree/master/libraries/WiFi/src
- 官方例程 WiFiClientEvents.ino:https://github.com/espressif/arduino-esp32/blob/master/libraries/WiFi/examples/WiFiClientEvents/WiFiClientEvents.ino
- ESP-IDF 快速入门(ESP32 芯片特性,含 2.4 GHz Wi-Fi):https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html
评价 (0)