ESP-NETIF

[English]

ESP-NETIF 库的作用主要体现在以下两方面:

  • 在 TCP/IP 协议栈之上为应用程序提供抽象层,允许应用程序在 IP 栈间选择。

  • 在底层 TCP/IP 协议栈 API 非线程安全的情况下,也能提供线程安全的 API。

ESP-IDF 目前只为 lwIP TCP/IP 协议栈实现了 ESP-NETIF。然而,该适配器本身不依赖特定 TCP/IP 实现,因而支持不同实现方式。

ESP-IDF 支持实现了 BSD API 的自定义 TCP/IP 协议栈。有关不使用 lwIP 时构建 ESP-IDF 的详细信息,请参阅 components/esp_netif_stack/README.md

部分 ESP-NETIF 的 API 函数可以被应用程序直接调用,如:获取或设置接口 IP 地址、配置 DHCP 等。其他 ESP-NETIF 的 API 函数则供网络驱动层在 ESP-IDF 内部调用。

应用程序通常无需直接调用 ESP-NETIF 的 API,它们会由默认网络事件句柄调用。

ESP-NETIF 架构

                     |            (A) 用户代码                 |
                     |                 Apps                   |
    .................| 初始化           设置          事件      |
    .                +----------------------------------------+
    .                   .                |           *
    .                   .                |           *
--------+            +===========================+   *     +-----------------------+
        |            | new/config   get/set/apps |   *     | init                  |
        |            |                           |...*.....| Apps (DHCP, SNTP)     |
        |            |---------------------------|   *     |                       |
  初始化 |            |                           |****     |                       |
  启动   |************|    事件句柄                |*********|  DHCP                 |
  停止   |            |                           |         |                       |
        |            |---------------------------|         |                       |
        |            |                           |         |    NETIF              |
  +-----|            |                           |         +-----------------+     |
  | glue|---<----|---|  esp_netif_transmit       |--<------| netif_output    |     |
  |     |        |   |                           |         |                 |     |
  |     |--->----|---|  esp_netif_receive        |-->------| netif_input     |     |
  |     |        |   |                           |         + ----------------+     |
  |     |...<....|...|  esp_netif_free_rx_buffer |...<.....| packet buffer         |
  +-----|     |  |   |                           |         |                       |
        |     |  |   |                           |         |         (D)           |
  (B)   |     |  |   |          (C)              |         +-----------------------+
--------+     |  |   +===========================+
  通信         |  |                                               网络堆栈
  驱动         |  |           ESP-NETIF
              |  |                                         +------------------+
              |  |   +---------------------------+.........| 开启/关闭         |
              |  |   |                           |         |                  |
              |  -<--|  l2tap_write              |-----<---|  写入             |
              |      |                           |         |                  |
              ---->--|  esp_vfs_l2tap_eth_filter |----->---|  读取             |
                     |                           |         |                  |
                     |            (E)            |         +------------------+
                     +---------------------------+
                                                                 用户代码
                           ESP-NETIF L2 TAP

图中不同线段对应的数据流和事件流

  • ........ 从用户代码到 ESP-NETIF 和通信驱动的初始化线。

  • --<--->-- 数据包在通信媒介与 TCP/IP 协议栈之间往返。

  • ******** 聚集在 ESP-NETIF 中的事件传递到驱动程序、用户代码和网络堆栈中。

  • | 用户设置及运行时间配置。

ESP-NETIF 交互

A) 用户代码样板

通过使用 ESP-NETIF API 抽象,应用程序与用于通信介质的特定 IO 驱动程序以及配置的 TCP/IP 网络栈之间的交互可以概括如下:

  1. 初始化代码

  1. 初始化 IO 驱动

  2. 创建新的 ESP-NETIF 实例,并完成以下配置:

  • ESP-NETIF 的特定选项(flags、行为、名称)

  • 网络栈堆选项(netif init 和 input 函数,非公开信息)

  • IO 驱动的特定选项(发送、释放 rx 缓冲区功能、IO 驱动句柄)

  1. 将 IO 驱动句柄附加到上述步骤所创建的 ESP-NETIF 实例

  2. 配置事件句柄

  • 对 IO 驱动定义的公共接口使用默认句柄;或为定制的行为或新接口定义特定的句柄

  • 为应用程序相关事件(如 IP 丢失或获取)注册句柄

  1. 通过 ESP-NETIF API 与网络接口交互

  1. 获取、设置 TCP/IP 相关参数(如 DHCP,IP 等)

  2. 接收 IP 事件(连接或断连)

  3. 控制应用程序生命周期(启用或禁用接口)

B) 通信驱动、IO 驱动和媒介驱动

对于 ESP-NETIF,通信驱动具有以下两个重要作用:

  1. 事件句柄:定义与 ESP-NETIF 交互的行为模式(如:连接以太网 -> 开启 netif)

  2. 胶合 IO 层:调整输入或输出函数以使用 ESP-NETIF 的传输、接收,并清空接收缓冲区

  • 给适当的 ESP-NETIF 对象安装 driver_transmit,以便将网络堆栈中传出的数据包传输给 IO 驱动

  • 调用函数 esp_netif_receive() 以便将传入的数据传输给网络堆栈

C) ESP-NETIF

ESP-NETIF 是 IO 驱动和网络堆栈间的媒介,用于连通两者之间的数据包传输路径。它提供了一组接口,用于在运行时将驱动程序附加到 ESP-NETIF 对象并在编译期间配置网络堆栈。此外,ESP-NETIF 还提供了一组 API,用于控制网络接口的生命周期及其 TCP/IP 属性。ESP-NETIF 的公共接口大体上可以分为以下六组:

  1. 初始化 API(用于创建并配置 ESP-NETIF 实例)

  2. 输入或输出 API(用于在 IO 驱动和网络堆栈间传输数据)

  3. 事件或行为 API

  • 管理网络接口生命周期

  • ESP-NETIF 为设计事件句柄提供了构建模块

  1. 基本网络接口属性设置器和获取器 API

  2. 网络堆栈抽象 API:实现用户与 TCP/IP 堆栈交互

  • 启用或禁用接口

  • DHCP 服务器和客户端 API

  • DNS API

  • SNTP API

  1. 驱动转换工具 API

D) 网络堆栈

网络堆栈与应用程序代码在公共接口方面无公开交互,需通过 ESP-NETIF API 实现完全抽象。

E) ESP-NETIF L2 TAP 接口

ESP-NETIF L2 TAP 接口是 ESP-IDF 访问用户应用程序中的数据链路层(OSI/ISO 中的 L2)以进行帧接收和传输的机制。在嵌入式开发中,它通常用于实现非 IP 相关协议,如 PTP 和 Wake on LAN 等。请注意,目前 ESP-NETIF L2 TAP 接口仅支持以太网 (IEEE 802.3)。

使用 VFS 的文件描述符访问 ESP-NETIF L2 TAP 接口,VFS 文件描述符会提供类似文件的接口(调用 open()read()write() 等函数访问),详情请参阅 虚拟文件系统组件

ESP-NETIF 只提供一个 L2 TAP 接口设备(路径名),但由于 ESP-NETIF L2 TAP 接口也可作为第二层基础设施的通用入口点,因此可以同时打开多个不同配置的文件描述符。特定文件描述符的具体配置很关键,它可以配置为仅允许访问由 if_key (如 ETH_DEF)标识的特定网络接口,并根据帧类型(如 IEEE 802.3 中的以太网类型)过滤特定帧。由于 ESP-NETIF L2 TAP 需要与 IP 堆栈同时存在,因此不应将 IP 相关流量(IP、ARP 等)直接传递给用户应用程序,此时则需要通过配置过滤特定帧实现这一点。在未过滤的情况下,即使该选项仍可配置,也不建议在标准用例中使用。过滤的另一优势在于,过滤后,用户应用程序只能访问它感兴趣的帧类型,其余的流量会传递到其他 L2 TAP 文件描述符或 IP 堆栈。

