章节导航#

• 本章重要 API 函数
• 学习前后依赖
• 1. 概述
• 2. 本章目录结构
• 3. 软件架构传递树
  • 3.1 模块调用关系
  • 3.2 AP 模式事件流
• 4. 代码讲解
  • 4.1 main/main.c — 程序入口
  • 4.2 components/WIFIAP/wifiap.h — 热点账号配置
  • 4.3 components/WIFIAP/wifiap.c — AP 模式初始化与事件处理
  • 4.4 为什么 AP 模式不需要 esp_wifi_connect()
  • 4.5 为什么 AP 模式通常没有 IP_EVENT_STA_GOT_IP
• 5. 时序流程图
  • 5.1 从上电到热点建立的完整流程
  • 5.2 STA 接入与断开的时序
• 6. AP 模式的本质
• 7. STA 与 AP 两章的对照理解
• 容易踩坑
• 8. 本章小结
• Tips

3.1 模块调用关系#

1
app_main()                                      [main/main.c]
2
  ├── nvs_flash_init()                          [ESP-IDF: nvs_flash]
3
  │     └── 初始化 NVS 分区
4
  │
5
  ├── lcd_init()                                [components/LCD/lcd.c]
6
  │     └── 初始化 LCD 显示屏
7
  │
8
  ├── wifiap_init()                             [components/WIFIAP/wifiap.c]
9
  │     ├── esp_netif_init()                    初始化网络接口层
10
  │     ├── esp_event_loop_create_default()     创建默认事件循环
11
  │     ├── esp_event_handler_register()        注册 Wi-Fi 事件回调
12
  │     ├── esp_netif_create_default_wifi_ap()  创建默认 AP 网络接口
13
  │     ├── esp_wifi_init()                     初始化 Wi-Fi 驱动
14
  │     ├── esp_wifi_set_mode(WIFI_MODE_AP)     设为 AP 模式
15
  │     ├── esp_wifi_set_config()               配置热点名称/密码/认证方式
16
  │     ├── esp_wifi_start()                    启动热点
17
  │     └── lcd_show_string()                   显示热点 ID / PWD / STA 状态
18
  │
19
  └── while(1)
20
        └── vTaskDelay(500)                     主任务空转等待事件

这个结构和 20_WIFI_STA 很像，但有两个关键区别：

1. STA 需要主动 connect() 去连路由器；
2. AP 只需要 start() 打开热点，等待别人来连。

3.2 AP 模式事件流#

1
esp_wifi_start()
2
   │
3
   ▼
4
热点开始广播 SSID: ESP32S3-AP
5
   │
6
   ├── LCD 第一行显示热点名称
7
   ├── LCD 第二行显示热点密码
8
   └── LCD 第三行预留 STA 状态显示
9
          │
10
          ▼
11
外部 STA（手机/电脑）搜索并连接热点
12
          │
13
          ▼
14
WIFI_EVENT_AP_STACONNECTED
15
          │
16
          └── LCD 第三行显示 "connected"
17

18
外部 STA 断开时：
19

20
WIFI_EVENT_AP_STADISCONNECTED
21
          │
22
          └── LCD 第三行显示 "disconnected"

注意，这里感知到的是：

• 谁连上了我的热点；
• 谁又离开了我的热点；

而不是”我连上了谁”。这是 AP 模式和 STA 模式在事件语义上的根本差异。

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

main.c 如下：

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

执行顺序与上一章 STA 模式保持一致：

这说明 AP 模式和 STA 模式一样，都采用 初始化 + 事件驱动 的工程结构，而不是在 while(1) 里不断轮询 Wi-Fi 状态。

4.2 components/WIFIAP/wifiap.h — 热点账号配置#

wifiap.h 内容很简单：

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

4
void wifiap_init(void);

这表示当前工程创建的热点参数是固定写死的：

• 热点名称：ESP32S3-AP
• 热点密码：qwer123456

这种写法用于教学示例非常直接，优点是上电即可看到效果。

但它也有局限：

