章节导航#

• 本章重要 API 函数
• 学习前后依赖
• 1. 概述
• 2. 本章目录结构
• 3. 软件架构传递树
  • 3.1 模块调用关系
  • 3.2 Wi-Fi 事件流
• 4. 代码讲解
  • 4.1 main/main.c — 程序入口
  • 4.2 components/WIFISTA/wifista.h — 账号配置头文件
  • 4.3 components/WIFISTA/wifista.c — 事件驱动的 STA 模块
  • 4.4 为什么 Wi-Fi 必须先初始化 NVS
  • 4.5 为什么获取 IP 要走 IP_EVENT，而不是 WIFI_EVENT_STA_CONNECTED
• 5. 时序流程图
  • 5.1 启动到联网的完整时序
  • 5.2 断开连接后的处理逻辑
• 6. STA 模式的本质
• 7. 与前一章 Wi-Fi 原理笔记的衔接
• 容易踩坑
• 8. 本章小结
• Tips

3.1 模块调用关系#

1
app_main()                                      [main/main.c]
2
  ├── nvs_flash_init()                          [ESP-IDF: nvs_flash]
3
  │     └── 初始化 NVS 分区，供 Wi-Fi 驱动读写参数
4
  │
5
  ├── lcd_init()                                [components/LCD/lcd.c]
6
  │     └── 初始化 LCD 显示屏
7
  │
8
  ├── wifista_init()                            [components/WIFISTA/wifista.c]
9
  │     ├── esp_netif_init()                    初始化网络接口层
10
  │     ├── esp_event_loop_create_default()     创建默认事件循环
11
  │     ├── esp_event_handler_register()        注册 Wi-Fi / IP 事件回调
12
  │     ├── esp_netif_create_default_wifi_sta() 创建默认 STA 接口
13
  │     ├── esp_wifi_init()                     初始化 Wi-Fi 驱动
14
  │     ├── esp_wifi_set_mode(WIFI_MODE_STA)    设为 STA 模式
15
  │     ├── esp_wifi_set_config()               写入 SSID / 密码
16
  │     └── esp_wifi_start()                    启动 Wi-Fi 驱动
17
  │
18
  └── while(1)
19
        └── vTaskDelay(500)                     主任务空转等待事件

可以看出，本工程采用的是 “主任务做初始化，后续工作交给事件回调” 的结构。真正的联网动作不是在 while(1) 中轮询完成的，而是由 ESP-IDF 内部的事件系统推动的。

3.2 Wi-Fi 事件流#

1
esp_wifi_start()
2
   │
3
   ▼
4
WIFI_EVENT_STA_START
5
   │
6
   └── 回调中调用 esp_wifi_connect()
7
          │
8
          ▼
9
WIFI_EVENT_STA_CONNECTED
10
   │
11
   └── LCD 显示 "connected"
12
          │
13
          ▼
14
DHCP 获取 IP
15
          │
16
          ▼
17
IP_EVENT_STA_GOT_IP
18
   │
19
   └── 解析 event_data 中的 IP 地址
20
       并显示到 LCD 第二行

断开连接时则会走另一条分支：

1
WIFI_EVENT_STA_DISCONNECTED
2
   │
3
   ├── LCD 显示 "disconnected"
4
   └── esp_wifi_stop()

4.1 main/main.c — 程序入口#

main.c 很短，但顺序非常关键：

1
void app_main(void)
2
{
3
    nvs_flash_init();
4
    lcd_init();
5
    wifista_init();
6
    while (1)
7
    {
8
        vTaskDelay(500);
9
    }
10
}

执行顺序解释如下：

这里体现了 ESP-IDF 的一个非常重要的风格：

• 初始化阶段在 app_main() 完成；
• 运行阶段由驱动任务、事件循环、协议栈接管；
• 用户主循环往往只是一个空闲等待，不负责轮询网络状态。

4.2 components/WIFISTA/wifista.h — 账号配置头文件#

wifista.h 只定义了三个内容：

1
#define DEFAULT_SSID "your_ssid"
2
#define DEFAULT_PWD  "your_password"
3

4
void wifista_init(void);

这说明当前项目把路由器账号信息直接硬编码进了头文件中。

优点：

• 示例工程简单直观；
• 不需要菜单配置或串口输入。

缺点：

• 账号密码直接写在源码里，不适合正式项目；
• 改 Wi-Fi 时必须重新编译固件；
• 安全性差，源码泄露就等于密码泄露。