ESP-NETIF L2 TAP 接口使用手册

初始化

要使用 ESP-NETIF L2 TAP 接口,需要首先通过 Kconfig 配置 CONFIG_ESP_NETIF_L2_TAP 启用接口,随后通过 esp_vfs_l2tap_intf_register() 注册。请在完成上述步骤后再使用 VFS 函数。

open()

ESP-NETIF L2 TAP 注册完成后,可使用路径名 "/dev/net/tap" 访问。同一路径名最多可以被打开 CONFIG_ESP_NETIF_L2_TAP_MAX_FDS 次,多个具有不同配置的文件描述符可以访问数据链路层的各个帧。

ESP-NETIF L2 TAP 可以使用 O_NONBLOCK 文件状态标志打开,确保 read() 不会阻塞。请注意,在当前实现中,当访问网络接口时,由于网络接口被多个 ESP-NETIF L2 TAP 文件描述符和 IP 栈共享,且缺乏列队机制,因此 write() 可能会受阻塞。使用 fcntl() 检索和修改文件状态标志。

成功时,open() 返回新的文件描述符(非负整数)。出错时,返回 -1,并设置 errno 以标识错误。

ioctl()

由于新打开的 ESP-NETIF L2 TAP 文件描述符尚未绑定任意网络接口或配置任意帧类型过滤器,使用前,用户需通过以下选项完成配置:

  • L2TAP_S_INTF_DEVICE - 将文件描述符绑定到特定网络接口的选项,该网络接口由其 if_key 标识。ESP-NETIF 网络接口的 if_key 作为第三个参数传输给 ioctl()。ESP-IDF 中,默认网络接口 if_key 的使用存放在 esp_netif/include/esp_netif_defaults.h 头文件中。

  • L2TAP_S_DEVICE_DRV_HNDL - 将文件描述符绑定到特定网络接口的另一选项。此时,网络接口直接由其 IO 驱动句柄(例如以太网中的 esp_eth_handle_t)标识。IO 驱动句柄将作为第三个参数传输给 ioctl()

  • L2TAP_S_RCV_FILTER - 设置过滤器,将特定类型的帧传递到文件描述符。在以太网中,帧是基于长度和以太网类型字段过滤的。如果过滤器值设置为小于或等于 0x05DC,则将以太网类型字段视作 IEEE802.3 长度字段,并将该字段中所有值在 <0, 0x05DC> 区间内的帧传递到文件描述符中。随后,由用户应用程序执行 IEEE802.2 逻辑链路控制 (LLC) 的解析。如果过滤器值设置为大于 0x05DC,则将以太网类型字段视为代表协议标识,仅将与设置值相等的帧传递到文件描述符中。

上述配置选项都支持通过对应获取器选项读取当前配置。

警告

首先调用 L2TAP_S_INTF_DEVICEL2TAP_S_DEVICE_DRV_HNDL 将文件描述符绑定到特定网络接口,随后方可调用 L2TAP_S_RCV_FILTER 选项。

备注

当前不支持识别 VLAN 标记帧。如果用户需要处理 VLAN 标记帧,应将过滤器设置为等于 VLAN 标记(即 0x8100 或 0x88A8),并在用户应用程序中处理 VLAN 标记帧。

备注

当用户应用程序不需要使用 IP 栈时, L2TAP_S_DEVICE_DRV_HNDL 将非常适用,也无需初始化 ESP-NETIF。但在此情况下,网络接口无法通过 if_key 来识别,需要通过 IO 驱动程序句柄直接标识网络接口。

成功时,ioctl() 返回 0。出错时,返回 -1,并设置 errno 以指示错误类型:
* EBADF - 文件描述符无效。
* EACCES - 此状态下无法改变选项(例如文件描述符尚未绑定到网络接口)。
* EINVAL - 配置参数无效。同一网络接口上的其他文件描述符已经使用了以太网类型过滤器。
* ENODEV - 此文件描述符尝试分配给的网络接口不存在。
* ENOSYS - 不支持该操作,传递的配置选项不存在。

fcntl()

fcntl() 配置已开启的 ESP-NETIF L2 TAP 文件描述符属性。

以下命令调控与文件描述符相关的状态标志:

  • F_GETFD - 函数返回文件描述符标志,忽略第三个参数。

  • F_SETFD - 将文件描述符标志设置为第三个参数的指定值。返回零。

成功时,ioctl() 返回 0。出错时,返回 -1,并设置 errno 以指示错误类型。
* EBADF - 文件描述符无效。
* ENOSYS - 不支持该命令。

read()

已开启并完成配置的 ESP-NETIF L2 TAP 文件描述符可通过 read() 获取入站帧。读取可以是阻塞或非阻塞的,具体取决于 O_NONBLOCK 文件状态标志的实际状态。当文件状态标志设置为阻塞时,读取程序将等待,直到接收到帧,并将上下文切换到其他任务。当文件状态标志设置为非阻塞时,立即返回读取程序。在此情况下,如果已经帧已经入队,则返回一帧,否则函数指示队列为空。与文件描述符关联的队列帧数量受 CONFIG_ESP_NETIF_L2_TAP_RX_QUEUE_SIZE Kconfig 选项限制。一旦队列里帧的数量达到配置的阈值,新到达的帧将被丢弃,直到队列有足够的空间接受传入的流量(队尾丢弃队列管理)。

成功时,read() 函数返回读取的字节数。当目标缓冲区的大小为 0 时,函数返回 0。出错时,函数返回 -1,并设置 errno 以指示错误类型。
* EBADF - 文件描述符无效。
* EAGAIN - 文件描述符标记为非阻塞 (O_NONBLOCK),但读取受阻塞。

write()

通过已开启并完成配置的 ESP-NETIF L2 TAP 文件描述符可以将原始数据链路层帧发送到网络接口,用户应用程序负责构建除物理接口设备自动添加的字段外的整个帧。在以太网链路中,用户应用程序需要构建以下字段:源或目的 MAC 地址、以太网类型、实际协议头和用户数据,字段长度如下表:

目的 MAC

源 MAC

类型/长度

负载(协议头/数据)

6 B

6 B

2 B

0-1486 B

换句话说,ESP-NETIF L2 TAP 接口不会对数据帧进行额外处理,只会检查数据帧的以太网类型是否与文件描述符配置的过滤器相同。如果以太网类型不同,则会返回错误,并且不发送数据帧。需要注意的是,由于网络接口是由多个 ESP-NETIF L2 TAP 文件描述符和 IP 栈共享的资源,且当前缺乏列队机制,当前实现中的 write() 在进入网络接口时可能会受阻塞,。

成功时,write() 返回已写入的字节数。如果输入缓冲区的大小为 0,则返回 0。出错时,则返回 -1,并设置 errno 以指示错误类型。
* EBADF - 文件描述符无效。
* EBADMSG - 帧的以太网类型与文件描述符配置的过滤器不同。
* EIO - 网络接口不可用或正忙。

close()

已开启的 ESP-NETIF L2 TAP 文件描述符可以通过 close() 函数关闭,释放其分配到的资源。ESP-NETIF L2 TAP 实现的 close() 函数可能会受阻塞,但它是线程安全的,可以从与实际使用文件描述符的任务不同的任务中调用。如果出现一个任务在 I/O 操作中被阻塞、另一个任务试图关闭文件描述符的情况,则第一个任务会解除阻塞,其读取程序以错误结束。

成功时,close() 返回 0。出错时,则返回 -1, 并设置 errno 以指示错误类型。
* EBADF - 文件描述符无效。

select()

select() 函数按标准方法使用,启用 CONFIG_VFS_SUPPORT_SELECT 即可使用该函数。

SNTP API

SNTP 的简要介绍、初始化代码和基本模式请参阅 系统时间SNTP 时间同步 小节。