• 无法运行时动态改热点名称；
• 密码写在源码中，不适合正式产品；
• 一旦需要用户自定义配网，就必须改成 NVS、网页配置或串口配置。

4.3 components/WIFIAP/wifiap.c — AP 模式初始化与事件处理#

wifiap.c 可分为两部分：

1. Wi-Fi 事件回调函数
2. AP 初始化函数

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
wifiap_event_handler()

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

1
STA: connected

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

1
STA: disconnected

1
void wifiap_init(void)
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_netif_create_default_wifi_ap();
7

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

11
    esp_wifi_set_mode(WIFI_MODE_AP);
12

13
    wifi_config_t wifiap_config = {
14
        .ap = {
15
            .ssid = DEFAULT_SSID,
16
            .ssid_len = strlen(DEFAULT_SSID),
17
            .password = DEFAULT_PWD,
18
            .max_connection = 2,
19
            .authmode = WIFI_AUTH_WPA_WPA2_PSK,
20
        }
21
    };
22
    esp_wifi_set_config(ESP_IF_WIFI_AP, &wifiap_config);
23

24
    esp_wifi_start();
25

26
    lcd_show_string(1,1,"ID:",GREEN,BLACK);
27
    lcd_show_string(1,4,DEFAULT_SSID,YELLOW,BLACK);
28
    lcd_show_string(2,1,"PWD:",GREEN,BLACK);
29
    lcd_show_string(2,5,DEFAULT_PWD,YELLOW,BLACK);
30
    lcd_show_string(3,1,"STA:",GREEN,BLACK);
31
}

1
esp_netif_init();

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

1
esp_netif_create_default_wifi_ap();

1
esp_netif_create_default_wifi_sta();

1
192.168.4.1

1
192.168.4.2
2
192.168.4.3

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

4
esp_wifi_set_mode(WIFI_MODE_AP);

1
wifi_config_t wifiap_config = {
2
    .ap = {
3
        .ssid = DEFAULT_SSID,
4
        .ssid_len = strlen(DEFAULT_SSID),
5
        .password = DEFAULT_PWD,
6
        .max_connection = 2,
7
        .authmode = WIFI_AUTH_WPA_WPA2_PSK,
8
    }
9
};

1
esp_wifi_set_config(ESP_IF_WIFI_AP, &wifiap_config);

1
esp_wifi_start();

1
lcd_show_string(1,1,"ID:",GREEN,BLACK);
2
lcd_show_string(1,4,DEFAULT_SSID,YELLOW,BLACK);
3
lcd_show_string(2,1,"PWD:",GREEN,BLACK);
4
lcd_show_string(2,5,DEFAULT_PWD,YELLOW,BLACK);
5
lcd_show_string(3,1,"STA:",GREEN,BLACK);

1
ID:  ESP32S3-AP
2
PWD: qwer123456
3
STA: connected / disconnected

4.4 为什么 AP 模式不需要 esp_wifi_connect()#

这是 AP 模式与 STA 模式最直观的差别。

在 STA 模式中：

• 自己是客户端；
• 要主动去找路由器；
• 要主动发起连接；
• 因此必须调用 esp_wifi_connect()。

在 AP 模式中：

• 自己是热点；
• 自己负责广播 SSID；
• 等别人来连；
• 所以只要 esp_wifi_start() 就够了。

可以简单类比为：

1
STA 模式：我去别人家敲门
2
AP 模式：我把自己家门打开，等别人来

因此，AP 模式没有”主动连接”这个动作，也就不需要 esp_wifi_connect()。

4.5 为什么 AP 模式通常没有 IP_EVENT_STA_GOT_IP#

STA 模式里，ESP32 作为客户端，要从路由器的 DHCP Server 获取 IP，因此会触发：

1
IP_EVENT_STA_GOT_IP

而 AP 模式下，ESP32 自己就是热点端，通常拥有一个固定的默认地址（如 192.168.4.1），并在内部运行 DHCP Server 给接入的客户端分配地址。

所以本工程的重点不再是：

