diff --git a/docs/Doxyfile b/docs/Doxyfile index 9e1bcdc9e..d8dfc6333 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -87,6 +87,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 \ ## ## Protocols - API Reference ## diff --git a/docs/en/api-guides/mesh.rst b/docs/en/api-guides/mesh.rst index 7ad224140..5a22e027a 100644 --- a/docs/en/api-guides/mesh.rst +++ b/docs/en/api-guides/mesh.rst @@ -1,7 +1,9 @@ ESP-MESH ======== -This guide provides information regarding the ESP-MESH protocol. Please see the :doc:`MESH API Reference<../api-reference/mesh/esp_mesh>` for more information about API usage. +This guide provides information regarding the ESP-MESH protocol. Please see the +:doc:`MESH API Reference<../api-reference/network/esp_mesh>` for more information +about API usage. .. ------------------------------- Overview ----------------------------------- diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 19ae39bd4..0288fb8c4 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -103,7 +103,7 @@ The 8-bit subtype field is specific to a given partition type. esp-idf currently - nvs (2) is for the :doc:`Non-Volatile Storage (NVS) API <../api-reference/storage/nvs_flash>`. - NVS is used to store per-device PHY calibration data (different to initialisation data). - - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/wifi/esp_wifi>` initialisation function is used. + - NVS is used to store WiFi data if the :doc:`esp_wifi_set_storage(WIFI_STORAGE_FLASH) <../api-reference/network/esp_wifi>` initialisation function is used. - The NVS API can also be used for other application data. - It is strongly recommended that you include an NVS partition of at least 0x3000 bytes in your project. - If using NVS API to store a lot of data, increase the NVS partition size from the default 0x6000 bytes. diff --git a/docs/en/api-reference/ethernet/index.rst b/docs/en/api-reference/ethernet/index.rst deleted file mode 100644 index 6e95831d3..000000000 --- a/docs/en/api-reference/ethernet/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Ethernet API -************ - -.. toctree:: - :maxdepth: 1 - - Ethernet - - -Example code for this API section is provided in :example:`ethernet` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/index.rst b/docs/en/api-reference/index.rst index 0de5c5ae6..d1d9afaa8 100644 --- a/docs/en/api-reference/index.rst +++ b/docs/en/api-reference/index.rst @@ -5,10 +5,8 @@ API Reference .. toctree:: :maxdepth: 2 - Wi-Fi - Mesh Bluetooth - Ethernet + Networking Peripherals Protocols Provisioning diff --git a/docs/en/api-reference/mesh/index.rst b/docs/en/api-reference/mesh/index.rst deleted file mode 100644 index a988ad8b0..000000000 --- a/docs/en/api-reference/mesh/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Mesh API -********* - -.. toctree:: - :maxdepth: 1 - - ESP Mesh - -Example code for this API section is provided in :example:`mesh` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/ethernet/esp_eth.rst b/docs/en/api-reference/network/esp_eth.rst similarity index 99% rename from docs/en/api-reference/ethernet/esp_eth.rst rename to docs/en/api-reference/network/esp_eth.rst index 4025ed231..e18cc2b72 100644 --- a/docs/en/api-reference/ethernet/esp_eth.rst +++ b/docs/en/api-reference/network/esp_eth.rst @@ -1,4 +1,4 @@ -ETHERNET +Ethernet ======== Application Example diff --git a/docs/en/api-reference/mesh/esp_mesh.rst b/docs/en/api-reference/network/esp_mesh.rst similarity index 100% rename from docs/en/api-reference/mesh/esp_mesh.rst rename to docs/en/api-reference/network/esp_mesh.rst diff --git a/docs/en/api-reference/wifi/esp_now.rst b/docs/en/api-reference/network/esp_now.rst similarity index 100% rename from docs/en/api-reference/wifi/esp_now.rst rename to docs/en/api-reference/network/esp_now.rst diff --git a/docs/en/api-reference/wifi/esp_smartconfig.rst b/docs/en/api-reference/network/esp_smartconfig.rst similarity index 100% rename from docs/en/api-reference/wifi/esp_smartconfig.rst rename to docs/en/api-reference/network/esp_smartconfig.rst diff --git a/docs/en/api-reference/wifi/esp_wifi.rst b/docs/en/api-reference/network/esp_wifi.rst similarity index 100% rename from docs/en/api-reference/wifi/esp_wifi.rst rename to docs/en/api-reference/network/esp_wifi.rst diff --git a/docs/en/api-reference/network/index.rst b/docs/en/api-reference/network/index.rst new file mode 100644 index 000000000..0c7f5ba5a --- /dev/null +++ b/docs/en/api-reference/network/index.rst @@ -0,0 +1,42 @@ +Networking APIs +*************** + +Wi-Fi +===== + +.. toctree:: + :maxdepth: 1 + + Wi-Fi + Smart Config + ESP-NOW + ESP Mesh + +Example code for the Wi-Fi API is provided in :example:`wifi` directory of ESP-IDF examples. + +Example code for ESP Mesh is provided in :example:`mesh` directory of ESP-IDF examples. + +Ethernet +======== + +.. toctree:: + :maxdepth: 1 + + Ethernet + +Example code for the Ethernet API is provided in :example:`ethernet` directory of ESP-IDF examples. + +IP Network Layer +================ + +.. toctree:: + :maxdepth: 1 + + TCP/IP Adapter + +Example code for TCP/IP socket APIs is provided in :example:`protocols/sockets` directory of ESP-IDF examples. + +Application Layer +================= + +Documentation for application layer network protocols (above the IP network layer) is provided in :doc:`../protocols/index`. diff --git a/docs/en/api-reference/network/lwip.rst b/docs/en/api-reference/network/lwip.rst new file mode 100644 index 000000000..562bb2354 --- /dev/null +++ b/docs/en/api-reference/network/lwip.rst @@ -0,0 +1,8 @@ +lwIP TCP/IP API +*************** + +Application Example +------------------- + +Example code for TCP/IP socket APIs is provided in :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 new file mode 100644 index 000000000..940223e00 --- /dev/null +++ b/docs/en/api-reference/network/tcpip_adapter.rst @@ -0,0 +1,20 @@ +TCP/IP Adapter +============== + +The purpose of TCP/IP Adapter library is twofold. First, it provides an abstraction layer for the application on top of the IP stack, to allow applications to choose between IP stacks in the future. Second, the APIs it provides are thread safe, even if the underlying IP stack APIs are not. + +In many cases, application does not need to call TCP/IP Adapter APIs itself. A few cases when such calls are needed are related to :doc:`event handling <../../api-guides/event-handling>`. + + +The aim of this adapter is to provide an abstraction layer between the TCP/IP stack and the network interface layer (currently Wi-Fi or Ethernet), and general network interface management. + +ESP-IDF currently implements TCP/IP Adapter for the :doc:`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. + + +API Reference +------------- + +.. include:: /_build/inc/tcpip_adapter.inc +.. include:: /_build/inc/tcpip_adapter_lwip.inc diff --git a/docs/en/api-reference/protocols/index.rst b/docs/en/api-reference/protocols/index.rst index f57b4cc4e..8c3637d9b 100644 --- a/docs/en/api-reference/protocols/index.rst +++ b/docs/en/api-reference/protocols/index.rst @@ -1,5 +1,5 @@ -Protocols API -************* +Application Protocols +********************* .. toctree:: :maxdepth: 1 @@ -14,3 +14,9 @@ Protocols API Modbus slave Example code for this API section is provided in :example:`protocols` directory of ESP-IDF examples. + + +IP Network Layer +================ + +Documentation for IP Network Layer protocols (below the Application Protocol layer) is provided in :doc:`../network/index`. diff --git a/docs/en/api-reference/wifi/index.rst b/docs/en/api-reference/wifi/index.rst deleted file mode 100644 index 1553d3597..000000000 --- a/docs/en/api-reference/wifi/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -Wi-Fi API -********* - -.. toctree:: - :maxdepth: 1 - - Wi-Fi - Smart Config - ESPNOW - - -Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples. diff --git a/docs/zh_CN/api-reference/ethernet/esp_eth.rst b/docs/zh_CN/api-reference/ethernet/esp_eth.rst deleted file mode 100644 index 00cb4e891..000000000 --- a/docs/zh_CN/api-reference/ethernet/esp_eth.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/ethernet/esp_eth.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/ethernet/index.rst b/docs/zh_CN/api-reference/ethernet/index.rst deleted file mode 100644 index 949fe213e..000000000 --- a/docs/zh_CN/api-reference/ethernet/index.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/ethernet/index.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/mesh/esp_mesh.rst b/docs/zh_CN/api-reference/mesh/esp_mesh.rst deleted file mode 100644 index 658aa16a7..000000000 --- a/docs/zh_CN/api-reference/mesh/esp_mesh.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/mesh/esp_mesh.rst diff --git a/docs/zh_CN/api-reference/mesh/index.rst b/docs/zh_CN/api-reference/mesh/index.rst deleted file mode 100644 index 34515650e..000000000 --- a/docs/zh_CN/api-reference/mesh/index.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/mesh/index.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/network/esp_eth.rst b/docs/zh_CN/api-reference/network/esp_eth.rst new file mode 100644 index 000000000..89a9556e6 --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_eth.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/esp_eth.rst diff --git a/docs/zh_CN/api-reference/network/esp_mesh.rst b/docs/zh_CN/api-reference/network/esp_mesh.rst new file mode 100644 index 000000000..f4553aa87 --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_mesh.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/esp_mesh.rst diff --git a/docs/zh_CN/api-reference/network/esp_now.rst b/docs/zh_CN/api-reference/network/esp_now.rst new file mode 100644 index 000000000..0c9a268f7 --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_now.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/esp_now.rst diff --git a/docs/zh_CN/api-reference/network/esp_smartconfig.rst b/docs/zh_CN/api-reference/network/esp_smartconfig.rst new file mode 100644 index 000000000..00a8e6f66 --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_smartconfig.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/esp_smartconfig.rst diff --git a/docs/zh_CN/api-reference/network/esp_wifi.rst b/docs/zh_CN/api-reference/network/esp_wifi.rst new file mode 100644 index 000000000..860ea1be1 --- /dev/null +++ b/docs/zh_CN/api-reference/network/esp_wifi.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/esp_wifi.rst diff --git a/docs/zh_CN/api-reference/network/index.rst b/docs/zh_CN/api-reference/network/index.rst new file mode 100644 index 000000000..777339ac4 --- /dev/null +++ b/docs/zh_CN/api-reference/network/index.rst @@ -0,0 +1 @@ +.. include:: ../../../en/api-reference/network/index.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/wifi/esp_now.rst b/docs/zh_CN/api-reference/wifi/esp_now.rst deleted file mode 100644 index 6023755f6..000000000 --- a/docs/zh_CN/api-reference/wifi/esp_now.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/wifi/esp_now.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/wifi/esp_smartconfig.rst b/docs/zh_CN/api-reference/wifi/esp_smartconfig.rst deleted file mode 100644 index 251cc590a..000000000 --- a/docs/zh_CN/api-reference/wifi/esp_smartconfig.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/wifi/esp_smartconfig.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/wifi/esp_wifi.rst b/docs/zh_CN/api-reference/wifi/esp_wifi.rst deleted file mode 100644 index 7d88405f5..000000000 --- a/docs/zh_CN/api-reference/wifi/esp_wifi.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/wifi/esp_wifi.rst \ No newline at end of file diff --git a/docs/zh_CN/api-reference/wifi/index.rst b/docs/zh_CN/api-reference/wifi/index.rst deleted file mode 100644 index 5cf31c597..000000000 --- a/docs/zh_CN/api-reference/wifi/index.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../en/api-reference/wifi/index.rst \ No newline at end of file