diff --git a/components/esp_common/src/esp_err_to_name.c b/components/esp_common/src/esp_err_to_name.c index 97d12112a..1a06c9905 100644 --- a/components/esp_common/src/esp_err_to_name.c +++ b/components/esp_common/src/esp_err_to_name.c @@ -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 diff --git a/components/esp_netif/include/esp_netif.h b/components/esp_netif/include/esp_netif.h index 4d690c275..e06a3f583 100644 --- a/components/esp_netif/include/esp_netif.h +++ b/components/esp_netif/include/esp_netif.h @@ -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_ */ diff --git a/components/esp_netif/include/esp_netif_net_stack.h b/components/esp_netif/include/esp_netif_net_stack.h index bfef36fd0..d2a6b0f0c 100644 --- a/components/esp_netif/include/esp_netif_net_stack.h +++ b/components/esp_netif/include/esp_netif_net_stack.h @@ -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_ diff --git a/components/esp_netif/include/esp_netif_types.h b/components/esp_netif/include/esp_netif_types.h index 7f08bf1cf..960df2d88 100644 --- a/components/esp_netif/include/esp_netif_types.h +++ b/components/esp_netif/include/esp_netif_types.h @@ -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 */ diff --git a/components/esp_netif/lwip/esp_netif_lwip.c b/components/esp_netif/lwip/esp_netif_lwip.c index 1fc0e3c81..751b00653 100644 --- a/components/esp_netif/lwip/esp_netif_lwip.c +++ b/components/esp_netif/lwip/esp_netif_lwip.c @@ -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; diff --git a/docs/Doxyfile b/docs/Doxyfile index dc233500d..af1a5b342 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -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 ## diff --git a/docs/en/api-guides/lwip.rst b/docs/en/api-guides/lwip.rst index 4eb528b61..3c5199e8a 100644 --- a/docs/en/api-guides/lwip.rst +++ b/docs/en/api-guides/lwip.rst @@ -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. diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index 02f488fa3..c47669111 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -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 `. 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 `. 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 +++++++++++++++++++++++++++++++ diff --git a/docs/en/api-reference/network/esp_netif.rst b/docs/en/api-reference/network/esp_netif.rst new file mode 100644 index 000000000..eeae49b31 --- /dev/null +++ b/docs/en/api-reference/network/esp_netif.rst @@ -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 + diff --git a/docs/en/api-reference/network/index.rst b/docs/en/api-reference/network/index.rst index cb5c5801b..93adede1d 100644 --- a/docs/en/api-reference/network/index.rst +++ b/docs/en/api-reference/network/index.rst @@ -36,7 +36,7 @@ IP Network Layer .. toctree:: :maxdepth: 1 - TCP/IP Adapter + ESP-NETIF Code examples for TCP/IP socket APIs are provided in the :example:`protocols/sockets` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/network/tcpip_adapter.rst b/docs/en/api-reference/network/tcpip_adapter.rst deleted file mode 100644 index e3b8fdd53..000000000 --- a/docs/en/api-reference/network/tcpip_adapter.rst +++ /dev/null @@ -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 - diff --git a/docs/zh_CN/api-reference/network/esp_netif.rst b/docs/zh_CN/api-reference/network/esp_netif.rst new file mode 100644 index 000000000..b48cbe39b --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_netif.rst @@ -0,0 +1,2 @@ +.. include:: ../../../en/api-reference/network/esp_netif.rst + diff --git a/docs/zh_CN/api-reference/network/index.rst b/docs/zh_CN/api-reference/network/index.rst index 3a7856001..83bc3ce5b 100644 --- a/docs/zh_CN/api-reference/network/index.rst +++ b/docs/zh_CN/api-reference/network/index.rst @@ -36,7 +36,7 @@ IP 网络层协议 .. toctree:: :maxdepth: 1 - TCP/IP Adapter + ESP-NETIF TCP/IP 套接字 API 的示例代码存放在 ESP-IDF 示例项目的 :example:`protocols/sockets` 目录下。 diff --git a/docs/zh_CN/api-reference/network/tcpip_adapter.rst b/docs/zh_CN/api-reference/network/tcpip_adapter.rst deleted file mode 100644 index 210dfd7c1..000000000 --- a/docs/zh_CN/api-reference/network/tcpip_adapter.rst +++ /dev/null @@ -1,2 +0,0 @@ -.. include:: ../../../en/api-reference/network/tcpip_adapter.rst -