ESP-NETIF
ESP-NETIF 库的作用主要体现在以下两方面:
在 TCP/IP 协议栈之上为应用程序提供抽象层,允许应用程序在 IP 栈间选择。
在底层 TCP/IP 协议栈 API 非线程安全的情况下,也能提供线程安全的 API。
ESP-IDF 目前只为 lwIP TCP/IP 协议栈实现了 ESP-NETIF。然而,该适配器本身不依赖于特定的 TCP/IP 实现,因而支持不同实现方式。
一些 ESP-NETIF API 函数是为应用程序代码调用而设计的,例如获取或设置接口 IP 地址和配置 DHCP,其他函数则由网络驱动层的内部 ESP-IDF 使用。大多数情况下,应用程序不需要直接调用 ESP-NETIF API,因为这些 API 由默认的网络事件处理程序调用。
如果你只对默认配置下的常见网络接口感兴趣,请参考 ESP-NETIF 用户指南,查看如何初始化默认接口并注册事件处理程序。
如果想了解更多关于 ESP-NETIF 库与其他组件交互的信息,请参考 ESP-NETIF 架构。
如果想自定义应用程序的网络接口,例如设置静态 IP 地址或在运行时更新配置,请参考 ESP-NETIF 编程指南。
如果想开发自己的网络驱动程序,实现对新 TCP/IP 协议栈的支持或以其他方式自定义 ESP-NETIF,请参考 ESP-NETIF 开发者指南。
ESP-NETIF 用户指南
通常只需要在启动后创建一个默认的网络接口,并在关闭时销毁它即可(请参阅 初始化)。在分配新 IP 地址或失去 IP 地址时接收通知也是非常有用的(请参阅 IP 事件)。
初始化
ESP-NETIF 组件使用了系统事件,典型的网络启动代码如下所示(为了清晰起见,省略了错误处理部分,完整版启动代码请参阅 ethernet/basic/main/ethernet_example_main.c):
// 1) 初始化 TCP/IP 协议栈和事件循环
esp_netif_init();
esp_event_loop_create_default();
// 2) 创建网络接口句柄
esp_netif = esp_netif_new(&config);
// 3) 创建网络接口驱动程序(如以太网)及其网络层连接
// 并注册 ESP-NETIF 事件(如,在发生连接事件时将启用接口)
esp_netif_glue_t glue = driver_glue(driver);
// 4) 将驱动程序的胶水层附加到网络接口句柄上
esp_netif_attach(esp_netif, glue);
// 5) 注册用户端的事件处理程序
esp_event_handler_register(DRIVER_EVENT, ...); // 观察驱动状态,例如链路连接
esp_event_handler_register(IP_EVENT, ...); // 观察 ESP-NETIF 状态,例如获取 IP
备注
以上步骤需严格按照顺序执行,因为网络接口驱动程序注册系统事件时会使用默认的事件循环。
默认的事件循环应在初始化接口驱动程序 之前 创建,因为驱动程度通常需要注册系统事件处理程序。
注册应用程序事件处理程序应在调用
esp_netif_attach()
之后 进行,因为事件处理程序按其注册顺序被调用。为了确保系统处理程序先被调用,应该在其后注册应用处理程序。
步骤 2)
、3)
、4)
对于大多数常见用例来说相当复杂,因此 ESP-NETIF 提供了一些预配置的接口和便利函数,从而使用最常见的配置创建最常见的网络接口。
备注
每个网络接口都需要单独初始化,因此如果要使用多个接口,必须为每个接口运行步骤 2)
到步骤 5)
,而步骤 1)
仅需执行一次。
有关如何创建和配置接口并将网络接口驱动程序附加到接口(步骤 2)
、3)
、4)
),请参阅 常见的网络接口。
有关如何使用 ESP-NETIF 事件处理程序(步骤 5)
),请参阅 IP 事件。
常见的网络接口
初始化网络接口可能有些复杂,ESP-NETIF 提供了一些创建常见接口(例如 Wi-Fi 和以太网)的快捷方式。
请参考以下示例来了解如何初始化默认接口:
wifi/getting_started/station 演示了如何使用 station 功能将 ESP32-C2 连接到 AP。
wifi/getting_started/softAP 演示了如何使用 SoftAP 功能将 ESP32-C2 配置为 AP。
ethernet/basic 演示了如何使用以太网驱动程序,将其添加到 esp_netif,并获取一个可 ping 的 IP 地址。
protocols/l2tap 演示了如何使用 ESP-NETIF L2 TAP 接口访问数据链路层,以接收和传输帧,实现非 IP 协议,并使用特定的 EthTypes 回显以太网帧。
protocols/static_ip 演示了如何将 Wi-Fi 配置为 station,包括设置静态 IP、子网掩码、网关和 DNS 服务器。
Wi-Fi 默认初始化
初始化代码以及注册默认接口(例如 softAP 和基站)的事件处理程序都在单独的 API 中提供,从而简化应用程序的启动代码:
请注意,这些函数会返回 esp_netif
句柄,即分配并配置了默认设置的网络接口对象的指针,这意味着:
如果应用程序使用
esp_netif_destroy_default_wifi()
提供网络去初始化,则创建的对象必须被销毁。这些 默认 接口不能被多次创建,除非使用
esp_netif_destroy_default_wifi()
删除已创建的句柄。
在
AP+STA
模式下使用 Wi-Fi 时,须创建以上全部接口。请参考示例 wifi/softap_sta/main/softap_sta.c。
IP 事件
初始化 代码的最后一部分(步骤 5)
)注册了两组事件处理程序:
网络接口驱动事件:用于通知驱动的生命周期状态,例如 Wi-Fi 站点加入 AP 或断开连接。处理这些事件不在 ESP-NETIF 组件的范围内。值得一提的是,ESP-NETIF 也使用相同的事件将网络接口设置为所需状态。因此,如果应用程序使用驱动事件来确定网络接口的特定状态,则应在注册系统处理程序 之后 再注册事件处理程序(通常在将驱动程序附加到接口时进行注册)。这就是为什么事件处理程序的注册是在 初始化 代码的最后一步进行。
IP 事件:用于通知 IP 地址的变化,例如分配新地址或失去有效地址。这些事件的特定类型可参见
ip_event_t
。每个常见的接口都有相应的GOT_IP
和LOST_IP
事件。
由于网络的异步特性,注册事件处理程序非常关键,因为网络状态的变化可能是不可预测的。通过注册事件处理程序,应用程序可以及时响应这些变化,确保在网络事件发生时采取适当的措施。
备注
丢失 IP 事件由一个可配置的定时器触发,配置项为 CONFIG_ESP_NETIF_IP_LOST_TIMER_INTERVAL。当 IP 地址丢失时定时器启动,事件将在配置的时间间隔后触发,默认值为 120 秒。将时间间隔设置为 0 时可禁用该事件。
ESP-NETIF 架构
| (A) 用户代码 |
| 应用程序 |
.................| 初始化 设置 事件 |
. +----------------------------------------+
. . | *
. . | *
--------+ +===========================+ * +-----------------------+
| | 新建/配置 获取/设置/应用程序| * | 初始化 |
| | |...*.....| 应用程序 (DHCP, SNTP) |
| |---------------------------| * | |
初始化 | | |**** | |
启动 |************| 事件处理程序 |*********| DHCP |
停止 | | | | |
| |---------------------------| | |
| | | | NETIF |
+-----| | | +-----------------+ |
|胶水层|---<----|---| esp_netif_transmit |--<------| netif_output | |
| | | | | | | |
| |--->----|---| esp_netif_receive |-->------| netif_input | |
| | | | | + ----------------+ |
| |...<....|...| esp_netif_free_rx_buffer |...<.....| 数据包 buffer |
+-----| | | | | | |
| | | | | | (D) |
(B) | | | | (C) | +-----------------------+
--------+ | | +===========================+ 网络堆栈
网络 | | ESP-NETIF
接口 | |
驱动 | | +---------------------------+ +------------------+
| | | |.........| 开启/关闭 |
| | | | | |
| -<--| l2tap_write |-----<---| 写入 |
| | | | |
---->--| esp_vfs_l2tap_eth_filter |----->---| 读取 |
| | | (A) |
| (E) | +------------------+
+---------------------------+ 用户代码
ESP-NETIF L2 TAP
图中不同线段对应的数据流和事件流
........
从用户代码到 ESP-NETIF 和网络接口驱动的初始化线--<--->--
数据包在通信媒介与 TCP/IP 协议栈之间往返********
聚集在 ESP-NETIF 中的事件传递到驱动程序、用户代码和网络堆栈中|
用户设置及运行时间配置
ESP-NETIF 交互
A) 用户代码样板
通过使用 ESP-NETIF API 抽象,应用程序与用于通信介质(网络接口驱动)的特定 IO 驱动程序以及配置的 TCP/IP 网络栈之间的交互可以概括如下:
初始化代码
初始化 IO 驱动
创建新的 ESP-NETIF 实例,并完成以下配置:
ESP-NETIF 的特定选项(标志、行为、名称)
网络栈堆选项(netif 初始化和输入函数,非公开信息)
IO 驱动的特定选项(发送、释放 rx buffer 函数、IO 驱动句柄)
将 IO 驱动句柄附加到上述步骤所创建的 ESP-NETIF 实例
配置事件处理程序
对 IO 驱动定义的公共接口使用默认处理程序;或为定制的行为或新接口定义特定的处理程序
为应用程序相关事件(如 IP 丢失或获取)注册处理程序
通过 ESP-NETIF API 与网络接口交互
获取、设置 TCP/IP 相关参数(如 DHCP、IP 等)
接收 IP 事件(连接或断连)
控制应用程序生命周期(启用或禁用接口)
B) 网络接口驱动
对于 ESP-NETIF,网络接口驱动(也被称为 I/O 驱动或媒体驱动)具有以下两大作用:
事件驱动程序:定义与 ESP-NETIF 交互的行为模式(如:连接以太网 -> 开启 netif)
胶合 IO 层:调整输入或输出函数以使用 ESP-NETIF 的传输、接收,并清空接收 buffer
给适当的 ESP-NETIF 对象安装 driver_transmit,以便将网络堆栈中传出的数据包传输给 IO 驱动
调用函数
esp_netif_receive()
以便将传入的数据传输给网络堆栈
C) ESP-NETIF
ESP-NETIF 是 IO 驱动和网络堆栈间的媒介,用于连通两者之间的数据包传输路径。它提供了一组接口,用于在运行时将驱动程序附加到 ESP-NETIF 对象并在编译期间配置网络堆栈。此外,ESP-NETIF 还提供了一组 API,用于控制网络接口的生命周期及其 TCP/IP 属性。ESP-NETIF 的公共接口大体上可以分为以下六组:
初始化 API(用于创建并配置 ESP-NETIF 实例)
输入或输出 API(用于在 IO 驱动和网络堆栈间传输数据)
事件或行为 API
管理网络接口生命周期
ESP-NETIF 为设计事件句柄提供了构建模块
基本网络接口属性设置器和获取器 API
网络堆栈抽象 API:实现用户与 TCP/IP 堆栈交互
启用或禁用接口
DHCP 服务器和客户端 API
DNS API
驱动转换工具 API
D) 网络堆栈
网络堆栈与应用程序代码在公共接口方面无公开交互,需通过 ESP-NETIF API 实现完全抽象。
E) ESP-NETIF L2 TAP 接口
ESP-NETIF L2 TAP 接口是 ESP-IDF 中的一种机制,用于让用户应用程序访问数据链路层(OSI/ISO 中的 L2),以便接收和传输帧。在嵌入式开发中,它通常用于实现与 IP 无关的协议,例如 如 PTP 和 Wake on LAN 等。请注意,目前仅支持以太网 (IEEE 802.3)。更多关于 L2 TAP 的信息,请参阅 L2 TAP Interface Usage。
ESP-NETIF 编程指南
在某些情况下,仅初始化一个默认的网络接口、使用该接口并连接到本地网络是不够的。此时请参考编程指南:ESP-NETIF Programmers Manual。
通常需要在以下用例中使用特定的 ESP-NETIF API 集:
ESP-NETIF 开发者指南
在某些情况下,用户应用程序可能需要自定义 ESP-NETIF、注册自定义驱动程序、甚至使用自定义的 TCP/IP 协议栈。此时请参考 ESP-NETIF 开发者指南。