esp_netif: docs update to include tcpip_adapter migration guide
added migration guide link to the esp-netif page and network page added redirects from tcpip_adapter to new esp_netif
This commit is contained in:
David Cermak
parent
af3f821fd7
commit
1a012b7ad2
|
|
@ -12,9 +12,11 @@ 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
|
||||
======================
|
||||
----------------------
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
|
|
|
|||
|
|
@ -38,8 +38,16 @@ IP Network Layer
|
|||
|
||||
ESP-NETIF <esp_netif.rst>
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
TCP/IP Adapter Migration Guide <tcpip_adapter_migration.rst>
|
||||
|
||||
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
|
||||
=================
|
||||
|
||||
|
|
|
|||
83
docs/en/api-reference/network/tcpip_adapter_migration.rst
Normal file
83
docs/en/api-reference/network/tcpip_adapter_migration.rst
Normal file
|
|
@ -0,0 +1,83 @@
|
|||
TCP/IP Adapter Migration Guide
|
||||
==============================
|
||||
|
||||
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:`examples/wifi/getting_started/station/main/station_example_main.c`
|
||||
- WiFi Access Point: :example:`examples/wifi/getting_started/softAP/main/softap_example_main.c`
|
||||
- Ethernet :example:`examples/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.
|
||||
|
|
@ -14,7 +14,7 @@ api-reference/wifi/index api-reference/network/index
|
|||
api-reference/wifi/esp_now api-reference/network/esp_now
|
||||
api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig
|
||||
api-reference/wifi/esp_wifi api-reference/network/esp_wifi
|
||||
api-reference/system/tcpip_adapter api-reference/network/tcpip_adapter
|
||||
api-reference/system/tcpip_adapter api-reference/network/esp_netif
|
||||
get-started/idf-monitor api-guides/tools/idf-monitor
|
||||
get-started-cmake/idf-monitor api-guides/tools/idf-monitor
|
||||
get-started/get-started-devkitc hw-reference/get-started-devkitc
|
||||
|
|
@ -50,3 +50,4 @@ api-guide/build-system-cmake api-guide/build-system
|
|||
api-guide/ulp-cmake api-guide/ulp
|
||||
api-guide/unit-tests-cmake api-guide/unit-tests
|
||||
|
||||
api-reference/network/tcpip_adapter api-reference/network/esp_netif
|
||||
|
|
@ -37,6 +37,7 @@ IP 网络层协议
|
|||
:maxdepth: 1
|
||||
|
||||
ESP-NETIF <esp_netif.rst>
|
||||
TCP/IP Adapter Migration Guide <tcpip_adapter_migration.rst>
|
||||
|
||||
TCP/IP 套接字 API 的示例代码存放在 ESP-IDF 示例项目的 :example:`protocols/sockets` 目录下。
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1 @@
|
|||
.. include:: ../../../en/api-reference/network/tcpip_adapter_migration.rst
|
||||
Loading…
Reference in a new issue