本章作为教学示例是可以接受的，但后续正式项目更推荐：

• 用 menuconfig 配置；
• 或用 NVS 保存配网结果；
• 或通过 AP 配网页面动态写入。

4.3 components/WIFISTA/wifista.c — 事件驱动的 STA 模块#

wifista.c 可以分成两部分：

1. 事件处理函数 wifista_event_handler()
2. 初始化函数 wifista_init()

1
void wifista_event_handler(void* event_handler_arg,
2
                           esp_event_base_t event_base,
3
                           int32_t event_id,
4
                           void* event_data)

1
if(event_id == WIFI_EVENT_STA_START)
2
{
3
    esp_wifi_connect();
4
}

1
else if(event_id == WIFI_EVENT_STA_CONNECTED)
2
{
3
    lcd_show_string(1,1,"connected   ",YELLOW,BLACK);
4
}

1
else if(event_id == WIFI_EVENT_STA_DISCONNECTED)
2
{
3
    lcd_show_string(1,1,"disconnected",YELLOW,BLACK);
4
    esp_wifi_stop();
5
}

1
esp_wifi_connect();

1
if(event_id == IP_EVENT_STA_GOT_IP)
2
{
3
    esp_netif_ip_info_t *event = (esp_netif_ip_info_t *)event_data;
4
    lcd_show_num(2,1,esp_ip4_addr1_16(&event->ip),3,GREEN,BLACK);
5
    lcd_show_string(2,4,".",GREEN,BLACK);
6
    lcd_show_num(2,5,esp_ip4_addr2_16(&event->ip),3,GREEN,BLACK);
7
    lcd_show_string(2,8,".",GREEN,BLACK);
8
    lcd_show_num(2,9,esp_ip4_addr3_16(&event->ip),3,GREEN,BLACK);
9
    lcd_show_string(2,12,".",GREEN,BLACK);
10
    lcd_show_num(2,13,esp_ip4_addr4_16(&event->ip),3,GREEN,BLACK);
11
}

1
esp_netif_ip_info_t *

1
192.168.1.102

1
void wifista_init()
2
{
3
    esp_netif_init();
4
    esp_event_loop_create_default();
5
    esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID,&wifista_event_handler, NULL);
6
    esp_event_handler_register(IP_EVENT,IP_EVENT_STA_GOT_IP,&wifista_event_handler,NULL);
7
    esp_netif_create_default_wifi_sta();
8

9
    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
10
    esp_wifi_init(&cfg);
11

12
    esp_wifi_set_mode(WIFI_MODE_STA);
13

14
    wifi_config_t wifista_config = {
15
        .sta = {
16
            .ssid = DEFAULT_SSID,
17
            .password = DEFAULT_PWD,
18
        }
19
    };
20
    esp_wifi_set_config(WIFI_IF_STA, &wifista_config);
21

22
    esp_wifi_start();
23
}

1
esp_netif_init();

1
esp_event_loop_create_default();

1
esp_event_handler_register(WIFI_EVENT, ESP_EVENT_ANY_ID, &wifista_event_handler, NULL);
2
esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &wifista_event_handler, NULL);

1
esp_netif_create_default_wifi_sta();

1
wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
2
esp_wifi_init(&cfg);
3

4
esp_wifi_set_mode(WIFI_MODE_STA);

1
wifi_config_t wifista_config = {
2
    .sta = {
3
        .ssid = DEFAULT_SSID,
4
        .password = DEFAULT_PWD,
5
    }
6
};

1
esp_wifi_set_config(WIFI_IF_STA, &wifista_config);

1
esp_wifi_start();

1
WIFI_EVENT_STA_START

4.4 为什么 Wi-Fi 必须先初始化 NVS#

在 main.c 中，nvs_flash_init() 被放在最前面，这不是随便写的顺序。

ESP-IDF 的 Wi-Fi 驱动依赖 NVS 保存和读取以下信息：

• PHY 校准数据
• 国家/信道配置
• 某些 Wi-Fi 驱动内部参数
• 后续若开启 Wi-Fi 存储模式，也会保存 AP 信息

因此，正确顺序必须是：

1
NVS 初始化成功
2
   ↓
3
Wi-Fi 驱动初始化
4
   ↓
5
STA 配置与连接

如果跳过 NVS，常见结果包括：

• esp_wifi_init() 失败；
• Wi-Fi 行为异常；
• 获取不到正常的射频校准参数。

4.5 为什么获取 IP 要走 IP_EVENT，而不是 WIFI_EVENT_STA_CONNECTED#

