Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

esp_netif: documentation udpated and grouped the esp-netif API

Browse source 
structure. Updated rst documenentation and diagram of esp-netif
cooperation with other components.
This commit is contained in:
David Cermak 2019-09-12 09:24:56 +02:00
parent eb94d87935
commit d471266b46
14 changed files with 372 additions and 114 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
components/esp_common/src/esp_err_to_name.c
View file

@ -479,8 +479,8 @@ static const esp_err_msg_t esp_err_msg_table[] = {
# ifdef ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED
ERR_TBL_IT(ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED), /* 20487 0x5007 */
# endif
# ifdef ESP_ERR_ESP_NETIF_DRIVER_ATACH_FAILED
ERR_TBL_IT(ESP_ERR_ESP_NETIF_DRIVER_ATACH_FAILED), /* 20488 0x5008 */
# ifdef ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED
ERR_TBL_IT(ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED), /* 20488 0x5008 */
# endif
// components/esp_common/include/esp_err.h
# ifdef ESP_ERR_FLASH_BASE

247
components/esp_netif/include/esp_netif.h
View file

@ -22,9 +22,15 @@
#include "esp_netif_types.h"
#include "esp_netif_defaults.h"
//
// 1) Initialization API:
//
/**
* @defgroup ESP_NETIF_INIT_API ESP-NETIF Initialization API
* @brief Initialization and deinitialization of underlying TCP/IP stack and esp-netif instances
*
*/
/** @addtogroup ESP_NETIF_INIT_API
* @{
*/
/**
* @brief Initialize the underlying TCP/IP stack
@ -62,14 +68,14 @@ esp_netif_t *esp_netif_new(const esp_netif_config_t *esp_netif_config);
/**
* @brief Destroys the esp_netif object
*
* @param[in] pointer to the object to be deleted
* @param[in] esp_netif pointer to the object to be deleted
*/
void esp_netif_destroy(esp_netif_t *esp_netif);
/**
* @brief Configures driver related options of esp_netif object
*
* @param[inout] pointer to the object to be configured
* @param[inout] esp_netif pointer to the object to be configured
* @param[in] driver_config pointer esp-netif io driver related configuration
* @return
* - ESP_OK on success
@ -79,40 +85,46 @@ void esp_netif_destroy(esp_netif_t *esp_netif);
esp_err_t esp_netif_set_driver_config(esp_netif_t *esp_netif,
const esp_netif_driver_ifconfig_t *driver_config);
/**
* @brief 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)
*
* @param[inout] esp_netif pointer to esp_netif object to be attached
* @param[in] driver_handle pointer to the driver handle
* @return
* - ESP_OK on success
* - ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED if driver's pot_attach callback failed
*/
esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle driver_handle);
//
// 2) Input - Output APIs
//
/**
* @}
*/
/**
* @brief Outputs packets from the TCP/IP stack to the media to be transmitted
*
* This function gets called from network stack to output packets to IO driver.
*
* @note This function is installed automatically for default interfaces.
* Custom interface may need to install if the rx buffer passed as pointer and the IO driver has to
* deallocate the data in driver context
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] void* buffer: rx buffer pointer
*/
esp_err_t esp_netif_transmit(esp_netif_t *esp_netif, void* data, size_t len);
* @defgroup ESP_NETIF_DATA_IO_API ESP-NETIF Input Output API
* @brief Input and Output functions to pass data packets from communication media (IO driver)
* to TCP/IP stack.
*
* These functions are usually not directly called from user code, but installed, or registered
* as callbacks in either IO driver on one hand or TCP/IP stack on the other. More specifically
* esp_netif_receive is typically called from io driver on reception callback to input the packets
* to TCP/IP stack. Similarly esp_netif_transmit is called from the TCP/IP stack whenever
* a packet ought to output to the communication media.
*
* @note These IO functions are registerd (installed) automatically for default interfaces
* (interfaces with the keys such as WIFI_STA_DEF, WIFI_AP_DEF, ETH_DEF). Custom interface
* has to register these IO functions when creating interface using @ref esp_netif_new
*
*/
/**
* @brief Free the rx buffer allocated by the media driver
*
* This function gets called from network stack when the rx buffer to be freed in media driver context.
*
* @note This function is installed automatically for default interfaces.
* Custom interface may need to install if the rx buffer passed as pointer and the IO driver has to
* deallocate the data in driver context
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] void* buffer: rx buffer pointer
*/
void esp_netif_free_rx_buffer(void *esp_netif, void* buffer);
/** @addtogroup ESP_NETIF_DATA_IO_API
* @{
*/
/**
* @brief Passes the raw packets from communication media to the appropriate TCP/IP stack
@ -120,11 +132,6 @@ void esp_netif_free_rx_buffer(void *esp_netif, void* buffer);
* This function is called from the configured (peripheral) driver layer.
* The data are then forwarded as frames to the TCP/IP stack.
*
* @note Installation happens automatically for default interfaces; custom IO drivers must install
* this function so that it is called on a reception of incoming packet
*
* @note Application code does not usually need to call this function directly.
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] buffer Received data
* @param[in] len Length of the data frame
@ -135,10 +142,20 @@ void esp_netif_free_rx_buffer(void *esp_netif, void* buffer);
*/
esp_err_t esp_netif_receive(esp_netif_t *esp_netif, void *buffer, size_t len, void *eb);
//
// 3) ESP-NETIF lifecycle
//
/**
* @}
*/
/**
* @defgroup ESP_NETIF_LIFECYCLE ESP-NETIF Lifecycle control
* @brief These APIS define basic building blocks to control network interface lifecycle, i.e.
* start, stop, set_up or set_down. These functions can be directly used as event handlers
* registered to follow the events from communication media.
*/
/** @addtogroup ESP_NETIF_LIFECYCLE
* @{
*/
/**
* @brief Default building block for network interface action upon IO driver start event
@ -202,9 +219,28 @@ void esp_netif_action_disconnected(void *esp_netif, esp_event_base_t base, int32
*/
void esp_netif_action_got_ip(void *esp_netif, esp_event_base_t base, int32_t event_id, void *data);
//
/// 4) Configuration (getter - setters)
//
/**
* @}
*/
/**
* @defgroup ESP_NETIF_GET_SET ESP-NETIF Runtime configuration
* @brief Getters and setters for various TCP/IP related parameters
*/
/** @addtogroup ESP_NETIF_GET_SET
* @{
*/
/**
* @brief Set the mac address for the interface instance
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] mac Desired mac address for the related network interface
* @return ESP_OK
*/
esp_err_t esp_netif_set_mac(esp_netif_t *esp_netif, uint8_t mac[]);
/**
* @brief Set the hostname of an interface
*
@ -317,14 +353,31 @@ esp_err_t esp_netif_set_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_
*/
esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_info_t *ip_info);
/**
* @brief Get net interface index from network stack implementation
*
* @note This index could be used in `setsockopt()` to bind socket with multicast interface
*
* @param[in] esp_netif Handle to esp-netif instance
*
* @return
* implementation specific index of interface represented with supplied esp_netif
*/
int esp_netif_get_netif_impl_index(esp_netif_t *esp_netif);
//
// 5) Network stack related API
//
/**
* @}
*/
/**
* @defgroup ESP_NETIF_NET_DHCP ESP-NETIF DHCP Settings
* @brief Network stack related interface to DHCP client and server
*/
/** @addtogroup ESP_NETIF_NET_DHCP
* @{
*/
//
// DHCP
//
/**
* @brief Set or Get DHCP server option
*
@ -342,6 +395,21 @@ esp_err_t esp_netif_set_old_ip_info(esp_netif_t *esp_netif, const esp_netif_ip_i
*/
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);
/**
* @brief Set or Get DHCP client option
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] opt_op ESP_NETIF_OP_SET to set an option, ESP_NETIF_OP_GET to get an option.
* @param[in] opt_id Option index to get or set, must be one of the supported enum values.
* @param[inout] opt_val Pointer to the option parameter.
* @param[in] opt_len Length of the option parameter.
*
* @return
* - 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);
/**
@ -421,9 +489,19 @@ esp_err_t esp_netif_dhcps_start(esp_netif_t *esp_netif);
*/
esp_err_t esp_netif_dhcps_stop(esp_netif_t *esp_netif);
//
// DNS:
//
/**
* @}
*/
/**
* @defgroup ESP_NETIF_NET_DNS ESP-NETIF DNS Settings
* @brief Network stack related interface to NDS
*/
/** @addtogroup ESP_NETIF_NET_DNS
* @{
*/
/**
* @brief Set DNS Server information
*
@ -467,14 +545,19 @@ esp_err_t esp_netif_set_dns_info(esp_netif_t *esp_netif, esp_netif_dns_type_t ty
* - 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);
/**
* @brief Set the mac address for the interface instance
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] mac Desired mac address for the related network interface
* @return ESP_OK
/**
* @}
*/
/**
* @defgroup ESP_NETIF_NET_IP ESP-NETIF IP address related interface
* @brief Network stack related interface to IP
*/
/** @addtogroup ESP_NETIF_NET_IP
* @{
*/
esp_err_t esp_netif_set_mac(esp_netif_t *esp_netif, uint8_t mac[]);
/**
* @brief Create interface link-local IPv6 address
@ -540,9 +623,18 @@ char * esp_ip4addr_ntoa(const esp_ip4_addr_t *addr, char *buf, int buflen);
*/
uint32_t esp_ip4addr_aton(const char *addr);
//
// 6) Driver conversion utilities to related keys, flags, implementation handle, list of netifs
//
/**
* @}
*/
/**
* @defgroup ESP_NETIF_CONVERT ESP-NETIF Conversion utilities
* @brief ESP-NETIF conversion utilities to related keys, flags, implementation handle
*/
/** @addtogroup ESP_NETIF_CONVERT
* @{
*/
/**
* @brief Gets media driver handle for this esp-netif instance
@ -600,9 +692,19 @@ esp_netif_type_t esp_netif_get_type(esp_netif_t *esp_netif);
*/
uint32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_t event_type);
//
// 7) esp_netif list API
//
/**
* @}
*/
/**
* @defgroup ESP_NETIF_LIST ESP-NETIF List of interfaces
* @brief APIs to enumerate all registered interfaces
*/
/** @addtogroup ESP_NETIF_LIST
* @{
*/
/**
* @brief Iterates over list of interfaces. Returns first netif if NULL given as parameter
*
@ -610,7 +712,7 @@ uint32_t esp_netif_get_event_id(esp_netif_t *esp_netif, esp_netif_ip_event_type_
*
* @return First netif from the list if supplied parameter is NULL, next one otherwise
*/
esp_netif_t* esp_netif_next(esp_netif_t* netif);
esp_netif_t* esp_netif_next(esp_netif_t* esp_netif);
/**
* @brief Returns number of registered esp_netif objects
@ -636,16 +738,5 @@ size_t esp_netif_get_nr_of_ifs(void);
*/
esp_err_t esp_netif_get_sta_list(const wifi_sta_list_t *wifi_sta_list, esp_netif_sta_list_t *tcpip_sta_list);
/**
* @brief Get net interface index from network stack implementation
*
* @note This index could be used in `setsockopt()` to bind socket with multicast interface
*
* @param[in] esp_netif Handle to esp-netif instance
*
* @return
* implementation specific index of interface represented with supplied esp_netif
*/
int esp_netif_get_netif_impl_index(esp_netif_t *esp_netif);
#endif /* _ESP_NETIF_H_ */

