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.
This commit is contained in:
Darian Leung 2018-06-26 20:48:47 +08:00
parent 1806a69abf
commit f4c3917712
26 changed files with 1636 additions and 635 deletions

File diff suppressed because it is too large Load Diff

View File

@ -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

Binary file not shown.

After

Width:  |  Height:  |  Size: 68 KiB

BIN
docs/_static/mesh-beacon-frame-rssi.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 30 KiB

View File

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

BIN
docs/_static/mesh-network-building.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 46 KiB

BIN
docs/_static/mesh-node-types.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 38 KiB

BIN
docs/_static/mesh-packet.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 48 KiB

BIN
docs/_static/mesh-root-node-failure.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 50 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 44 KiB

View File

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 29 KiB

BIN
docs/_static/mesh-tree-topology.png vendored Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 31 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 57 KiB

View File

@ -24,6 +24,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>

File diff suppressed because it is too large Load Diff

View File

@ -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
--------------

View File

@ -24,6 +24,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>