这是初学者最容易混淆的一点。

两者的区别如下：

也就是说：

1
先有 STA_CONNECTED
2
后有 GOT_IP

中间还隔着 DHCP 协议过程。

因此，正确的工程实践是：

• STA_CONNECTED：提示”已经连上路由器”
• GOT_IP：提示”现在真的能上网了”

本项目正是按照这个逻辑设计的。

5.1 启动到联网的完整时序#

1
app_main()
2
   │
3
   ├── nvs_flash_init()
4
   │
5
   ├── lcd_init()
6
   │
7
   ├── wifista_init()
8
   │     │
9
   │     ├── esp_netif_init()
10
   │     ├── esp_event_loop_create_default()
11
   │     ├── 注册 Wi-Fi / IP 事件回调
12
   │     ├── esp_netif_create_default_wifi_sta()
13
   │     ├── esp_wifi_init()
14
   │     ├── esp_wifi_set_mode(WIFI_MODE_STA)
15
   │     ├── esp_wifi_set_config()
16
   │     └── esp_wifi_start()
17
   │            │
18
   │            ▼
19
   │      WIFI_EVENT_STA_START
20
   │            │
21
   │            └── esp_wifi_connect()
22
   │                     │
23
   │                     ▼
24
   │              WIFI_EVENT_STA_CONNECTED
25
   │                     │
26
   │                     └── LCD 第一行显示 "connected"
27
   │
28
   │              DHCP 自动申请地址
29
   │                     │
30
   │                     ▼
31
   │              IP_EVENT_STA_GOT_IP
32
   │                     │
33
   │                     └── LCD 第二行显示 IPv4 地址
34
   │
35
   └── while(1)
36
         └── vTaskDelay(500)

5.2 断开连接后的处理逻辑#

1
Wi-Fi 已连接
2
   │
3
   ▼
4
发生断开（路由器掉电 / 密码错误 / 信号太弱）
5
   │
6
   ▼
7
WIFI_EVENT_STA_DISCONNECTED
8
   │
9
   ├── LCD 显示 "disconnected"
10
   └── esp_wifi_stop()
11
          │
12
          └── Wi-Fi 驱动停止

这个项目没有做自动重连，因此它更像一个一次性联网状态演示，而不是可长期运行的稳定联网框架。

本章最易忽视的细节#

1. esp_wifi_start() 不会自动联网：很多初学者以为调了 esp_wifi_start() 就等于连上 Wi-Fi 了。实际上这只是启动驱动，真正连接需要额外调用 esp_wifi_connect()。最佳实践是在 WIFI_EVENT_STA_START 回调中调用它——因为这时驱动才真正就绪。
2. CONNECTED 之后不能立刻发 HTTP 请求：必须等 IP_EVENT_STA_GOT_IP。即便 CONNECTED 事件触发了，DHCP 可能还需要几百毫秒到几秒才能完成。如果在这期间发起 TCP 连接，socket 会因为没有 IP 而失败。
3. 回调函数签名不能写错：事件回调必须是 void handler(void*, esp_event_base_t, int32_t, void*) 这四个参数，顺序也不能错。如果写错了签名，编译不会报错（因为函数指针强转），但运行时 event_data 指向的地址会完全错乱。
4. ESP_EVENT_ANY_ID 意味着所有 Wi-Fi 事件都进同一个回调：你必须在回调里用 if-else 或 switch 按 event_id 分发。如果忘了判断 event_id，可能会导致一个事件的处理逻辑被错误地执行到另一个事件上。

踩坑记录#

• STA 连上了但 IP_EVENT_STA_GOT_IP 不触发：如果网段内有多个 DHCP Server，或者路由器 DHCP 池已满，ESP32 可能一直拿不到 IP。用串口工具看日志，Wi-Fi 驱动通常会打印 DHCP 超时信息。
• 回调里调用阻塞函数导致系统卡死：事件回调是运行在事件循环任务中的，如果你在回调里写 vTaskDelay(5000) 或死等某个条件，事件循环会被堵住，后续所有 Wi-Fi/IP 事件都无法处理。事件回调必须尽可能快、不阻塞。
• 密码错误时事件流完全不同：如果密码错误，事件流是 STA_START → STA_DISCONNECTED，中间不会有 STA_CONNECTED。Wi-Fi 驱动默认会重试几次再放弃，所以你会看到多次 DISCONNECTED 事件。