40
components/esp_netif/include/esp_netif_net_stack.h
View file

@ -19,6 +19,10 @@
// Network stack API: This ESP-NETIF API are supposed to be called only from internals of TCP/IP stack
//
/** @addtogroup ESP_NETIF_CONVERT
* @{
*/
/**
* @brief Returns esp-netif handle
*
@ -28,7 +32,6 @@
*/
esp_netif_t* esp_netif_get_handle_from_netif_impl(void *dev);
/**
* @brief Returns network stack specific implementation handle
*
@ -38,4 +41,39 @@ esp_netif_t* esp_netif_get_handle_from_netif_impl(void *dev);
*/
void* esp_netif_get_netif_impl(esp_netif_t *esp_netif);
/**
* @}
*/
/** @addtogroup ESP_NETIF_DATA_IO_API
* @{
*/
/**
* @brief Outputs packets from the TCP/IP stack to the media to be transmitted
*
* This function gets called from network stack to output packets to IO driver.
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] data Data to be tranmitted
* @param[in] len Length of the data frame
*/
esp_err_t esp_netif_transmit(esp_netif_t *esp_netif, void* data, size_t len);
/**
* @brief Free the rx buffer allocated by the media driver
*
* This function gets called from network stack when the rx buffer to be freed in IO driver context,
* i.e. to deallocate a buffer owned by io driver (when data packets were passed to higher levels
* to avoid copying)
*
* @param[in] esp_netif Handle to esp-netif instance
* @param[in] void* buffer: rx buffer pointer
*/
void esp_netif_free_rx_buffer(void *esp_netif, void* buffer);
/**
* @}
*/
#endif //_ESP_NETIF_NET_STACK_H_

