doc: Rearrange wifi & ethernet docs into a common "network" doc

2018-12-03 18:11:31 +11:00
parent 5436be94b6
commit 6a4955ef74
30 changed files with 92 additions and 47 deletions
@@ -1,10 +0,0 @@
-Ethernet API
-************
-
-.. toctree::
-   :maxdepth: 1
-
-   Ethernet <esp_eth>
-
-
-Example code for this API section is provided in :example:`ethernet` directory of ESP-IDF examples.
@@ -5,10 +5,8 @@ API Reference
 .. toctree::
   :maxdepth: 2

-   Wi-Fi <wifi/index>
-   Mesh <mesh/index>
   Bluetooth <bluetooth/index>
-   Ethernet <ethernet/index>
+   Networking <network/index>
   Peripherals <peripherals/index>
   Protocols <protocols/index>
   Provisioning <provisioning/index>
@@ -1,9 +0,0 @@
-Mesh API
-*********
-
-.. toctree::
-   :maxdepth: 1
-
-   ESP Mesh <esp_mesh>
-
-Example code for this API section is provided in :example:`mesh` directory of ESP-IDF examples.
@@ -1,4 +1,4 @@
-ETHERNET
+Ethernet
 ========

 Application Example
@@ -0,0 +1,42 @@
+Networking APIs
+***************
+
+Wi-Fi
+=====
+
+.. toctree::
+   :maxdepth: 1
+
+   Wi-Fi <esp_wifi>
+   Smart Config <esp_smartconfig>
+   ESP-NOW <esp_now>
+   ESP Mesh <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 <esp_eth>
+
+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 <tcpip_adapter.rst>
+
+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`.
@@ -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.
+
@@ -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 <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
@@ -1,5 +1,5 @@
-Protocols API
-*************
+Application Protocols
+*********************

 .. toctree::
   :maxdepth: 1
@@ -14,3 +14,9 @@ Protocols API
   Modbus slave <modbus>

 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`.
@@ -1,12 +0,0 @@
-Wi-Fi API
-*********
-
-.. toctree::
-   :maxdepth: 1
-
-   Wi-Fi <esp_wifi>
-   Smart Config <esp_smartconfig>
-   ESPNOW <esp_now>
-
-
-Example code for this API section is provided in :example:`wifi` directory of ESP-IDF examples.