本节介绍了使用 SNTP 服务特定用例的详细信息,包括静态配置的服务器、使用 DHCP 提供的服务器或两者兼备的情况,操作流程如下:

  1. 调用 esp_netif_sntp_init() 初始化服务并完成配置。

  2. 调用 esp_netif_sntp_start() 启动服务。如果在前一步中已经默认启动了服务,则不需要此步骤。如果需使用通过 DHCP 获取的 NTP 服务器,推荐在完成连接后显式启动该服务。注意,应在连接前启用通过 DHCP 获取的 NTP 服务器选项,并在连接后再启用 SNTP 服务。

  3. 需要时,可调用 esp_netif_sntp_sync_wait() 等待系统时间同步。

  4. 调用 esp_netif_sntp_deinit() 停止并销毁服务。

使用静态定义服务器的基本模式

连接到网络后,使用默认配置初始化该模块。注意,在配置结构体中可提供多个 NTP 服务器:

esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(2,
                           ESP_SNTP_SERVER_LIST("time.windows.com", "pool.ntp.org" ) );
esp_netif_sntp_init(&config);

备注

要配置多个 SNTP 服务器,需要更新 lwIP 配置,请参阅 CONFIG_LWIP_SNTP_MAX_SERVERS

使用 DHCP 获取的 SNTP 服务器

首先,激活 lwIP 配置选项,相关配置请参阅 CONFIG_LWIP_DHCP_GET_NTP_SRV。其次,在使用 DHCP 选项、且不使用 NTP 服务器的情况下初始化 SNTP 模块,代码如下:

esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(0, {} );
config.start = false;                       // 启动 SNTP 服务
config.server_from_dhcp = true;             // 接收来自 DHCP 服务器的 NTP 服务提供方案
esp_netif_sntp_init(&config);

连接成功后,可通过以下代码启动服务器:

esp_netif_sntp_start();

备注

也可选择在初始化期间启动服务(即默认 config.start=true)。注意,此时连接尚未完成,可能导致初始 SNTP 请求失败,并增加后续各次请求之间的延迟时间。

同时使用静态和动态服务器

同时使用静态和动态服务器的流程与使用 DHCP 获取的 SNTP 服务器基本相同。配置时,用户应确保在通过 DHCP 获取 NTP 服务器时刷新静态服务器配置。底层 lwIP 代码会在接受 DHCP 提供的信息时清理其余的 NTP 服务器列表。因此,ESP-NETIF SNTP 模块会保存静态配置的服务器,并在获取 DHCP 租约后对其重新配置。

典型配置依次如下,提供特定 IP_EVENT 更新配置,并提供第一个服务器的索引完成重新配置(例如,设置 config.index_of_first_server=1 会将 DHCP 提供的服务器保留在索引 0,而将静态配置的服务器保留在索引 1)。

esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG("pool.ntp.org");
config.start = false;                       // 启动 SNTP 服务(连接成功后)
config.server_from_dhcp = true;             // 接收来自 DHCP 服务器的 NTP 服务提供方案
config.renew_servers_after_new_IP = true;   // 让 esp-netif 在接收到 DHCP 租约后更新配置的 SNTP 服务器
config.index_of_first_server = 1;           // 服务器 1 开始更新,保留从 DHCP 获取的服务器 0 的设置
config.ip_event_to_renew = IP_EVENT_STA_GOT_IP;  // 基于 IP 事件刷新配置

随后,调用 esp_netif_sntp_start() 启用服务。

ESP-NETIF 编程手册

请参阅示例部分,了解默认接口的基本初始化:

更多示例请参阅 ESP-NETIF 自定义 I/O 驱动程序

Wi-Fi 默认初始化

初始化代码以及注册默认接口(例如接入点和基站)的事件处理程序都在单独的 API 中提供,以便为大多数应用程序提供简单的启动代码:

注意,这些函数返回 esp_netif 句柄,即分配并配置了默认设置的网络接口对象的指针,这意味着:

  • AP+STA 模式下使用 Wi-Fi 时,须创建以上全部接口。

API 参考

Header File

  • components/esp_netif/include/esp_netif.h

  • This header file can be included with:

    #include "esp_netif.h"
    
  • This header file is a part of the API provided by the esp_netif component. To declare that your component depends on esp_netif, add the following to your CMakeLists.txt:

    REQUIRES esp_netif
    

    or

    PRIV_REQUIRES esp_netif
    

Functions

esp_err_t esp_netif_init(void)

Initialize the underlying TCP/IP stack.

备注

This function should be called exactly once from application code, when the application starts up.

返回

  • ESP_OK on success

  • ESP_FAIL if initializing failed

esp_err_t esp_netif_deinit(void)

Deinitialize the esp-netif component (and the underlying TCP/IP stack)

     Note: Deinitialization is not supported yet
返回

  • ESP_ERR_INVALID_STATE if esp_netif not initialized

  • ESP_ERR_NOT_SUPPORTED otherwise

esp_netif_t *esp_netif_new(const esp_netif_config_t *esp_netif_config)

Creates an instance of new esp-netif object based on provided config.

参数

esp_netif_config -- [in] pointer esp-netif configuration

返回

  • pointer to esp-netif object on success

  • NULL otherwise

void esp_netif_destroy(esp_netif_t *esp_netif)

Destroys the esp_netif object.

参数

esp_netif -- [in] pointer to the object to be deleted

esp_err_t esp_netif_set_driver_config(esp_netif_t *esp_netif, const esp_netif_driver_ifconfig_t *driver_config)

Configures driver related options of esp_netif object.

参数
  • esp_netif -- [inout] pointer to the object to be configured

  • driver_config -- [in] pointer esp-netif io driver related configuration

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS if invalid parameters provided

esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle)

Attaches esp_netif instance to the io driver handle.

Calling this function enables connecting specific esp_netif object with already initialized io driver to update esp_netif object with driver specific configuration (i.e. calls post_attach callback, which typically sets io driver callbacks to esp_netif instance and starts the driver)

参数
  • esp_netif -- [inout] pointer to esp_netif object to be attached

  • driver_handle -- [in] pointer to the driver handle

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED if driver's pot_attach callback failed

esp_err_t esp_netif_receive(esp_netif_t *esp_netif, void *buffer, size_t len, void *eb)

Passes the raw packets from communication media to the appropriate TCP/IP stack.

This function is called from the configured (peripheral) driver layer. The data are then forwarded as frames to the TCP/IP stack.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • buffer -- [in] Received data

  • len -- [in] Length of the data frame

  • eb -- [in] Pointer to internal buffer (used in Wi-Fi driver)

返回

  • ESP_OK