2
components/esp_netif/include/esp_netif_types.h
View file

@ -26,7 +26,7 @@
#define ESP_ERR_ESP_NETIF_DHCP_ALREADY_STOPPED ESP_ERR_ESP_NETIF_BASE + 0x05
#define ESP_ERR_ESP_NETIF_NO_MEM ESP_ERR_ESP_NETIF_BASE + 0x06
#define ESP_ERR_ESP_NETIF_DHCP_NOT_STOPPED ESP_ERR_ESP_NETIF_BASE + 0x07
#define ESP_ERR_ESP_NETIF_DRIVER_ATACH_FAILED ESP_ERR_ESP_NETIF_BASE + 0x08
#define ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED ESP_ERR_ESP_NETIF_BASE + 0x08
/** @brief Type of esp_netif_object server */

2
components/esp_netif/lwip/esp_netif_lwip.c
View file

@ -468,7 +468,7 @@ esp_err_t esp_netif_attach(esp_netif_t *esp_netif, esp_netif_iodriver_handle dri
esp_err_t ret = base_driver->post_attach(esp_netif, driver_handle);
if (ret != ESP_OK) {
ESP_LOGE(TAG, "Post-attach callback of driver(%p) failed with %d", driver_handle, ret);
return ESP_ERR_ESP_NETIF_DRIVER_ATACH_FAILED;
return ESP_ERR_ESP_NETIF_DRIVER_ATTACH_FAILED;
}
}
return ESP_OK;

