docs/rewrite_mesh_docs

The following commit rewrites the ESP-MESH docs. This commit includes
new diagrams and a structure approach to the mesh docs. Some mesh api references
have also been modified.

components/esp32/include/esp_mesh_internal.h

@@ -33,22 +33,20 @@ extern "C" {
  *                Structures
  *******************************************************/
 typedef struct {
-    int scan;          /**< minimum scan times before being a root, default:10. */
-    int vote;          /**< max vote times in self-healing, default:1000. */
-    int fail;          /**< parent selection fail times. If the scan times reach this value,
-                            device will disconnect with associated children and join self-healing, default:120. */
-    int monitor_ie;    /**< acceptable times of parent networking IE change before update self networking IE, default:10. */
+    int scan;          /**< minimum scan times before being a root, default:10 */
+    int vote;          /**< max vote times in self-healing, default:1000 */
+    int fail;          /**< parent selection fail times, if the scan times reach this value,
+                            device will disconnect with associated children and join self-healing. default:60 */
+    int monitor_ie;    /**< acceptable times of parent networking IE change before update its own networking IE. default:3 */
 } mesh_attempts_t;
 
 typedef struct {
-    int duration_ms;   /* parent weak RSSI monitor duration. If the RSSI with current parent is less than cnx_rssi continuously
-                          within this duration_ms, device will search for a better parent. */
+    int duration_ms;   /* parent weak RSSI monitor duration, if the RSSI continues to be weak during this duration_ms,
+                          device will search for a new parent. */
     int cnx_rssi;      /* RSSI threshold for keeping a good connection with parent.
-                          If set a value greater than -120 dBm, device will arm a timer to monitor current RSSI at a period time of
-                          duration_ms. */
-    int select_rssi;   /* RSSI threshold for parent selection, should be a value greater than switch_rssi. */
-    int switch_rssi;   /* RSSI threshold for parent switch. Device will disassociate current parent and switch to a new parent when
-                          the RSSI with the new parent is greater than this set threshold. */
+                          If set a value greater than -120 dBm, a timer will be armed to monitor parent RSSI at a period time of duration_ms. */
+    int select_rssi;   /* RSSI threshold for parent selection. It should be a value greater than switch_rssi. */
+    int switch_rssi;   /* Disassociate with current parent and switch to a new parent when the RSSI is greater than this set threshold. */
     int backoff_rssi;  /* RSSI threshold for connecting to the root */
 } mesh_switch_parent_t;
 
@@ -59,7 +57,7 @@ typedef struct {
 } mesh_rssi_threshold_t;
 
 /**
- * @brief mesh networking IE
+ * @brief Mesh networking IE
  */
 typedef struct {
     /**< mesh networking IE head */
@@ -82,7 +80,7 @@ typedef struct {
     uint16_t root_cap;       /**< root capacity */
     uint16_t self_cap;       /**< self capacity */
     uint16_t layer2_cap;     /**< layer2 capacity */
-    uint16_t scan_ap_num;    /**< the number of scanned APs */
+    uint16_t scan_ap_num;    /**< the number of scanning APs */
     int8_t rssi;             /**< RSSI of the parent */
     int8_t router_rssi;      /**< RSSI of the router */
     uint8_t flag;            /**< flag of networking */
@@ -102,9 +100,9 @@ typedef struct {
  *                Function Definitions
  *******************************************************/
 /**
- * @brief     set mesh softAP beacon interval
+ * @brief      Set mesh softAP beacon interval
  *
- * @param     interval  beacon interval(ms) (100ms ~ 60000ms)
+ * @param[in]  interval  beacon interval (msecs) (100 msecs ~ 60000 msecs)
  *
  * @return
  *    - ESP_OK
@@ -114,9 +112,9 @@ typedef struct {
 esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
 
 /**
- * @brief     get mesh softAP beacon interval
+ * @brief      Get mesh softAP beacon interval
  *
- * @param     interval  beacon interval(ms)
+ * @param[out] interval  beacon interval (msecs)
  *
  * @return
  *    - ESP_OK
@@ -124,9 +122,9 @@ esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
 esp_err_t esp_mesh_get_beacon_interval(int *interval_ms);
 
 /**
- * @brief     set attempts for mesh self-organized networking
+ * @brief     Set attempts for mesh self-organized networking
  *
- * @param     attempts
+ * @param[in] attempts
  *
  * @return
  *    - ESP_OK
@@ -135,9 +133,9 @@ esp_err_t esp_mesh_get_beacon_interval(int *interval_ms);
 esp_err_t esp_mesh_set_attempts(mesh_attempts_t *attempts);
 
 /**
- * @brief    get attempts for mesh self-organized networking
+ * @brief      Get attempts for mesh self-organized networking
  *
- * @param    attempts
+ * @param[out] attempts
  *
  * @return
  *    - ESP_OK
@@ -146,9 +144,9 @@ esp_err_t esp_mesh_set_attempts(mesh_attempts_t *attempts);
 esp_err_t esp_mesh_get_attempts(mesh_attempts_t *attempts);
 
 /**
- * @brief     set parameters for parent switch
+ * @brief      Set parameters for parent switch
  *
- * @param     paras  parameters for parent switch
+ * @param[in]  paras  parameters for parent switch
  *
  * @return
  *    - ESP_OK
@@ -157,9 +155,9 @@ esp_err_t esp_mesh_get_attempts(mesh_attempts_t *attempts);
 esp_err_t esp_mesh_set_switch_parent_paras(mesh_switch_parent_t *paras);
 
 /**
- * @brief     get parameters for parent switch
+ * @brief      Get parameters for parent switch
  *
- * @param     paras  parameters for parent switch
+ * @param[out] paras  parameters for parent switch
  *
  * @return
  *    - ESP_OK
@@ -168,12 +166,12 @@ esp_err_t esp_mesh_set_switch_parent_paras(mesh_switch_parent_t *paras);
 esp_err_t esp_mesh_get_switch_parent_paras(mesh_switch_parent_t *paras);
 
 /**
- * @brief     set RSSI threshold
- *            The default high RSSI threshold value is -78 dBm.
- *            The default medium RSSI threshold value is -82 dBm.
- *            The default low RSSI threshold value is -85 dBm.
+ * @brief      Set RSSI threshold
+ *             - The default high RSSI threshold value is -78 dBm.
+ *             - The default medium RSSI threshold value is -82 dBm.
+ *             - The default low RSSI threshold value is -85 dBm.
  *
- * @param     threshold  RSSI threshold
+ * @param[in]  threshold  RSSI threshold
  *
  * @return
  *    - ESP_OK
@@ -182,8 +180,9 @@ esp_err_t esp_mesh_get_switch_parent_paras(mesh_switch_parent_t *paras);
 esp_err_t esp_mesh_set_rssi_threshold(const mesh_rssi_threshold_t *threshold);
 
 /**
- * @brief     get RSSI threshold
- * @param     threshold  RSSI threshold
+ * @brief      Get RSSI threshold
+ *
+ * @param[out] threshold  RSSI threshold
  *
  * @return
  *    - ESP_OK
@@ -192,11 +191,11 @@ esp_err_t esp_mesh_set_rssi_threshold(const mesh_rssi_threshold_t *threshold);
 esp_err_t esp_mesh_get_rssi_threshold(mesh_rssi_threshold_t *threshold);
 
 /**
- * @brief     enable the minimum rate to 6Mbps
+ * @brief      Enable the minimum rate to 6 Mbps
  *
- * @attention This API shall be called before WiFi start.
+ * @attention  This API shall be called before Wi-Fi is started.
  *
- * @param     is_6m  enable or not
+ * @param[in]  is_6m  enable or not
  *
  * @return
  *    - ESP_OK
@@ -204,7 +203,7 @@ esp_err_t esp_mesh_get_rssi_threshold(mesh_rssi_threshold_t *threshold);
 esp_err_t esp_mesh_set_6m_rate(bool is_6m);
 
 /**
- * @brief     print the number of txQ waiting
+ * @brief      Print the number of txQ waiting
  *
  * @return
  *    - ESP_OK
@@ -213,7 +212,7 @@ esp_err_t esp_mesh_set_6m_rate(bool is_6m);
 esp_err_t esp_mesh_print_txQ_waiting(void);
 
 /**
- * @brief     print the number of rxQ waiting
+ * @brief      Print the number of rxQ waiting
  *
  * @return
  *    - ESP_OK
@@ -222,9 +221,9 @@ esp_err_t esp_mesh_print_txQ_waiting(void);
 esp_err_t esp_mesh_print_rxQ_waiting(void);
 
 /**
- * @brief     set passive scan time
+ * @brief      Set passive scan time
  *
- * @param     interval_ms  passive scan time(ms)
+ * @param[in]  interval_ms  passive scan time (msecs)
  *
  * @return
  *    - ESP_OK
@@ -234,19 +233,19 @@ esp_err_t esp_mesh_print_rxQ_waiting(void);
 esp_err_t esp_mesh_set_passive_scan_time(int time_ms);
 
 /**
- * @brief     get passive scan time
+ * @brief      Get passive scan time
  *
- * @return    interval_ms  passive scan time(ms)
+ * @return     interval_ms  passive scan time (msecs)
  */
 int esp_mesh_get_passive_scan_time(void);
 
 /**
- * @brief     set announce interval
- *            The default short interval is 500 milliseconds.
- *            The default long interval is 3000 milliseconds.
+ * @brief      Set announce interval
+ *             - The default short interval is 500 milliseconds.
+ *             - The default long interval is 3000 milliseconds.
  *
- * @param     short_ms  shall be greater than the default value
- * @param     long_ms  shall be greater than the default value
+ * @param[in]  short_ms  shall be greater than the default value
+ * @param[in]  long_ms  shall be greater than the default value
  *
  * @return
  *    - ESP_OK
@@ -254,10 +253,10 @@ int esp_mesh_get_passive_scan_time(void);
 esp_err_t esp_mesh_set_announce_interval(int short_ms, int long_ms);
 
 /**
- * @brief     get announce interval
+ * @brief      Get announce interval
  *
- * @param     short_ms  short interval
- * @param     long_ms  long interval
+ * @param[out] short_ms  short interval
+ * @param[out] long_ms  long interval
  *
  * @return
  *    - ESP_OK

docs/en/api-guides/index.rst

@@ -25,6 +25,6 @@ API Guides
    Console Component <console>
    ROM debug console <romconsole>
    WiFi Driver <wifi>
-   Mesh Stack <mesh>
+   ESP-MESH <mesh>
    BluFi <blufi>
    External SPI-connected RAM <external-ram>

docs/en/api-reference/mesh/esp_mesh.rst

@@ -1,11 +1,266 @@
-Mesh
-=====
+ESP-MESH Programming Guide
+==========================
+
+This is a programming guide for ESP-MESH, including the API reference and coding 
+examples. This guide is split into the following parts:
+
+1. :ref:`mesh-programming-model`
+
+2. :ref:`mesh-writing-mesh-application`
+
+3. :ref:`mesh-application-examples`
+
+4. :ref:`mesh-api-reference`
+
+For documentation regarding the ESP-MESH protocol, please see the 
+:doc:`ESP-MESH API Guide<../../api-guides/mesh>`.
+
+
+.. ---------------------- ESP-MESH Programming Model --------------------------
+
+.. _mesh-programming-model:
+
+ESP-MESH Programming Model
+--------------------------
+
+Software Stack
+^^^^^^^^^^^^^^
+
+The ESP-MESH software stack is built atop the Wi-Fi Driver/FreeRTOS and may use 
+the LwIP Stack in some instances (i.e. the root node). The following diagram 
+illustrates the ESP-MESH software stack.
+
+.. _mesh-going-to-software-stack:
+
+.. figure:: ../../../_static/mesh-software-stack.png
+    :align: center
+    :alt: ESP-MESH Software Stack
+    :figclass: align-center
+
+    ESP-MESH Software Stack
+
+System Events
+^^^^^^^^^^^^^
+
+An application interfaces with ESP-MESH via **ESP-MESH Events**. Since ESP-MESH 
+is built atop the Wi-Fi stack, it is also possible for the application to interface 
+with the Wi-Fi driver via the **Wi-Fi Event Task**. The following diagram illustrates 
+the interfaces for the various System Events in an ESP-MESH application.
+
+.. figure:: ../../../_static/mesh-events-delivery.png
+    :align: center
+    :alt: ESP-MESH System Events Delivery
+    :figclass: align-center
+
+    ESP-MESH System Events Delivery
+
+The :cpp:type:`mesh_event_id_t` defines all possible ESP-MESH system events and
+can indicate events such as the connection/disconnection of parent/child. Before 
+ESP-MESH system events can be used, the application must register a **Mesh Event 
+Callback** via :cpp:func:`esp_mesh_set_config`. The callback is used to receive 
+events from the ESP-MESH stack as well as the LwIP Stack and should contain handlers 
+for each event relevant to the application.
+
+Typical use cases of system events include using events such as 
+:cpp:enumerator:`MESH_EVENT_PARENT_CONNECTED` and :cpp:enumerator:`MESH_EVENT_CHILD_CONNECTED` 
+to indicate when a node can begin transmitting data upstream and downstream respectively. Likewise, 
+:cpp:enumerator:`MESH_EVENT_ROOT_GOT_IP` and :cpp:enumerator:`MESH_EVENT_ROOT_LOST_IP` can be 
+used to indicate when the root node can and cannot transmit data to the external IP 
+network.
+
+.. warning::
+    When using ESP-MESH under self-organized mode, users must ensure that no calls 
+    to Wi-Fi API are made. This is due to the fact that the self-organizing mode 
+    will internally make Wi-Fi API calls to connect/disconnect/scan etc. 
+    **Any Wi-Fi calls from the application (including calls from callbacks and 
+    handlers of Wi-Fi events) may interfere with ESP-MESH's self-organizing behavior**. 
+    Therefore, user's should not call Wi-Fi APIs after :cpp:func:`esp_mesh_start` 
+    is called, and before :cpp:func:`esp_mesh_stop` is called.
+
+LwIP & ESP-MESH
+^^^^^^^^^^^^^^^
+
+The application can access the ESP-MESH stack directly without having to go through 
+the LwIP stack. The LwIP stack is only required by the root node to transmit/receive 
+data to/from an external IP network. However, since every node can potentially 
+become the root node (due to automatic root node selection), each node must still 
+initialize the LwIP stack.
+
+**Each node is required to initialize LwIP by calling** :cpp:func:`tcpip_adapter_init`. 
+In order to prevent non-root node access to LwIP, the application should stop the 
+following services after LwIP initialization:
+
+    - DHCP server service on the softAP interface.
+    - DHCP client service on the station interface.
+
+The following code snippet demonstrates how to initialize LwIP for ESP-MESH applications.
+
+.. code-block:: c
+
+    /*  tcpip initialization */
+    tcpip_adapter_init();
+    /*
+     * for mesh
+     * stop DHCP server on softAP interface by default
+     * stop DHCP client on station interface by default
+     */
+    ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
+    ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
+    /* do not specify system event callback, use NULL instead. */
+    ESP_ERROR_CHECK(esp_event_loop_init(NULL, NULL));
+
+.. note::
+
+    ESP-MESH requires a root node to be connected with a router. Therefore, in 
+    the event that a node becomes the root, **the corresponding handler must start 
+    the DHCP client service and immediately obtain an IP address**. Doing so will 
+    allow other nodes to begin transmitting/receiving packets to/from the external 
+    IP network. However, this step is unnecessary if static IP settings are used.
+
+
+.. ---------------------- Writing a Mesh Application --------------------------
+
+.. _mesh-writing-mesh-application:
+
+Writing an ESP-MESH Application 
+-------------------------------
+
+The prerequisites for starting ESP-MESH is to initialize LwIP and Wi-Fi, The 
+following code snippet demonstrates the necessary prerequisite steps before 
+ESP-MESH itself can be initialized.
+
+.. code-block:: c
+
+    tcpip_adapter_init();
+    /*
+     * for mesh
+     * stop DHCP server on softAP interface by default
+     * stop DHCP client on station interface by default
+     */
+    ESP_ERROR_CHECK(tcpip_adapter_dhcps_stop(TCPIP_ADAPTER_IF_AP));
+    ESP_ERROR_CHECK(tcpip_adapter_dhcpc_stop(TCPIP_ADAPTER_IF_STA));
+    /* do not specify system event callback, use NULL instead. */
+    ESP_ERROR_CHECK(esp_event_loop_init(NULL, NULL));
+
+    /*  Wi-Fi initialization */
+    wifi_init_config_t config = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK(esp_wifi_init(&config));
+    ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_FLASH));
+    ESP_ERROR_CHECK(esp_wifi_start());
+
+After initializing LwIP and Wi-Fi, the process of getting an ESP-MESH network 
+up and running can be summarized into the following three steps:
+
+1. :ref:`mesh-initialize-mesh`
+2. :ref:`mesh-configuring-mesh`
+3. :ref:`mesh-start-mesh`
+
+.. _mesh-initialize-mesh:
+
+Initialize Mesh
+^^^^^^^^^^^^^^^
+
+The following code snippet demonstrates how to initialize ESP-MESH
+
+.. code-block:: c
+
+    /*  mesh initialization */
+    ESP_ERROR_CHECK(esp_mesh_init());
+
+.. _mesh-configuring-mesh:
+
+Configuring an ESP-MESH Network
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. todo - Add note about unified configuration
+
+ESP-MESH is configured via :cpp:func:`esp_mesh_set_config` which receives its arguments
+using the :cpp:type:`mesh_cfg_t` structure. The structure contains the following
+parameters used to configure ESP-MESH:
+
++------------------+-------------------------------------+
+| Parameter        | Description                         |
++==================+=====================================+
+| Channel          | Range from 1 to 14                  |
++------------------+-------------------------------------+
+| Event Callback   | Callback for Mesh Events,           |
+|                  | see :cpp:type:`mesh_event_cb_t`     |
++------------------+-------------------------------------+
+| Mesh ID          | ID of ESP-MESH Network,             |
+|                  | see :cpp:type:`mesh_addr_t`         |
++------------------+-------------------------------------+
+| Router           | Router Configuration,               |
+|                  | see :cpp:type:`mesh_router_t`       |
++------------------+-------------------------------------+
+| Mesh AP          | Mesh AP Configuration,              |
+|                  | see :cpp:type:`mesh_ap_cfg_t`       |
++------------------+-------------------------------------+
+| Crypto Functions | Crypto Functions for Mesh IE,       |
+|                  | see :cpp:type:`mesh_crypto_funcs_t` |
++------------------+-------------------------------------+
+
+The following code snippet demonstrates how to configure ESP-MESH.
+
+.. code-block:: c
+
+    /* Enable the Mesh IE encryption by default */
+    mesh_cfg_t cfg = MESH_INIT_CONFIG_DEFAULT();
+    /* mesh ID */
+    memcpy((uint8_t *) &cfg.mesh_id, MESH_ID, 6);
+    /* mesh event callback */
+    cfg.event_cb = &mesh_event_handler;
+    /* channel (must match the router's channel) */
+    cfg.channel = CONFIG_MESH_CHANNEL;
+    /* router */
+    cfg.router.ssid_len = strlen(CONFIG_MESH_ROUTER_SSID);
+    memcpy((uint8_t *) &cfg.router.ssid, CONFIG_MESH_ROUTER_SSID, cfg.router.ssid_len);
+    memcpy((uint8_t *) &cfg.router.password, CONFIG_MESH_ROUTER_PASSWD,
+           strlen(CONFIG_MESH_ROUTER_PASSWD));
+    /* mesh softAP */
+    cfg.mesh_ap.max_connection = CONFIG_MESH_AP_CONNECTIONS;
+    memcpy((uint8_t *) &cfg.mesh_ap.password, CONFIG_MESH_AP_PASSWD,
+           strlen(CONFIG_MESH_AP_PASSWD));
+    ESP_ERROR_CHECK(esp_mesh_set_config(&cfg));
+
+.. _mesh-start-mesh:
+
+Start Mesh
+^^^^^^^^^^
+
+The following code snippet demonstrates how to start ESP-MESH.
+
+.. code-block:: c
+
+    /* mesh start */
+    ESP_ERROR_CHECK(esp_mesh_start());
+
+After starting ESP-MESH, the application should check for ESP-MESH events to determine 
+when it has connected to the network. After connecting, the application can start 
+transmitting and receiving packets over the ESP-MESH network using 
+:cpp:func:`esp_mesh_send` and :cpp:func:`esp_mesh_recv`.
+
+.. --------------------- ESP-MESH Application Examples ------------------------
+
+.. _mesh-application-examples:
 
 Application Examples
 --------------------
 
-See :example:`mesh` directory of ESP-IDF examples that contains the following applications.
+ESP-IDF contains these ESP-MESH example projects:
 
+:example:`The Internal Communication Example<mesh/internal_communication>` demonstrates
+how to setup a ESP-MESH network and have the root node send a data packet to 
+every node within the network.
+
+:example:`The Manual Networking Example<mesh/manual_networking>` demonstrates
+how to use ESP-MESH without the self-organizing features. This example shows how
+to program a node to manually scan for a list of potential parent nodes and select 
+a parent node based on custom criteria.
+
+
+.. ------------------------- ESP-MESH API Reference ---------------------------
+
+.. _mesh-api-reference:
 
 API Reference
 --------------

docs/zh_CN/api-guides/index.rst

@@ -25,6 +25,6 @@ API Guides
    Console Component <console>
    ROM debug console <romconsole>
    WiFi Driver <wifi>
-   Mesh Stack <mesh>
+   ESP-MESH <mesh>
    BluFi <blufi>
    External SPI-connected RAM <external-ram>