• 我有没有拿到 IP

而变成了：

• 有没有客户端连到我
• 客户端有没有断开

因此，这里监听的是：

• WIFI_EVENT_AP_STACONNECTED
• WIFI_EVENT_AP_STADISCONNECTED

而不是 IP_EVENT_STA_GOT_IP。

5.1 从上电到热点建立的完整流程#

1
app_main()
2
   │
3
   ├── nvs_flash_init()
4
   │
5
   ├── lcd_init()
6
   │
7
   ├── wifiap_init()
8
   │     │
9
   │     ├── esp_netif_init()
10
   │     ├── esp_event_loop_create_default()
11
   │     ├── 注册 Wi-Fi 事件回调
12
   │     ├── esp_netif_create_default_wifi_ap()
13
   │     ├── esp_wifi_init()
14
   │     ├── esp_wifi_set_mode(WIFI_MODE_AP)
15
   │     ├── esp_wifi_set_config()
16
   │     └── esp_wifi_start()
17
   │             │
18
   │             ▼
19
   │        ESP32 开始广播热点 SSID
20
   │             │
21
   │             ├── LCD 显示 ID
22
   │             ├── LCD 显示 PWD
23
   │             └── LCD 显示 STA 标题
24
   │
25
   └── while(1)
26
         └── vTaskDelay(500)

5.2 STA 接入与断开的时序#

1
外部手机 / 电脑                            ESP32-AP
2
      │                                      │
3
      │ 扫描到 SSID: ESP32S3-AP              │
4
      │────────────────────────────────────► │
5
      │                                      │
6
      │ 输入密码并发起连接                    │
7
      │────────────────────────────────────► │
8
      │                                      │
9
      │ 认证 + 关联成功                       │
10
      │                                      │
11
      │◄──────── WIFI_EVENT_AP_STACONNECTED ─│
12
      │                                      │
13
      │                            LCD 显示 connected
14
      │                                      │
15
      │ 后续如果手动断开或离开覆盖范围         │
16
      │────────────────────────────────────► │
17
      │                                      │
18
      │◄────── WIFI_EVENT_AP_STADISCONNECTED ─│
19
      │                                      │
20
      │                         LCD 显示 disconnected

本章最易忽视的细节#

1. AP 模式下 ESP32 自带 DHCP Server：esp_netif_create_default_wifi_ap() 不仅创建了网络接口，还在内部启动了一个 DHCP Server。这意味着手机连上热点后会自动获得 IP（默认是从 192.168.4.2 开始的地址池），不需要你写任何 DHCP 相关代码。
2. ssid_len 不是可选的：很多教程只写 .ssid = "ESP32S3-AP" 而不写 .ssid_len，这在某些情况下会导致手机搜不到热点。因为 Wi-Fi 协议允许 SSID 中包含 \0 字符，如果不指定长度，ESP-IDF 会用 strlen() 计算——如果你的 SSID 恰好需要包含 \0（极少见），就会出问题。所以显式写 strlen(DEFAULT_SSID) 是最安全的做法。
3. max_connection 受限于 ESP32 的资源：ESP32-S3 默认最多支持 10 个 STA 同时连接（由 CONFIG_ESP_WIFI_SOFTAP_SUPPORT 和内存决定），但你配置的值不能超过硬件上限。如果设成 max_connection = 100，实际只能连上硬件支持的最大数量。
4. AP 模式下 Wi-Fi 信道很重要：默认 AP 信道通常是 1。如果你的环境中信道 1 已经很拥挤（周围 Wi-Fi 很多），可以显式设置 .channel 字段。信道选择会影响连接稳定性——这往往是”连得上但经常掉线”的元凶。

踩坑记录#