4
docs/Doxyfile
View file

@ -109,8 +109,8 @@ INPUT = \
../../components/soc/esp32/include/soc/touch_channel.h \
../../components/soc/esp32/include/soc/uart_channel.h \
../../components/soc/esp32/include/soc/rtc_gpio_channel.h \
## tcpip_adapter - API Reference
../../components/tcpip_adapter/include/tcpip_adapter.h \
## esp_netif - API Reference
../../components/esp_netif/include/esp_netif.h \
##
## Protocols - API Reference
##

2
docs/en/api-guides/lwip.rst
View file

@ -16,7 +16,7 @@ Adapted APIs
Some common lwIP "app" APIs are supported indirectly by ESP-IDF:
- DHCP Server & Client are supported indirectly via the :doc:`/api-reference/network/tcpip_adapter` functionality
- DHCP Server & Client are supported indirectly via the :doc:`/api-reference/network/esp_netif` functionality
- Simple Network Time Protocol (SNTP) is supported via the :component_file:`lwip/include/apps/esp_sntp.h` functions (see also :example:`protocols/sntp`)
- ICMP Ping is supported using a variation on the lwIP ping API. See :doc:`/api-reference/protocols/icmp_echo`.
- NetBIOS lookup is available using the standard lwIP API. :example:`protocols/http_server/restful_server` has an option to demonstrate using NetBIOS to look up a host on the LAN.

12
docs/en/api-guides/wifi.rst
View file