void esp_netif_action_start(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver start event Creates network interface, if AUTOUP enabled turns the interface on, if DHCPS enabled starts dhcp server.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_stop(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver stop event.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_connected(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver connected event.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_disconnected(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IO driver disconnected event.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_got_ip(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon network got IP event.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_join_ip6_multicast_group(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 multicast group join.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_leave_ip6_multicast_group(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 multicast group leave.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_add_ip6_address(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 address added by the underlying stack.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

void esp_netif_action_remove_ip6_address(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data)

Default building block for network interface action upon IPv6 address removed by the underlying stack.

备注

This API can be directly used as event handler

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • base -- The base type of the event

  • event_id -- The specific ID of the event

  • data -- Optional data associated with the event

esp_err_t esp_netif_set_default_netif(esp_netif_t *esp_netif)

Manual configuration of the default netif.

This API overrides the automatic configuration of the default interface based on the route_prio If the selected netif is set default using this API, no other interface could be set-default disregarding its route_prio number (unless the selected netif gets destroyed)

参数

esp_netif -- [in] Handle to esp-netif instance

返回

ESP_OK on success

esp_netif_t *esp_netif_get_default_netif(void)

Getter function of the default netif.

This API returns the selected default netif.

返回

Handle to esp-netif instance of the default netif.

esp_err_t esp_netif_join_ip6_multicast_group(esp_netif_t *esp_netif, const esp_ip6_addr_t *addr)

Cause the TCP/IP stack to join a IPv6 multicast group.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • addr -- [in] The multicast group to join

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_MLD6_FAILED

  • ESP_ERR_NO_MEM

esp_err_t esp_netif_leave_ip6_multicast_group(esp_netif_t *esp_netif, const esp_ip6_addr_t *addr)

Cause the TCP/IP stack to leave a IPv6 multicast group.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • addr -- [in] The multicast group to leave

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_MLD6_FAILED

  • ESP_ERR_NO_MEM

esp_err_t esp_netif_set_mac(esp_netif_t *esp_netif, uint8_t mac[])

Set the mac address for the interface instance.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • mac -- [in] Desired mac address for the related network interface

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_NOT_SUPPORTED - mac not supported on this interface

esp_err_t esp_netif_get_mac(esp_netif_t *esp_netif, uint8_t mac[])

Get the mac address for the interface instance.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • mac -- [out] Resultant mac address for the related network interface

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_NOT_SUPPORTED - mac not supported on this interface

esp_err_t esp_netif_set_hostname(esp_netif_t *esp_netif, const char *hostname)

Set the hostname of an interface.

The configured hostname overrides the default configuration value CONFIG_LWIP_LOCAL_HOSTNAME. Please note that when the hostname is altered after interface started/connected the changes would only be reflected once the interface restarts/reconnects

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • hostname -- [in] New hostname for the interface. Maximum length 32 bytes.

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error

esp_err_t esp_netif_get_hostname(esp_netif_t *esp_netif, const char **hostname)

Get interface hostname.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • hostname -- [out] Returns a pointer to the hostname. May be NULL if no hostname is set. If set non-NULL, pointer remains valid (and string may change if the hostname changes).

返回

  • ESP_OK - success

  • ESP_ERR_ESP_NETIF_IF_NOT_READY - interface status error

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS - parameter error

bool esp_netif_is_netif_up(esp_netif_t *esp_netif)

Test if supplied interface is up or down.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • true - Interface is up

  • false - Interface is down

esp_err_t esp_netif_get_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info)

Get interface's IP address information.

If the interface is up, IP information is read directly from the TCP/IP stack. If the interface is down, IP information is read from a copy kept in the ESP-NETIF instance

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • ip_info -- [out] If successful, IP information will be returned in this argument.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_get_old_ip_info(esp_netif_t *esp_netif, esp_netif_ip_info_t *ip_info)

Get interface's old IP information.

Returns an "old" IP address previously stored for the interface when the valid IP changed.

If the IP lost timer has expired (meaning the interface was down for longer than the configured interval) then the old IP information will be zero.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • ip_info -- [out] If successful, IP information will be returned in this argument.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_set_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info)

Set interface's IP address information.

This function is mainly used to set a static IP on an interface.

If the interface is up, the new IP information is set directly in the TCP/IP stack.

The copy of IP information kept in the ESP-NETIF instance is also updated (this copy is returned if the IP is queried while the interface is still down.)

备注

DHCP client/server must be stopped (if enabled for this interface) before setting new IP information.

备注

Calling this interface for may generate a SYSTEM_EVENT_STA_GOT_IP or SYSTEM_EVENT_ETH_GOT_IP event.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • ip_info -- [in] IP information to set on the specified interface

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED If DHCP server or client is still running

esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info)

Set interface old IP information.

This function is called from the DHCP client (if enabled), before a new IP is set. It is also called from the default handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events.

Calling this function stores the previously configured IP, which can be used to determine if the IP changes in the future.

If the interface is disconnected or down for too long, the "IP lost timer" will expire (after the configured interval) and set the old IP information to zero.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • ip_info -- [in] Store the old IP information for the specified interface

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

int esp_netif_get_netif_impl_index(esp_netif_t *esp_netif)

Get net interface index from network stack implementation.

备注

This index could be used in setsockopt() to bind socket with multicast interface

参数

esp_netif -- [in] Handle to esp-netif instance

返回

implementation specific index of interface represented with supplied esp_netif

esp_err_t esp_netif_get_netif_impl_name(esp_netif_t *esp_netif, char *name)

Get net interface name from network stack implementation.

备注

This name could be used in setsockopt() to bind socket with appropriate interface

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • name -- [out] Interface name as specified in underlying TCP/IP stack. Note that the actual name will be copied to the specified buffer, which must be allocated to hold maximum interface name size (6 characters for lwIP)

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_napt_enable(esp_netif_t *esp_netif)

Enable NAPT on an interface.

备注

Enable operation can be performed only on one interface at a time. NAPT cannot be enabled on multiple interfaces according to this implementation.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_NOT_SUPPORTED

esp_err_t esp_netif_napt_disable(esp_netif_t *esp_netif)

Disable NAPT on an interface.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_FAIL

  • ESP_ERR_NOT_SUPPORTED

esp_err_t esp_netif_dhcps_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op, esp_netif_dhcp_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP server option.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • opt_op -- [in] ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.

  • opt_id -- [in] Option index to get or set, must be one of the supported enum values.

  • opt_val -- [inout] Pointer to the option parameter.

  • opt_len -- [in] Length of the option parameter.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

esp_err_t esp_netif_dhcpc_option(esp_netif_t *esp_netif, esp_netif_dhcp_option_mode_t opt_op, esp_netif_dhcp_option_id_t opt_id, void *opt_val, uint32_t opt_len)

Set or Get DHCP client option.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • opt_op -- [in] ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.

  • opt_id -- [in] Option index to get or set, must be one of the supported enum values.

  • opt_val -- [inout] Pointer to the option parameter.

  • opt_len -- [in] Length of the option parameter.

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

esp_err_t esp_netif_dhcpc_start(esp_netif_t *esp_netif)

Start DHCP client (only if enabled in interface object)

备注

The default event handlers for the SYSTEM_EVENT_STA_CONNECTED and SYSTEM_EVENT_ETH_CONNECTED events call this function.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

  • ESP_ERR_ESP_NETIF_DHCPC_START_FAILED

esp_err_t esp_netif_dhcpc_stop(esp_netif_t *esp_netif)

Stop DHCP client (only if enabled in interface object)

备注

Calling action_netif_stop() will also stop the DHCP Client if it is running.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_IF_NOT_READY

esp_err_t esp_netif_dhcpc_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status)

Get DHCP client status.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • status -- [out] If successful, the status of DHCP client will be returned in this argument.

返回

  • ESP_OK

esp_err_t esp_netif_dhcps_get_status(esp_netif_t *esp_netif, esp_netif_dhcp_status_t *status)

Get DHCP Server status.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • status -- [out] If successful, the status of the DHCP server will be returned in this argument.

返回

  • ESP_OK

esp_err_t esp_netif_dhcps_start(esp_netif_t *esp_netif)

Start DHCP server (only if enabled in interface object)

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED

esp_err_t esp_netif_dhcps_stop(esp_netif_t *esp_netif)

Stop DHCP server (only if enabled in interface object)

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

  • ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED

  • ESP_ERR_ESP_NETIF_IF_NOT_READY

esp_err_t esp_netif_dhcps_get_clients_by_mac(esp_netif_t *esp_netif, int num, esp_netif_pair_mac_ip_t *mac_ip_pair)

Populate IP addresses of clients connected to DHCP server listed by their MAC addresses.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • num -- [in] Number of clients with specified MAC addresses in the array of pairs

  • mac_ip_pair -- [inout] Array of pairs of MAC and IP addresses (MAC are inputs, IP outputs)

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS on invalid params

  • ESP_ERR_NOT_SUPPORTED if DHCP server not enabled

esp_err_t esp_netif_set_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type, esp_netif_dns_info_t *dns)

Set DNS Server information.

This function behaves differently if DHCP server or client is enabled

If DHCP client is enabled, main and backup DNS servers will be updated automatically from the DHCP lease if the relevant DHCP options are set. Fallback DNS Server is never updated from the DHCP lease and is designed to be set via this API. If DHCP client is disabled, all DNS server types can be set via this API only.

If DHCP server is enabled, the Main DNS Server setting is used by the DHCP server to provide a DNS Server option to DHCP clients (Wi-Fi stations).

  • The default Main DNS server is typically the IP of the DHCP server itself.

  • This function can override it by setting server type ESP_NETIF_DNS_MAIN.

  • Other DNS Server types are not supported for the DHCP server.

  • To propagate the DNS info to client, please stop the DHCP server before using this API.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • type -- [in] Type of DNS Server to set: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK

  • dns -- [in] DNS Server address to set

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params

esp_err_t esp_netif_get_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t type, esp_netif_dns_info_t *dns)

Get DNS Server information.

Return the currently configured DNS Server address for the specified interface and Server type.

This may be result of a previous call to esp_netif_set_dns_info(). If the interface's DHCP client is enabled, the Main or Backup DNS Server may be set by the current DHCP lease.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • type -- [in] Type of DNS Server to get: ESP_NETIF_DNS_MAIN, ESP_NETIF_DNS_BACKUP, ESP_NETIF_DNS_FALLBACK

  • dns -- [out] DNS Server result is written here on success

返回

  • ESP_OK on success

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS invalid params

esp_err_t esp_netif_create_ip6_linklocal(esp_netif_t *esp_netif)

Create interface link-local IPv6 address.

Cause the TCP/IP stack to create a link-local IPv6 address for the specified interface.

This function also registers a callback for the specified interface, so that if the link-local address becomes verified as the preferred address then a SYSTEM_EVENT_GOT_IP6 event will be sent.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

  • ESP_OK

  • ESP_ERR_ESP_NETIF_INVALID_PARAMS

esp_err_t esp_netif_get_ip6_linklocal(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6)

Get interface link-local IPv6 address.

If the specified interface is up and a preferred link-local IPv6 address has been created for the interface, return a copy of it.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • if_ip6 -- [out] IPv6 information will be returned in this argument if successful.

返回

  • ESP_OK

  • ESP_FAIL If interface is down, does not have a link-local IPv6 address, or the link-local IPv6 address is not a preferred address.

esp_err_t esp_netif_get_ip6_global(esp_netif_t *esp_netif, esp_ip6_addr_t *if_ip6)

Get interface global IPv6 address.

If the specified interface is up and a preferred global IPv6 address has been created for the interface, return a copy of it.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • if_ip6 -- [out] IPv6 information will be returned in this argument if successful.

返回

  • ESP_OK

  • ESP_FAIL If interface is down, does not have a global IPv6 address, or the global IPv6 address is not a preferred address.

int esp_netif_get_all_ip6(esp_netif_t *esp_netif, esp_ip6_addr_t if_ip6[])

Get all IPv6 addresses of the specified interface.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • if_ip6 -- [out] Array of IPv6 addresses will be copied to the argument

返回

number of returned IPv6 addresses

void esp_netif_set_ip4_addr(esp_ip4_addr_t *addr, uint8_t a, uint8_t b, uint8_t c, uint8_t d)

Sets IPv4 address to the specified octets.

参数
  • addr -- [out] IP address to be set

  • a -- the first octet (127 for IP 127.0.0.1)

  • b --

  • c --

  • d --

char *esp_ip4addr_ntoa(const esp_ip4_addr_t *addr, char *buf, int buflen)

Converts numeric IP address into decimal dotted ASCII representation.

参数
  • addr -- ip address in network order to convert

  • buf -- target buffer where the string is stored

  • buflen -- length of buf

返回

either pointer to buf which now holds the ASCII representation of addr or NULL if buf was too small

uint32_t esp_ip4addr_aton(const char *addr)

Ascii internet address interpretation routine The value returned is in network order.

参数

addr -- IP address in ascii representation (e.g. "127.0.0.1")

返回

ip address in network order

esp_err_t esp_netif_str_to_ip4(const char *src, esp_ip4_addr_t *dst)

Converts Ascii internet IPv4 address into esp_ip4_addr_t.

参数
  • src -- [in] IPv4 address in ascii representation (e.g. "127.0.0.1")

  • dst -- [out] Address of the target esp_ip4_addr_t structure to receive converted address

返回

  • ESP_OK on success

  • ESP_FAIL if conversion failed

  • ESP_ERR_INVALID_ARG if invalid parameter is passed into

esp_err_t esp_netif_str_to_ip6(const char *src, esp_ip6_addr_t *dst)

Converts Ascii internet IPv6 address into esp_ip4_addr_t Zeros in the IP address can be stripped or completely ommited: "2001:db8:85a3:0:0:0:2:1" or "2001:db8::2:1")

参数
  • src -- [in] IPv6 address in ascii representation (e.g. ""2001:0db8:85a3:0000:0000:0000:0002:0001")

  • dst -- [out] Address of the target esp_ip6_addr_t structure to receive converted address

返回

  • ESP_OK on success

  • ESP_FAIL if conversion failed

  • ESP_ERR_INVALID_ARG if invalid parameter is passed into

esp_netif_iodriver_handle esp_netif_get_io_driver(esp_netif_t *esp_netif)

Gets media driver handle for this esp-netif instance.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

opaque pointer of related IO driver

esp_netif_t *esp_netif_get_handle_from_ifkey(const char *if_key)

Searches over a list of created objects to find an instance with supplied if key.

参数

if_key -- Textual description of network interface

返回

Handle to esp-netif instance

esp_netif_flags_t esp_netif_get_flags(esp_netif_t *esp_netif)

Returns configured flags for this interface.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

Configuration flags

const char *esp_netif_get_ifkey(esp_netif_t *esp_netif)

Returns configured interface key for this esp-netif instance.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

Textual description of related interface

const char *esp_netif_get_desc(esp_netif_t *esp_netif)

Returns configured interface type for this esp-netif instance.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

Enumerated type of this interface, such as station, AP, ethernet

int esp_netif_get_route_prio(esp_netif_t *esp_netif)

Returns configured routing priority number.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

Integer representing the instance's route-prio, or -1 if invalid paramters

int32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_t event_type)

Returns configured event for this esp-netif instance and supplied event type.

参数
  • esp_netif -- [in] Handle to esp-netif instance

  • event_type -- (either get or lost IP)

返回

specific event id which is configured to be raised if the interface lost or acquired IP address -1 if supplied event_type is not known

esp_netif_t *esp_netif_next(esp_netif_t *esp_netif)

Iterates over list of interfaces. Returns first netif if NULL given as parameter.

备注

This API doesn't lock the list, nor the TCPIP context, as this it's usually required to get atomic access between iteration steps rather that within a single iteration. Therefore it is recommended to iterate over the interfaces inside esp_netif_tcpip_exec()

备注

This API is deprecated. Please use esp_netif_next_unsafe() directly if all the system interfaces are under your control and you can safely iterate over them. Otherwise, iterate over interfaces using esp_netif_tcpip_exec(), or use esp_netif_find_if() to search in the list of netifs with defined predicate.

参数

esp_netif -- [in] Handle to esp-netif instance

返回

First netif from the list if supplied parameter is NULL, next one otherwise

esp_netif_t *esp_netif_next_unsafe(esp_netif_t *esp_netif)

Iterates over list of interfaces without list locking. Returns first netif if NULL given as parameter.

Used for bulk search loops within TCPIP context, e.g. using esp_netif_tcpip_exec(), or if we're sure that the iteration is safe from our application perspective (e.g. no interface is removed between iterations)

参数

esp_netif -- [in] Handle to esp-netif instance

返回

First netif from the list if supplied parameter is NULL, next one otherwise

esp_netif_t *esp_netif_find_if(esp_netif_find_predicate_t fn, void *ctx)

Return a netif pointer for the first interface that meets criteria defined by the callback.

参数
  • fn -- Predicate function returning true for the desired interface

  • ctx -- Context pointer passed to the predicate, typically a descriptor to compare with

返回

valid netif pointer if found, NULL if not

size_t esp_netif_get_nr_of_ifs(void)

Returns number of registered esp_netif objects.

返回

Number of esp_netifs

void esp_netif_netstack_buf_ref(void *netstack_buf)

increase the reference counter of net stack buffer

参数

netstack_buf -- [in] the net stack buffer

void esp_netif_netstack_buf_free(void *netstack_buf)

free the netstack buffer

参数

netstack_buf -- [in] the net stack buffer

esp_err_t esp_netif_tcpip_exec(esp_netif_callback_fn fn, void *ctx)

Utility to execute the supplied callback in TCP/IP context.

参数
  • fn -- Pointer to the callback

  • ctx -- Parameter to the callback

返回

The error code (esp_err_t) returned by the callback

Type Definitions

typedef bool (*esp_netif_find_predicate_t)(esp_netif_t *netif, void *ctx)

Predicate callback for esp_netif_find_if() used to find interface which meets defined criteria.

typedef esp_err_t (*esp_netif_callback_fn)(void *ctx)

TCPIP thread safe callback used with esp_netif_tcpip_exec()

Header File

  • components/esp_netif/include/esp_netif_sntp.h

  • This header file can be included with:

    #include "esp_netif_sntp.h"
    
  • This header file is a part of the API provided by the esp_netif component. To declare that your component depends on esp_netif, add the following to your CMakeLists.txt:

    REQUIRES esp_netif
    

    or

    PRIV_REQUIRES esp_netif
    

Functions

esp_err_t esp_netif_sntp_init(const esp_sntp_config_t *config)

Initialize SNTP with supplied config struct.

参数

config -- Config struct

返回

ESP_OK on success

esp_err_t esp_netif_sntp_start(void)

Start SNTP service if it wasn't started during init (config.start = false) or restart it if already started.

返回

ESP_OK on success

void esp_netif_sntp_deinit(void)

Deinitialize esp_netif SNTP module.

esp_err_t esp_netif_sntp_sync_wait(TickType_t tout)

Wait for time sync event.

参数

tout -- Specified timeout in RTOS ticks

返回

ESP_TIMEOUT if sync event didn't came withing the timeout ESP_ERR_NOT_FINISHED if the sync event came, but we're in smooth update mode and still in progress (SNTP_SYNC_STATUS_IN_PROGRESS) ESP_OK if time sync'ed

Structures

struct esp_sntp_config

SNTP configuration struct.

Public Members

bool smooth_sync

set to true if smooth sync required

bool server_from_dhcp

set to true to request NTP server config from DHCP

bool wait_for_sync

if true, we create a semaphore to signal time sync event

bool start

set to true to automatically start the SNTP service

esp_sntp_time_cb_t sync_cb

optionally sets callback function on time sync event

bool renew_servers_after_new_IP

this is used to refresh server list if NTP provided by DHCP (which cleans other pre-configured servers)

ip_event_t ip_event_to_renew

set the IP event id on which we refresh server list (if renew_servers_after_new_IP=true)

size_t index_of_first_server

refresh server list after this server (if renew_servers_after_new_IP=true)

size_t num_of_servers

number of preconfigured NTP servers

const char *servers[1]

list of servers

Macros

ESP_SNTP_SERVER_LIST(...)

Utility macro for providing multiple servers in parentheses.

ESP_NETIF_SNTP_DEFAULT_CONFIG_MULTIPLE(servers_in_list, list_of_servers)

Default configuration to init SNTP with multiple servers.

参数
ESP_NETIF_SNTP_DEFAULT_CONFIG(server)

Default configuration with a single server.

Type Definitions

typedef void (*esp_sntp_time_cb_t)(struct timeval *tv)

Time sync notification function.

typedef struct esp_sntp_config esp_sntp_config_t

SNTP configuration struct.

Header File

  • components/esp_netif/include/esp_netif_types.h

  • This header file can be included with:

    #include "esp_netif_types.h"
    
  • This header file is a part of the API provided by the esp_netif component. To declare that your component depends on esp_netif, add the following to your CMakeLists.txt:

    REQUIRES esp_netif
    

    or

    PRIV_REQUIRES esp_netif
    

Structures

struct esp_netif_dns_info_t

DNS server info.

Public Members

esp_ip_addr_t ip

IPV4 address of DNS server

struct esp_netif_ip_info_t

Event structure for IP_EVENT_STA_GOT_IP, IP_EVENT_ETH_GOT_IP events

Public Members

esp_ip4_addr_t ip

Interface IPV4 address

esp_ip4_addr_t netmask

Interface IPV4 netmask

esp_ip4_addr_t gw

Interface IPV4 gateway address

struct esp_netif_ip6_info_t

IPV6 IP address information.

Public Members

esp_ip6_addr_t ip

Interface IPV6 address

struct ip_event_got_ip_t

Event structure for IP_EVENT_GOT_IP event.

Public Members

esp_netif_t *esp_netif

Pointer to corresponding esp-netif object

esp_netif_ip_info_t ip_info

IP address, netmask, gatway IP address

bool ip_changed

Whether the assigned IP has changed or not

struct ip_event_got_ip6_t

Event structure for IP_EVENT_GOT_IP6 event

Public Members

esp_netif_t *esp_netif

Pointer to corresponding esp-netif object

esp_netif_ip6_info_t ip6_info

IPv6 address of the interface

int ip_index

IPv6 address index

struct ip_event_add_ip6_t

Event structure for ADD_IP6 event

Public Members

esp_ip6_addr_t addr

The address to be added to the interface

bool preferred

The default preference of the address

struct ip_event_ap_staipassigned_t

Event structure for IP_EVENT_AP_STAIPASSIGNED event

Public Members

esp_netif_t *esp_netif

Pointer to the associated netif handle

esp_ip4_addr_t ip

IP address which was assigned to the station

uint8_t mac[6]

MAC address of the connected client

struct bridgeif_config

LwIP bridge configuration

Public Members

uint16_t max_fdb_dyn_entries

maximum number of entries in dynamic forwarding database

uint16_t max_fdb_sta_entries

maximum number of entries in static forwarding database

uint8_t max_ports

maximum number of ports the bridge can consist of

struct esp_netif_inherent_config

ESP-netif inherent config parameters.

Public Members

esp_netif_flags_t flags

flags that define esp-netif behavior

uint8_t mac[6]

initial mac address for this interface

const esp_netif_ip_info_t *ip_info

initial ip address for this interface

uint32_t get_ip_event

event id to be raised when interface gets an IP

uint32_t lost_ip_event

event id to be raised when interface losts its IP

const char *if_key

string identifier of the interface

const char *if_desc

textual description of the interface

int route_prio

numeric priority of this interface to become a default routing if (if other netifs are up). A higher value of route_prio indicates a higher priority

bridgeif_config_t *bridge_info

LwIP bridge configuration

struct esp_netif_driver_base_s

ESP-netif driver base handle.

Public Members

esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h)

