ESP-NETIF¶

The purpose of ESP-NETIF library is twofold:

It provides an abstraction layer for the application on top of the TCP/IP stack. This will allow applications to choose between IP stacks in the future.
The APIs it provides are thread safe, even if the underlying TCP/IP stack APIs are not.

ESP-IDF currently implements ESP-NETIF for the lwIP TCP/IP stack only. However, the adapter itself is TCP/IP implementation agnostic and different implementations are possible.

Some ESP-NETIF API functions are intended to be called by application code, for example to get/set interface IP addresses, configure DHCP. Other functions are intended for internal ESP-IDF use by the network driver layer.

In many cases, applications do not need to call ESP-NETIF APIs directly as they are called from the default network event handlers.

ESP-NETIF component is a successor of the tcpip_adapter, former network interface abstraction, which has become deprecated since IDF v4.1. Please refer to the TCP/IP 适配器迁移指南 section in case existing applications to be ported to use the esp-netif API instead.

ESP-NETIF architecture¶

                 |          (A) USER CODE                 |
                 |                                        |
    .............| init          settings      events     |
    .            +----------------------------------------+
    .               .                |           *
    .               .                |           *
--------+        +===========================+   *     +-----------------------+
        |        | new/config     get/set    |   *     |                       |
        |        |                           |...*.....| init                  |
        |        |---------------------------|   *     |                       |
  init  |        |                           |****     |                       |
  start |********|  event handler            |*********|  DHCP                 |
  stop  |        |                           |         |                       |
        |        |---------------------------|         |                       |
        |        |                           |         |    NETIF              |
  +-----|        |                           |         +-----------------+     |
  | glue|----<---|  esp_netif_transmit       |--<------| netif_output    |     |
  |     |        |                           |         |                 |     |
  |     |---->---|  esp_netif_receive        |-->------| netif_input     |     |
  |     |        |                           |         + ----------------+     |
  |     |....<...|  esp_netif_free_rx_buffer |...<.....| packet buffer         |
  +-----|        |                           |         |                       |
        |        |                           |         |         (D)           |
  (B)   |        |          (C)              |         +-----------------------+
--------+        +===========================+
communication                                                NETWORK STACK
DRIVER                   ESP-NETIF

Data and event flow in the diagram¶

........ Initialization line from user code to ESP-NETIF and communication driver
--<--->-- Data packets going from communication media to TCP/IP stack and back
******** Events aggregated in ESP-NETIF propagates to driver, user code and network stack
| User settings and runtime configuration

ESP-NETIF interaction¶

A) User code, boiler plate¶

Overall application interaction with a specific IO driver for communication media and configured TCP/IP network stack is abstracted using ESP-NETIF APIs and outlined as below:

Initialization code

Initializes IO driver

Creates a new instance of ESP-NETIF and configure with

ESP-NETIF specific options (flags, behaviour, name)

Network stack options (netif init and input functions, not publicly available)

IO driver specific options (transmit, free rx buffer functions, IO driver handle)

Attaches the IO driver handle to the ESP-NETIF instance created in the above steps

Configures event handlers

use default handlers for common interfaces defined in IO drivers; or define a specific handlers for customised behaviour/new interfaces

register handlers for app related events (such as IP lost/acquired)

Interaction with network interfaces using ESP-NETIF API

Getting and setting TCP/IP related parameters (DHCP, IP, etc)

Receiving IP events (connect/disconnect)

Controlling application lifecycle (set interface up/down)

B) Communication driver, IO driver, media driver¶

Communication driver plays these two important roles in relation with ESP-NETIF:

Event handlers: Define behaviour patterns of interaction with ESP-NETIF (for example: ethernet link-up -> turn netif on)
Glue IO layer: Adapts the input/output functions to use ESP-NETIF transmit, receive and free receive buffer

Installs driver_transmit to appropriate ESP-NETIF object, so that outgoing packets from network stack are passed to the IO driver

Calls esp_netif_receive() to pass incoming data to network stack

C) ESP-NETIF, former tcpip_adapter¶

ESP-NETIF is an intermediary between an IO driver and a network stack, connecting packet data path between these two. As that it provides a set of interfaces for attaching a driver to ESP-NETIF object (runtime) and configuring a network stack (compile time). In addition to that a set of API is provided to control network interface lifecycle and its TCP/IP properties. As an overview, the ESP-NETIF public interface could be divided into these 6 groups:

Initialization APIs (to create and configure ESP-NETIF instance)
Input/Output API (for passing data between IO driver and network stack)
Event or Action API

Used for network interface lifecycle management

ESP-NETIF provides building blocks for designing event handlers

Setters and Getters for basic network interface properties
Network stack abstraction: enabling user interaction with TCP/IP stack

Set interface up or down

DHCP server and client API

DNS API

Driver conversion utilities

D) Network stack¶

Network stack has no public interaction with application code with regard to public interfaces and shall be fully abstracted by ESP-NETIF API.

ESP-NETIF programmer’s manual¶

Please refer to the example section for basic initialization of default interfaces:

WiFi Station: examples/wifi/getting_started/station/main/station_example_main.c
WiFi Access Point: examples/wifi/getting_started/softAP/main/softap_example_main.c
Ethernet examples/ethernet/basic/main/ethernet_example_main.c

For more specific cases please consult this guide: ESP-NETIF Custom I/O Driver.

WiFi default initialization¶

The initialization code as well as registering event handlers for default interfaces, such as softAP and station, are provided in two separate APIs to facilitate simple startup code for most applications:

esp_netif_create_default_wifi_ap()
esp_netif_create_default_wifi_sta()

Please note that these functions return the esp_netif handle, i.e. a pointer to a network interface object allocated and configured with default settings, which as a consequence, means that:

The created object has to be destroyed if a network de-initialization is provided by an application.
These default interfaces must not be created multiple times, unless the created handle is deleted using esp_netif_destroy().
When using Wifi in AP+STA mode, both these interfaces has to be created.

API Reference¶

Header File¶

esp_netif/include/esp_netif.h

Functions¶

esp_err_t esp_netif_init(void)¶

Initialize the underlying TCP/IP stack.

Return

ESP_OK on success
ESP_FAIL if initializing failed

Note

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

esp_err_t esp_netif_deinit(void)¶

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

     Note: Deinitialization is not supported yet

Return

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.

Return

pointer to esp-netif object on success
NULL otherwise

Parameters

[in] esp_netif_config: pointer esp-netif configuration

void esp_netif_destroy(esp_netif_t *esp_netif)¶

Destroys the esp_netif object.

Parameters

[in] esp_netif: 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.

Return

ESP_OK on success
ESP_ERR_ESP_NETIF_INVALID_PARAMS if invalid parameters provided

Parameters

[inout] esp_netif: pointer to the object to be configured
[in] driver_config: pointer esp-netif io driver related configuration

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)

Return

ESP_OK on success
ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED if driver’s pot_attach callback failed

Parameters

[inout] esp_netif: pointer to esp_netif object to be attached
[in] driver_handle: pointer to the driver handle

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.

Return

ESP_OK

Parameters

[in] esp_netif: Handle to esp-netif instance
[in] buffer: Received data
[in] len: Length of the data frame
[in] eb: Pointer to internal buffer (used in Wi-Fi driver)

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.

Note