From 1a012b7ad25f4957dac00241fb80a54fca746fc5 Mon Sep 17 00:00:00 2001 From: David Cermak Date: Mon, 18 Nov 2019 17:04:47 +0100 Subject: [PATCH] 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 --- docs/en/api-reference/network/esp_netif.rst | 4 +- docs/en/api-reference/network/index.rst | 8 ++ .../network/tcpip_adapter_migration.rst | 83 +++++++++++++++++++ docs/page_redirects.txt | 3 +- docs/zh_CN/api-reference/network/index.rst | 1 + .../network/tcpip_adapter_migration.rst | 1 + 6 files changed, 98 insertions(+), 2 deletions(-) create mode 100644 docs/en/api-reference/network/tcpip_adapter_migration.rst create mode 100644 docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst diff --git a/docs/en/api-reference/network/esp_netif.rst b/docs/en/api-reference/network/esp_netif.rst index eeae49b31..da44cbbd0 100644 --- a/docs/en/api-reference/network/esp_netif.rst +++ b/docs/en/api-reference/network/esp_netif.rst @@ -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 diff --git a/docs/en/api-reference/network/index.rst b/docs/en/api-reference/network/index.rst index 93adede1d..ab2bb3a73 100644 --- a/docs/en/api-reference/network/index.rst +++ b/docs/en/api-reference/network/index.rst @@ -38,8 +38,16 @@ IP Network Layer ESP-NETIF +.. toctree:: + :hidden: + + TCP/IP Adapter Migration Guide + 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  ================= diff --git a/docs/en/api-reference/network/tcpip_adapter_migration.rst b/docs/en/api-reference/network/tcpip_adapter_migration.rst new file mode 100644 index 000000000..92586dd2f --- /dev/null +++ b/docs/en/api-reference/network/tcpip_adapter_migration.rst @@ -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 ` +* :component_file:`DHCP ` +* :component_file:`DNS ` +* :component_file:`IP address ` + + +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 ` + + +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. diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index fc1cee798..a1a6239c0 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -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 \ No newline at end of file diff --git a/docs/zh_CN/api-reference/network/index.rst b/docs/zh_CN/api-reference/network/index.rst index 83bc3ce5b..55c7ef168 100644 --- a/docs/zh_CN/api-reference/network/index.rst +++ b/docs/zh_CN/api-reference/network/index.rst @@ -37,6 +37,7 @@ IP 网络层协议 :maxdepth: 1 ESP-NETIF + TCP/IP Adapter Migration Guide TCP/IP 套接字 API 的示例代码存放在 ESP-IDF 示例项目的 :example:`protocols/sockets` 目录下。 diff --git a/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst b/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst new file mode 100644 index 000000000..408056bd6 --- /dev/null +++ b/docs/zh_CN/api-reference/network/tcpip_adapter_migration.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/tcpip_adapter_migration.rst