post attach function pointer

esp_netif_t *netif

netif handle

struct esp_netif_driver_ifconfig

Specific IO driver configuration.

Public Members

esp_netif_iodriver_handle handle

io-driver handle

esp_err_t (*transmit)(void *h, void *buffer, size_t len)

transmit function pointer

esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer)

transmit wrap function pointer

void (*driver_free_rx_buffer)(void *h, void *buffer)

free rx buffer function pointer

struct esp_netif_config

Generic esp_netif configuration.

Public Members

const esp_netif_inherent_config_t *base

base config

const esp_netif_driver_ifconfig_t *driver

driver config

const esp_netif_netstack_config_t *stack

stack config

struct esp_netif_pair_mac_ip_t

DHCP client's addr info (pair of MAC and IP address)

Public Members

uint8_t mac[6]

Clients MAC address

esp_ip4_addr_t ip

Clients IP address

Macros

ESP_ERR_ESP_NETIF_BASE

Definition of ESP-NETIF based errors.

ESP_ERR_ESP_NETIF_INVALID_PARAMS
ESP_ERR_ESP_NETIF_IF_NOT_READY
ESP_ERR_ESP_NETIF_DHCPC_START_FAILED
ESP_ERR_ESP_NETIF_DHCP_ALREADY_STARTED
ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED
ESP_ERR_ESP_NETIF_NO_MEM
ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED
ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED
ESP_ERR_ESP_NETIF_INIT_FAILED
ESP_ERR_ESP_NETIF_DNS_NOT_CONFIGURED
ESP_ERR_ESP_NETIF_MLD6_FAILED
ESP_ERR_ESP_NETIF_IP6_ADDR_FAILED
ESP_ERR_ESP_NETIF_DHCPS_START_FAILED
ESP_NETIF_BR_FLOOD