• STA 连上 AP 但没有 IP：虽然 ESP32 AP 自带 DHCP Server，但如果手机端 Wi-Fi 设置中禁用了 DHCP（设为静态 IP 但配置错误），就会出现”已连接但无网络”的情况。排查方向是在手机端检查是否获取到了 192.168.4.x 地址。
• AP 启动后 ESP32 自己无法访问外网：这是设计如此——AP 模式下的 ESP32 是一个独立的局域网，不经过路由器。如果需要同时上网，必须使用 WIFI_MODE_APSTA（STA+AP 混合模式），让 STA 接口连接路由器、AP 接口同时提供热点。
• 热点密码少于 8 位导致手机拒绝连接：WPA/WPA2 规范要求密码至少 8 位。如果你的密码只有 6 位，Android/iOS 会提示”密码错误”或直接拒绝连接。这不是 ESP32 的问题，而是客户端的安全策略。

与 STA 模式的逐项深度对比#

上文第 7 节已有一张概要对比表，这里从架构层面补充更深层的差异：

为什么 AP 不需要 esp_wifi_connect()——从协议栈视角看#

这个问题在第 4.4 节已经用类比解释过了。从协议栈视角深入看：

1
STA 模式的协议栈动作序列：
2
  扫描 → 发现 AP → 认证请求 → 关联请求 → DHCP 请求 → 获得 IP
3

4
AP 模式的协议栈动作序列：
5
  启动 → 开始广播 Beacon → 等待 Probe Request →
6
  响应 Probe Response → 处理认证请求 → 处理关联请求 →
7
  内部 DHCP Server 分配 IP

关键差异在第一步：STA 是”主动发起扫描”，AP 是”被动等待扫描”。

esp_wifi_connect() 实际上触发了”扫描 → 认证 → 关联”这一整条 STA 侧的信令链。而 AP 侧没有对等的 API——因为 AP 侧的”认证”和”关联”处理已经内置在 Wi-Fi 驱动中，外部 STA 发来的请求会自动触发相应的处理逻辑，并产生 WIFI_EVENT_AP_STACONNECTED 事件。

换句话说：

• esp_wifi_connect() = 客户端主动发起连接流程
• esp_wifi_start()（AP 模式）= 服务器开始监听，连接流程由客户端驱动

这就是为什么 esp_wifi_connect() 只在 STA 模式有意义——它是”客户端发起连接”的 API，而 AP 是”服务器响应连接”的角色。

与后续章节的知识衔接#

• STA+AP 混合模式：如果要同时上网和提供热点（比如做 Wi-Fi 中继器），需要 WIFI_MODE_APSTA。此时会同时有 esp_netif_create_default_wifi_sta() 和 esp_netif_create_default_wifi_ap() 两个接口，STA 接口负责连接上游路由器，AP 接口负责给下游设备提供热点。
• WebServer 配网：常见的”手机连 ESP32 热点 → 打开网页 → 输入路由器密码 → ESP32 重启并连接路由器”的配网流程，前半段（手机连热点 + 网页）依赖本章的 AP 框架，后半段（连接路由器）依赖 STA 章节。
• NTP 校时：AP 模式下的 ESP32 因为没有互联网连接，不能直接 NTP 校时。如果需要在离线环境下提供准确时间，要么用外部 RTC 模块，要么用 STA+AP 模式让 STA 接口去同步时间。

设计决策思考：AP 模式下 beacon 间隔的选择#

AP 模式下有一个容易被忽略的参数：beacon 间隔。默认值是 100ms，意味着 ESP32 每 100ms 发送一次 beacon 帧。

这影响两个东西：

1. 功耗：beacon 越频繁，Wi-Fi 射频工作时间越长，功耗越高。如果你的设备是电池供电，可以把 beacon 间隔调到 300ms 甚至 500ms。
2. STA 发现速度：beacon 越稀疏，手机扫到热点的速度越慢。100ms 间隔大约 1-3 秒能被扫到，500ms 间隔可能需要 5-10 秒。

如果你需要在 esp_wifi_set_config() 中自定义 beacon 间隔，可以配置 .ap.beacon_interval 字段（单位是 TU，1 TU = 1024 微秒，所以 100ms ≈ 97 TU）。

对于大多数物联网应用，默认 100ms 是一个很好的平衡点。