事件驱动模型的设计原因（为什么不用轮询）#

初学者有时候会问：为什么不在 while(1) 里轮询 Wi-Fi 状态？像这样：

1
while(1) {
2
    if (wifi_is_connected()) { ... }
3
    vTaskDelay(100);
4
}

ESP-IDF 选择事件驱动而不是轮询的原因有三个层次：

层次一：功耗。 Wi-Fi 芯片（不管是内置还是外置）查询状态的寄存器操作本身就会唤醒芯片，频繁轮询意味着射频部分永远不能真正休眠。事件驱动下，没有事件时 Wi-Fi 子系统可以进入省电模式。

层次二：实时性。 Wi-Fi 事件的发生时机不可预测——连接成功可能在 100ms 后，也可能在 5 秒后。轮询周期如果设太长（比如 2 秒），事件响应延迟也至少 2 秒；设太短（比如 10ms），CPU 大部分时间都在做无效轮询。事件驱动在事件发生的那一刻回调，延迟接近 0。

层次三：数据完整性。 IP_EVENT_STA_GOT_IP 携带的 esp_netif_ip_info_t 数据结构是瞬时的——如果你不在回调里立刻读取，这个指针指向的内存可能已经被协议栈回收，之后轮询时读到的就是垃圾数据。

所以事件驱动不是”一种风格选择”，而是 实时性与低功耗的双重需求 共同决定的架构选择。

WIFI_EVENT vs IP_EVENT 的层次边界#

这是需要牢记的一张分层地图：

1
        ┌──────────────────────────┐
2
        │      应用层（HTTP/MQTT）   │ ← 你的业务代码
3
        ├──────────────────────────┤
4
        │      传输层（TCP/UDP）     │
5
        ├──────────────────────────┤
6
        │   IP_EVENT               │ ← 网络层事件
7
        │   - STA_GOT_IP           │    DHCP 完成，拿到 IP
8
        │   - STA_LOST_IP          │    IP 地址失效
9
        ├──────────────────────────┤
10
        │   WIFI_EVENT             │ ← 链路层事件
11
        │   - STA_START            │    驱动启动完成
12
        │   - STA_CONNECTED        │    802.11 关联成功
13
        │   - STA_DISCONNECTED     │    断开关联
14
        ├──────────────────────────┤
15
        │   硬件层（射频/PHY）       │
16
        └──────────────────────────┘

记住这条规则：

• WIFI_EVENT 告诉你”射频连上了没”
• IP_EVENT 告诉你”网络通了没”

两者之间隔着 DHCP 协议、ARP 解析、可能还有 802.1X 认证。所以在回调里要分层判断——先看 event_base 是 WIFI_EVENT 还是 IP_EVENT，再看具体 event_id。

与后续章节的知识衔接#

STA 模式是 ESP32 联网的第一步，后续章节的依赖关系如下：

• Wi-Fi AP 模式（第 22 章）：与 STA 模式共用同一套 esp_netif/esp_event 框架，只是角色互换。理解 STA 的事件驱动模型后，AP 模式的事件处理几乎可以照搬。
• NTP 校时（第 23 章）：必须在 STA 拿到 IP 之后才能初始化 SNTP 客户端，因为 SNTP 需要向公网 NTP 服务器发 UDP 包。本章的 IP_EVENT_STA_GOT_IP 就是 NTP 章节的启动前置条件。
• MQTT / HTTP：这两类应用层协议都建立在 TCP 之上，而 TCP 连接的前提是 STA 已有有效 IP。因此它们的初始化代码都应该放在 IP_EVENT_STA_GOT_IP 回调中，而不是 app_main() 的尾部。

设计决策思考：WIFI_INIT_CONFIG_DEFAULT() 做了什么#

很多教程直接写 WIFI_INIT_CONFIG_DEFAULT() 就过去了，但它背后实际上配置了：

• Wi-Fi 任务的核心绑定（通常默认不绑定）
• Wi-Fi 任务的优先级
• Wi-Fi 任务的栈大小
• 射频校准数据的存储方式
• NVS 中 Wi-Fi 参数的命名空间

对于大多数入门项目，默认参数足够。但如果你遇到以下情况就需要自定义：

• 大量并发 TCP 连接：Wi-Fi 任务栈可能不够，需要调大
• 实时性要求高：需要提高 Wi-Fi 任务的优先级
• 省电敏感场景：可能需要配置省电模式参数

这些都可以通过自定义 wifi_init_config_t 来实现，而不是永远用默认值。