Definition of ESP-NETIF bridge controll.

ESP_NETIF_BR_DROP
ESP_NETIF_BR_FDW_CPU

Type Definitions

typedef struct esp_netif_obj esp_netif_t
typedef enum esp_netif_flags esp_netif_flags_t
typedef enum esp_netif_ip_event_type esp_netif_ip_event_type_t
typedef struct bridgeif_config bridgeif_config_t

LwIP bridge configuration

typedef struct esp_netif_inherent_config esp_netif_inherent_config_t

ESP-netif inherent config parameters.

typedef struct esp_netif_config esp_netif_config_t
typedef void *esp_netif_iodriver_handle

IO driver handle type.

typedef struct esp_netif_driver_base_s esp_netif_driver_base_t

ESP-netif driver base handle.

typedef struct esp_netif_driver_ifconfig esp_netif_driver_ifconfig_t
typedef struct esp_netif_netstack_config esp_netif_netstack_config_t

Specific L3 network stack configuration.

typedef esp_err_t (*esp_netif_receive_t)(esp_netif_t *esp_netif, void *buffer, size_t len, void *eb)

ESP-NETIF Receive function type.

Enumerations

enum esp_netif_dns_type_t

Type of DNS server.

Values:

enumerator ESP_NETIF_DNS_MAIN

