mirror of
https://github.com/espressif/esp-idf.git
synced 2026-06-04 20:26:38 +03:00
Merge branch 'update/discontinue_tcpip_adapter' into 'master'
esp_netif: Remove tcpip_adapter compatibility layer Closes IDF-4457 See merge request espressif/esp-idf!17066
This commit is contained in:
David Čermák
@@ -65,26 +65,8 @@ LwIP & ESP-WIFI-MESH
|
||||
|
||||
The application can access the ESP-WIFI-MESH stack directly without having to go through the LwIP stack. The LwIP stack is only required by the root node to transmit/receive data to/from an external IP network. However, since every node can potentially become the root node (due to automatic root node selection), each node must still initialize the LwIP stack.
|
||||
|
||||
**Each node is required to initialize LwIP by calling** :cpp:func:`tcpip_adapter_init`. In order to prevent non-root node access to LwIP, the application should stop the following services after LwIP initialization:
|
||||
**Each node that could become root is required to initialize LwIP by calling** :cpp:func:`esp_netif_init`. In order to prevent non-root node access to LwIP, the application should not create or register any network interfaces using esp_netif APIs.
|
||||
|
||||
- DHCP server service on the softAP interface.
|
||||
- DHCP client service on the station interface.
|
||||
|
||||
The following code snippet demonstrates how to initialize LwIP for ESP-WIFI-MESH applications.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* tcpip initialization */
|
||||
tcpip_adapter_init();
|
||||
/*
|
||||
* for mesh
|
||||
* stop DHCP server on softAP interface by default
|
||||
* stop DHCP client on station interface by default
|
||||
*/
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
|
||||
|
||||
.. note::
|
||||
|
||||
ESP-WIFI-MESH requires a root node to be connected with a router. Therefore, in the event that a node becomes the root, **the corresponding handler must start the DHCP client service and immediately obtain an IP address**. Doing so will allow other nodes to begin transmitting/receiving packets to/from the external IP network. However, this step is unnecessary if static IP settings are used.
|
||||
|
||||
@@ -100,14 +82,7 @@ The prerequisites for starting ESP-WIFI-MESH is to initialize LwIP and Wi-Fi, Th
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
tcpip_adapter_init();
|
||||
/*
|
||||
* for mesh
|
||||
* stop DHCP server on softAP interface by default
|
||||
* stop DHCP client on station interface by default
|
||||
*/
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
|
||||
ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
|
||||
ESP_ERROR_CHECK(esp_netif_init());
|
||||
|
||||
/* event initialization */
|
||||
ESP_ERROR_CHECK(esp_event_loop_create_default());
|
||||
|
||||
@@ -12,8 +12,6 @@ Some ESP-NETIF API functions are intended to be called by application code, for
|
||||
|
||||
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 :doc:`/api-reference/network/tcpip_adapter_migration` section in case existing applications to be ported to use the esp-netif API instead.
|
||||
|
||||
ESP-NETIF architecture
|
||||
----------------------
|
||||
|
||||
@@ -114,8 +112,8 @@ Communication driver plays these two important roles in relation with ESP-NETIF:
|
||||
* Calls :cpp:func:`esp_netif_receive()` to pass incoming data to network stack
|
||||
|
||||
|
||||
C) ESP-NETIF, former tcpip_adapter
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
C) ESP-NETIF
|
||||
^^^^^^^^^^^^
|
||||
|
||||
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:
|
||||
|
||||
|
||||
@@ -55,13 +55,10 @@ IP Network Layer
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
tcpip_adapter_migration
|
||||
esp_netif_driver
|
||||
|
||||
Code examples for TCP/IP socket APIs are provided in the :example:`protocols/sockets` directory of ESP-IDF examples.
|
||||
|
||||
The TCP/IP Adapter (legacy network interface library) has been deprecated, please consult the :doc:`/api-reference/network/tcpip_adapter_migration` to update existing IDF applications.
|
||||
|
||||
Application Layer
|
||||
=================
|
||||
|
||||
|
||||
@@ -1,82 +0,0 @@
|
||||
TCP/IP Adapter Migration Guide
|
||||
==============================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
TCP/IP Adapter is a network interface abstraction component used in IDF prior to v4.1. This page outlines migration from tcpip_adapter API to its successor :doc:`/api-reference/network/esp_netif`.
|
||||
|
||||
|
||||
Updating network connection code
|
||||
--------------------------------
|
||||
|
||||
|
||||
Network stack initialization
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Simply replace ``tcpip_adapter_init()`` with ``esp_netif_init()``. Please note that the :doc:`/api-reference/network/esp_netif` initialization API returns standard error code and the ``esp_netif_deinit()`` for un-initialization is available.
|
||||
|
||||
Also replace ``#include "tcpip_adapter.h"`` with ``#include "esp_netif.h"``.
|
||||
|
||||
|
||||
Network interface creation
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
TCP/IP Adapter defined these three interfaces statically:
|
||||
|
||||
- WiFi Station
|
||||
- WiFi Access Point
|
||||
- Ethernet
|
||||
|
||||
Network interface instance shall be explicitly constructed for the :doc:`/api-reference/network/esp_netif` to enable its connection to the TCP/IP stack.
|
||||
For example initialization code for WiFi has to explicitly call ``esp_netif_create_default_wifi_sta();`` or ``esp_netif_create_default_wifi_ap();`` after the TCP/IP stack and the event loop have been initialized.
|
||||
Please consult an example initialization code for these three interfaces:
|
||||
|
||||
- WiFi Station: :example_file:`wifi/getting_started/station/main/station_example_main.c`
|
||||
- WiFi Access Point: :example_file:`wifi/getting_started/softAP/main/softap_example_main.c`
|
||||
- Ethernet: :example_file:`ethernet/basic/main/ethernet_example_main.c`
|
||||
|
||||
|
||||
Replacing other tcpip_adapter API
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
All the tcpip_adapter functions have their esp-netif counter-part. Please refer to the esp_netif.h grouped into these sections:
|
||||
|
||||
* :component_file:`Setters/Getters <esp_netif/include/esp_netif.h#L241>`
|
||||
* :component_file:`DHCP <esp_netif/include/esp_netif.h#L387>`
|
||||
* :component_file:`DNS <esp_netif/include/esp_netif.h#L516>`
|
||||
* :component_file:`IP address <esp_netif/include/esp_netif.h#L568>`
|
||||
|
||||
|
||||
Default event handlers
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Event handlers are moved from tcpip_adapter to appropriate driver code. There is no change from application code perspective, all events shall be handled in the same way.
|
||||
Please note that within IP related event handlers, application code usually receives IP addresses in a form of esp-netif specific struct (not the LwIP structs, but binary compatible).
|
||||
This is the preferred way of printing the address:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_LOGI(TAG, "got ip:" IPSTR "\n", IP2STR(&event->ip_info.ip));
|
||||
|
||||
Instead of
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
ESP_LOGI(TAG, "got ip:%s\n", ip4addr_ntoa(&event->ip_info.ip));
|
||||
|
||||
Since ``ip4addr_ntoa()`` is a LwIP API, the esp-netif provides ``esp_ip4addr_ntoa()`` as a replacement, but the above method is generally preferred.
|
||||
|
||||
|
||||
IP addresses
|
||||
^^^^^^^^^^^^
|
||||
|
||||
It is preferred to use esp-netif defined IP structures. Please note that the LwIP structs will still work when default compatibility enabled.
|
||||
* :component_file:`esp-netif IP address definitions <esp_netif/include/esp_netif_ip_addr.h#L96>`
|
||||
|
||||
|
||||
Next steps
|
||||
^^^^^^^^^^
|
||||
|
||||
Additional step in porting an application to fully benefit from the :doc:`/api-reference/network/esp_netif` is to disable the tcpip_adapter compatibility layer in the component configuration:
|
||||
``ESP NETIF Adapter`` -> ``Enable backward compatible tcpip_adapter interface`` and check if the project compiles.
|
||||
TCP/IP adapter brings many include dependencies and this step might help in decoupling the application from using specific TCP/IP stack API directly.
|
||||
Reference in New Issue
Block a user