@ -122,7 +122,7 @@ The ESP32 Wi-Fi programming model is depicted as follows:
The Wi-Fi driver can be considered a black box that knows nothing about high-layer code, such as the TCP/IP stack, application task, event task, etc. The application task (code) generally calls :doc:`Wi-Fi driver APIs <../api-reference/network/esp_wifi>` to initialize Wi-Fi and handles Wi-Fi events when necessary. Wi-Fi driver receives API calls, handles them, and post events to the application.
Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`tcpip_adapter component <../api-reference/network/tcpip_adapter>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, tcpip_adapter will automatically start the DHCP client.
Wi-Fi event handling is based on the :doc:`esp_event library <../api-reference/system/esp_event>`. Events are sent by the Wi-Fi driver to the :ref:`default event loop <esp-event-default-loops>`. Application may handle these events in callbacks registered using :cpp:func:`esp_event_handler_register`. Wi-Fi events are also handled by :doc:`esp_netif component <../api-reference/network/esp_netif>` to provide a set of default behaviors. For example, when Wi-Fi station connects to an AP, esp_netif will automatically start the DHCP client (by default).
ESP32 Wi-Fi Event Description
------------------------------------
@ -300,15 +300,17 @@ Below is a "big scenario" which describes some small scenarios in Station mode:
1. Wi-Fi/LwIP Init Phase
++++++++++++++++++++++++++++++
- s1.1: The main task calls tcpip_adapter_init() to create an LwIP core task and initialize LwIP-related work.
- s1.1: The main task calls esp_netif_init() to create an LwIP core task and initialize LwIP-related work.
- s1.2: The main task calls esp_event_loop_init() to create a system Event task and initialize an application event's callback function. In the scenario above, the application event's callback function does nothing but relaying the event to the application task.
- s1.3: The main task calls esp_wifi_init() to create the Wi-Fi driver task and initialize the Wi-Fi driver.
- s1.3: The main task calls esp_netif_create_default_wifi_ap() or esp_netif_create_default_wifi_sta() to create default network interface instance binding station or AP with TCP/IP stack.
- s1.4: The main task calls OS API to create the application task.
- s1.4: The main task calls esp_wifi_init() to create the Wi-Fi driver task and initialize the Wi-Fi driver.
Step 1.1~1.4 is a recommended sequence that initializes a Wi-Fi-/LwIP-based application. However, it is **NOT** a must-follow sequence, which means that you can create the application task in step 1.1 and put all other initializations in the application task. Moreover, you may not want to create the application task in the initialization phase if the application task depends on the sockets. Rather, you can defer the task creation until the IP is obtained.
- s1.5: The main task calls OS API to create the application task.
Step 1.1~1.5 is a recommended sequence that initializes a Wi-Fi-/LwIP-based application. However, it is **NOT** a must-follow sequence, which means that you can create the application task in step 1.1 and put all other initializations in the application task. Moreover, you may not want to create the application task in the initialization phase if the application task depends on the sockets. Rather, you can defer the task creation until the IP is obtained.
2. Wi-Fi Configuration Phase
+++++++++++++++++++++++++++++++

146
docs/en/api-reference/network/esp_netif.rst Normal file
View file

@ -0,0 +1,146 @@
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 architecture
======================
.. code-block:: text
| (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:
A) Initialization code
1) Initializes IO driver
2) 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)
3) Attaches the IO driver handle to the ESP-NETIF instance created in the above steps
4) 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)
B) 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)
Please note that the initialization code as well as registering event handlers for default interfaces,
such as WiFi softAP and WiFi station, are provided as a separate APIs (for example ``esp_netif_create_default_wifi_ap()`` and
``esp_netif_create_default_wifi_sta()``) to facilitate simple startup code for most applications.
B) Communication driver, IO driver, media driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Communication driver plays these two important roles in relation with ESP-NETIF:
1) Event handlers: Define behaviour patterns of interaction with ESP-NETIF (for example: ethernet link-up -> turn netif on)
2) 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:
1) Initialization APIs (to create and configure ESP-NETIF instance)
2) Input/Output API (for passing data between IO driver and network stack)
3) Event or Action API
* Used for network interface lifecycle management
* ESP-NETIF provides building blocks for designing event handlers
4) Setters and Getters for basic network interface properties
5) Network stack abstraction: enabling user interaction with TCP/IP stack
* Set interface up or down
* DHCP server and client API
* DNS API
6) 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.
API Reference
-------------
.. include:: /_build/inc/esp_netif.inc

2
docs/en/api-reference/network/index.rst
View file

@ -36,7 +36,7 @@ IP Network Layer
.. toctree::
:maxdepth: 1
TCP/IP Adapter <tcpip_adapter.rst>
ESP-NETIF <esp_netif.rst>
Code examples for TCP/IP socket APIs are provided in the :example:`protocols/sockets` directory of ESP-IDF examples.

19
docs/en/api-reference/network/tcpip_adapter.rst
View file

@ -1,19 +0,0 @@
TCP/IP Adapter
==============
The purpose of TCP/IP Adapter 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 TCP/IP Adapter for the lwIP TCP/IP stack only. However, the adapter itself is TCP/IP implementation agnostic and different implementations are possible.
Some TCP/IP Adapter 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 TCP/IP Adapter APIs directly as they are called from the default network event handlers.
API Reference
-------------
.. include:: /_build/inc/tcpip_adapter.inc

2
docs/zh_CN/api-reference/network/esp_netif.rst Normal file
View file

@ -0,0 +1,2 @@
.. include:: ../../../en/api-reference/network/esp_netif.rst

2
docs/zh_CN/api-reference/network/index.rst
View file

@ -36,7 +36,7 @@ IP 网络层协议
.. toctree::
:maxdepth: 1
TCP/IP Adapter <tcpip_adapter.rst>
ESP-NETIF <esp_netif.rst>
TCP/IP 套接字 API 的示例代码存放在 ESP-IDF 示例项目的 :example:`protocols/sockets` 目录下。

2
docs/zh_CN/api-reference/network/tcpip_adapter.rst
View file

@ -1,2 +0,0 @@
.. include:: ../../../en/api-reference/network/tcpip_adapter.rst