DNS main server address

enumerator ESP_NETIF_DNS_BACKUP

DNS backup server address (Wi-Fi STA and Ethernet only)

enumerator ESP_NETIF_DNS_FALLBACK

DNS fallback server address (Wi-Fi STA and Ethernet only)

enumerator ESP_NETIF_DNS_MAX
enum esp_netif_dhcp_status_t

Status of DHCP client or DHCP server.

Values:

enumerator ESP_NETIF_DHCP_INIT

DHCP client/server is in initial state (not yet started)

enumerator ESP_NETIF_DHCP_STARTED

DHCP client/server has been started

enumerator ESP_NETIF_DHCP_STOPPED

DHCP client/server has been stopped

enumerator ESP_NETIF_DHCP_STATUS_MAX
enum esp_netif_dhcp_option_mode_t

Mode for DHCP client or DHCP server option functions.

Values:

enumerator ESP_NETIF_OP_START
enumerator ESP_NETIF_OP_SET

Set option

enumerator ESP_NETIF_OP_GET

Get option

enumerator ESP_NETIF_OP_MAX
enum esp_netif_dhcp_option_id_t

Supported options for DHCP client or DHCP server.

Values:

enumerator ESP_NETIF_SUBNET_MASK

Network mask

enumerator ESP_NETIF_DOMAIN_NAME_SERVER

Domain name server

enumerator ESP_NETIF_ROUTER_SOLICITATION_ADDRESS

Solicitation router address

enumerator ESP_NETIF_REQUESTED_IP_ADDRESS

Request specific IP address

enumerator ESP_NETIF_IP_ADDRESS_LEASE_TIME

Request IP address lease time

enumerator ESP_NETIF_IP_REQUEST_RETRY_TIME

Request IP address retry counter

enumerator ESP_NETIF_VENDOR_CLASS_IDENTIFIER

Vendor Class Identifier of a DHCP client

enumerator ESP_NETIF_VENDOR_SPECIFIC_INFO

Vendor Specific Information of a DHCP server

enum ip_event_t

IP event declarations

Values:

enumerator IP_EVENT_STA_GOT_IP

station got IP from connected AP

enumerator IP_EVENT_STA_LOST_IP

station lost IP and the IP is reset to 0

enumerator IP_EVENT_AP_STAIPASSIGNED

soft-AP assign an IP to a connected station

enumerator IP_EVENT_GOT_IP6

station or ap or ethernet interface v6IP addr is preferred

enumerator IP_EVENT_ETH_GOT_IP

ethernet got IP from connected AP

enumerator IP_EVENT_ETH_LOST_IP

ethernet lost IP and the IP is reset to 0

enumerator IP_EVENT_PPP_GOT_IP

PPP interface got IP

enumerator IP_EVENT_PPP_LOST_IP

PPP interface lost IP

enum esp_netif_flags

Values:

enumerator ESP_NETIF_DHCP_CLIENT
enumerator ESP_NETIF_DHCP_SERVER
enumerator ESP_NETIF_FLAG_AUTOUP
enumerator ESP_NETIF_FLAG_GARP
enumerator ESP_NETIF_FLAG_EVENT_IP_MODIFIED
enumerator ESP_NETIF_FLAG_IS_PPP
enumerator ESP_NETIF_FLAG_IS_BRIDGE
enumerator ESP_NETIF_FLAG_MLDV6_REPORT
enum esp_netif_ip_event_type

Values:

enumerator ESP_NETIF_IP_EVENT_GOT_IP
enumerator ESP_NETIF_IP_EVENT_LOST_IP

Header File

  • components/esp_netif/include/esp_netif_ip_addr.h

  • This header file can be included with:

    #include "esp_netif_ip_addr.h"
    
  • This header file is a part of the API provided by the esp_netif component. To declare that your component depends on esp_netif, add the following to your CMakeLists.txt:

    REQUIRES esp_netif
    

    or

    PRIV_REQUIRES esp_netif
    

Functions

esp_ip6_addr_type_t esp_netif_ip6_get_addr_type(esp_ip6_addr_t *ip6_addr)

Get the IPv6 address type.

参数

ip6_addr -- [in] IPv6 type

返回

IPv6 type in form of enum esp_ip6_addr_type_t

static inline void esp_netif_ip_addr_copy(esp_ip_addr_t *dest, const esp_ip_addr_t *src)

Copy IP addresses.

参数
  • dest -- [out] destination IP

  • src -- [in] source IP

Structures

struct esp_ip6_addr

IPv6 address.

Public Members

uint32_t addr[4]

IPv6 address

uint8_t zone

zone ID

struct esp_ip4_addr

IPv4 address.

Public Members

uint32_t addr

IPv4 address

struct _ip_addr

IP address.

Public Members

esp_ip6_addr_t ip6

IPv6 address type

esp_ip4_addr_t ip4

IPv4 address type

union _ip_addr::[anonymous] u_addr

IP address union

uint8_t type

ipaddress type

Macros

esp_netif_htonl(x)
esp_netif_ip4_makeu32(a, b, c, d)
ESP_IP6_ADDR_BLOCK1(ip6addr)
ESP_IP6_ADDR_BLOCK2(ip6addr)
ESP_IP6_ADDR_BLOCK3(ip6addr)
ESP_IP6_ADDR_BLOCK4(ip6addr)
ESP_IP6_ADDR_BLOCK5(ip6addr)
ESP_IP6_ADDR_BLOCK6(ip6addr)
ESP_IP6_ADDR_BLOCK7(ip6addr)
ESP_IP6_ADDR_BLOCK8(ip6addr)
IPSTR
esp_ip4_addr_get_byte(ipaddr, idx)
esp_ip4_addr1(ipaddr)
esp_ip4_addr2(ipaddr)
esp_ip4_addr3(ipaddr)
esp_ip4_addr4(ipaddr)
esp_ip4_addr1_16(ipaddr)
esp_ip4_addr2_16(ipaddr)
esp_ip4_addr3_16(ipaddr)
esp_ip4_addr4_16(ipaddr)
IP2STR(ipaddr)
IPV6STR
IPV62STR(ipaddr)
ESP_IPADDR_TYPE_V4
ESP_IPADDR_TYPE_V6
ESP_IPADDR_TYPE_ANY
ESP_IP4TOUINT32(a, b, c, d)
ESP_IP4TOADDR(a, b, c, d)
ESP_IP4ADDR_INIT(a, b, c, d)
ESP_IP6ADDR_INIT(a, b, c, d)
IP4ADDR_STRLEN_MAX
ESP_IP_IS_ANY(addr)

