From 6a4955ef74afa8293cf929fccd06692118372f51 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Mon, 3 Dec 2018 18:11:31 +1100 Subject: [PATCH] doc: Rearrange wifi & ethernet docs into a common "network" doc --- docs/Doxyfile | 2 + docs/en/api-guides/mesh.rst | 4 +- docs/en/api-guides/partition-tables.rst | 2 +- docs/en/api-reference/ethernet/index.rst | 10 ----- docs/en/api-reference/index.rst | 4 +- docs/en/api-reference/mesh/index.rst | 9 ---- .../{ethernet => network}/esp_eth.rst | 2 +- .../{mesh => network}/esp_mesh.rst | 0 .../{wifi => network}/esp_now.rst | 0 .../{wifi => network}/esp_smartconfig.rst | 0 .../{wifi => network}/esp_wifi.rst | 0 docs/en/api-reference/network/index.rst | 42 +++++++++++++++++++ docs/en/api-reference/network/lwip.rst | 8 ++++ .../api-reference/network/tcpip_adapter.rst | 20 +++++++++ docs/en/api-reference/protocols/index.rst | 10 ++++- docs/en/api-reference/wifi/index.rst | 12 ------ docs/zh_CN/api-reference/ethernet/esp_eth.rst | 1 - docs/zh_CN/api-reference/ethernet/index.rst | 1 - docs/zh_CN/api-reference/mesh/esp_mesh.rst | 1 - docs/zh_CN/api-reference/mesh/index.rst | 1 - docs/zh_CN/api-reference/network/esp_eth.rst | 1 + docs/zh_CN/api-reference/network/esp_mesh.rst | 1 + docs/zh_CN/api-reference/network/esp_now.rst | 1 + .../api-reference/network/esp_smartconfig.rst | 1 + docs/zh_CN/api-reference/network/esp_wifi.rst | 1 + docs/zh_CN/api-reference/network/index.rst | 1 + docs/zh_CN/api-reference/wifi/esp_now.rst | 1 - .../api-reference/wifi/esp_smartconfig.rst | 1 - docs/zh_CN/api-reference/wifi/esp_wifi.rst | 1 - docs/zh_CN/api-reference/wifi/index.rst | 1 - 30 files changed, 92 insertions(+), 47 deletions(-) delete mode 100644 docs/en/api-reference/ethernet/index.rst delete mode 100644 docs/en/api-reference/mesh/index.rst rename docs/en/api-reference/{ethernet => network}/esp_eth.rst (99%) rename docs/en/api-reference/{mesh => network}/esp_mesh.rst (100%) rename docs/en/api-reference/{wifi => network}/esp_now.rst (100%) rename docs/en/api-reference/{wifi => network}/esp_smartconfig.rst (100%) rename docs/en/api-reference/{wifi => network}/esp_wifi.rst (100%) create mode 100644 docs/en/api-reference/network/index.rst create mode 100644 docs/en/api-reference/network/lwip.rst create mode 100644 docs/en/api-reference/network/tcpip_adapter.rst delete mode 100644 docs/en/api-reference/wifi/index.rst delete mode 100644 docs/zh_CN/api-reference/ethernet/esp_eth.rst delete mode 100644 docs/zh_CN/api-reference/ethernet/index.rst delete mode 100644 docs/zh_CN/api-reference/mesh/esp_mesh.rst delete mode 100644 docs/zh_CN/api-reference/mesh/index.rst create mode 100644 docs/zh_CN/api-reference/network/esp_eth.rst create mode 100644 docs/zh_CN/api-reference/network/esp_mesh.rst create mode 100644 docs/zh_CN/api-reference/network/esp_now.rst create mode 100644 docs/zh_CN/api-reference/network/esp_smartconfig.rst create mode 100644 docs/zh_CN/api-reference/network/esp_wifi.rst create mode 100644 docs/zh_CN/api-reference/network/index.rst delete mode 100644 docs/zh_CN/api-reference/wifi/esp_now.rst delete mode 100644 docs/zh_CN/api-reference/wifi/esp_smartconfig.rst delete mode 100644 docs/zh_CN/api-reference/wifi/esp_wifi.rst delete mode 100644 docs/zh_CN/api-reference/wifi/index.rst diff --git a/docs/Doxyfile b/docs/Doxyfile index 9e1bcdc9ef..d8dfc6333f 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 7ad224140f..5a22e027ac 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 19ae39bd4a..0288fb8c41 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 6e95831d32..0000000000 --- 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 0de5c5ae66..d1d9afaa88 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 a988ad8b08..0000000000 --- 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 4025ed2319..e18cc2b727 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 0000000000..0c7f5ba5a0 --- /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 0000000000..562bb23541 --- /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 0000000000..940223e001 --- /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 f57b4cc4e6..8c3637d9b7 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 1553d35976..0000000000 --- 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 00cb4e891e..0000000000 --- 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 949fe213ee..0000000000 --- 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 658aa16a76..0000000000 --- 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 34515650ea..0000000000 --- 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 0000000000..89a9556e69 --- /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 0000000000..f4553aa87a --- /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 0000000000..0c9a268f79 --- /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 0000000000..00a8e6f660 --- /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 0000000000..860ea1be14 --- /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 0000000000..777339ac4f --- /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 6023755f6b..0000000000 --- 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 251cc590a1..0000000000 --- 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 7d88405f5a..0000000000 --- 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 5cf31c597f..0000000000 --- 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 -- 2.40.0