Type Definitions

typedef struct esp_ip4_addr esp_ip4_addr_t
typedef struct esp_ip6_addr esp_ip6_addr_t
typedef struct _ip_addr esp_ip_addr_t

IP address.

Enumerations

enum esp_ip6_addr_type_t

Values:

enumerator ESP_IP6_ADDR_IS_UNKNOWN
enumerator ESP_IP6_ADDR_IS_GLOBAL
enumerator ESP_IP6_ADDR_IS_SITE_LOCAL
enumerator ESP_IP6_ADDR_IS_UNIQUE_LOCAL
enumerator ESP_IP6_ADDR_IS_IPV4_MAPPED_IPV6

Header File

  • components/esp_netif/include/esp_vfs_l2tap.h

  • This header file can be included with:

    #include "esp_vfs_l2tap.h"
    
  • This header file is a part of the API provided by the esp_netif component. To declare that your component depends on esp_netif, add the following to your CMakeLists.txt:

    REQUIRES esp_netif
    

    or

    PRIV_REQUIRES esp_netif
    

Functions

esp_err_t esp_vfs_l2tap_intf_register(l2tap_vfs_config_t *config)

Add L2 TAP virtual filesystem driver.

This function must be called prior usage of ESP-NETIF L2 TAP Interface

参数

config -- L2 TAP virtual filesystem driver configuration. Default base path /dev/net/tap is used when this paramenter is NULL.

返回

esp_err_t

  • ESP_OK on success

esp_err_t esp_vfs_l2tap_intf_unregister(const char *base_path)

Removes L2 TAP virtual filesystem driver.

参数

base_path -- Base path to the L2 TAP virtual filesystem driver. Default path /dev/net/tap is used when this paramenter is NULL.

返回

esp_err_t

  • ESP_OK on success

esp_err_t esp_vfs_l2tap_eth_filter(l2tap_iodriver_handle driver_handle, void *buff, size_t *size)

Filters received Ethernet L2 frames into L2 TAP infrastructure.

参数
  • driver_handle -- handle of driver at which the frame was received

  • buff -- received L2 frame

  • size -- input length of the L2 frame which is set to 0 when frame is filtered into L2 TAP

返回

esp_err_t

  • ESP_OK is always returned

Structures

struct l2tap_vfs_config_t

L2Tap VFS config parameters.

Public Members

const char *base_path

vfs base path

Macros

L2TAP_VFS_DEFAULT_PATH
L2TAP_VFS_CONFIG_DEFAULT()

Type Definitions

typedef void *l2tap_iodriver_handle

Enumerations

enum l2tap_ioctl_opt_t

Values:

enumerator L2TAP_S_RCV_FILTER
enumerator L2TAP_G_RCV_FILTER
enumerator L2TAP_S_INTF_DEVICE
enumerator L2TAP_G_INTF_DEVICE
enumerator L2TAP_S_DEVICE_DRV_HNDL
enumerator L2TAP_G_DEVICE_DRV_HNDL

Wi-Fi 默认 API 参考

Header File

  • components/esp_wifi/include/esp_wifi_default.h

  • This header file can be included with:

    #include "esp_wifi_default.h"
    
  • This header file is a part of the API provided by the esp_wifi component. To declare that your component depends on esp_wifi, add the following to your CMakeLists.txt:

    REQUIRES esp_wifi
    

    or

    PRIV_REQUIRES esp_wifi
    

Functions

esp_err_t esp_netif_attach_wifi_station(esp_netif_t *esp_netif)

Attaches wifi station interface to supplied netif.

参数

esp_netif -- instance to attach the wifi station to

返回

  • ESP_OK on success

  • ESP_FAIL if attach failed

esp_err_t esp_netif_attach_wifi_ap(esp_netif_t *esp_netif)

Attaches wifi soft AP interface to supplied netif.

参数

esp_netif -- instance to attach the wifi AP to

返回

  • ESP_OK on success

  • ESP_FAIL if attach failed

esp_err_t esp_wifi_set_default_wifi_sta_handlers(void)

Sets default wifi event handlers for STA interface.

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_err_t esp_wifi_set_default_wifi_ap_handlers(void)

Sets default wifi event handlers for AP interface.

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_err_t esp_wifi_set_default_wifi_nan_handlers(void)

Sets default wifi event handlers for NAN interface.

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_err_t esp_wifi_clear_default_wifi_driver_and_handlers(void *esp_netif)

Clears default wifi event handlers for supplied network interface.

参数

esp_netif -- instance of corresponding if object

返回

  • ESP_OK on success, error returned from esp_event_handler_register if failed

esp_netif_t *esp_netif_create_default_wifi_ap(void)

Creates default WIFI AP. In case of any init error this API aborts.

备注

The API creates esp_netif object with default WiFi access point config, attaches the netif to wifi and registers wifi handlers to the default event loop. This API uses assert() to check for potential errors, so it could abort the program. (Note that the default event loop needs to be created prior to calling this API)

返回

pointer to esp-netif instance

esp_netif_t *esp_netif_create_default_wifi_sta(void)

Creates default WIFI STA. In case of any init error this API aborts.

备注

The API creates esp_netif object with default WiFi station config, attaches the netif to wifi and registers wifi handlers to the default event loop. This API uses assert() to check for potential errors, so it could abort the program. (Note that the default event loop needs to be created prior to calling this API)

返回

pointer to esp-netif instance

esp_netif_t *esp_netif_create_default_wifi_nan(void)

Creates default WIFI NAN. In case of any init error this API aborts.

备注

The API creates esp_netif object with default WiFi station config, attaches the netif to wifi and registers wifi handlers to the default event loop. (Note that the default event loop needs to be created prior to calling this API)

返回

pointer to esp-netif instance

void esp_netif_destroy_default_wifi(void *esp_netif)

Destroys default WIFI netif created with esp_netif_create_default_wifi_...() API.

备注

This API unregisters wifi handlers and detaches the created object from the wifi. (this function is a no-operation if esp_netif is NULL)

参数

esp_netif -- [in] object to detach from WiFi and destroy

esp_netif_t *esp_netif_create_wifi(wifi_interface_t wifi_if, const esp_netif_inherent_config_t *esp_netif_config)

Creates esp_netif WiFi object based on the custom configuration.

Attention

This API DOES NOT register default handlers!

参数
  • wifi_if -- [in] type of wifi interface

  • esp_netif_config -- [in] inherent esp-netif configuration pointer

返回

pointer to esp-netif instance

esp_err_t esp_netif_create_default_wifi_mesh_netifs(esp_netif_t **p_netif_sta, esp_netif_t **p_netif_ap)

Creates default STA and AP network interfaces for esp-mesh.

Both netifs are almost identical to the default station and softAP, but with DHCP client and server disabled. Please note that the DHCP client is typically enabled only if the device is promoted to a root node.

Returns created interfaces which could be ignored setting parameters to NULL if an application code does not need to save the interface instances for further processing.

参数
  • p_netif_sta -- [out] pointer where the resultant STA interface is saved (if non NULL)

  • p_netif_ap -- [out] pointer where the resultant AP interface is saved (if non NULL)

返回

ESP_OK on success