alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Merge branch 'docs/rename_ESP-MESH_to_ESP-WIFI-MESH' into 'master'

Browse Source 
docs: rename ESP-MESH to ESP-WIFI-MESH

Closes DOC-7

See merge request espressif/esp-idf!14252
This commit is contained in:
Dai Zi Yan 2021-07-13 02:23:43 +00:00
commit a68fd59b02
13 changed files with 365 additions and 361 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
docs/_static/mesh-esp-mesh-network-architecture.png → docs/_static/mesh-esp-wifi-mesh-network-architecture.png vendored
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 30 KiB

After

Width:  |  Height:  |  Size: 30 KiB

2
docs/en/api-guides/esp-ble-mesh/ble-mesh-index.rst
View File

@ -18,7 +18,7 @@ ESP-BLE-MESH is implemented and certified based on the latest Mesh Profile v1.0.
.. note::
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-MESH. For more information and documentation see :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`.
If you are looking for Wi-Fi based implementation of mesh for {IDF_TARGET_NAME}, please check another product by Espressif called ESP-WIF-MESH. For more information and documentation see :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`.
.. _getting-started-with-ble-mesh:

266
docs/en/api-guides/mesh.rst → docs/en/api-guides/esp-wifi-mesh.rst
View File

@ -1,20 +1,18 @@
ESP-MESH
========
ESP-WIFI-MESH
================
:link_to_translation:`zh_CN:[中文]`
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.
This guide provides information regarding the ESP-WIFI-MESH protocol. Please see the :doc:`ESP-WIFI-MESH API Reference<../api-reference/network/esp-wifi-mesh>` for more information about API usage.
.. ------------------------------- Overview -----------------------------------
Overview
--------
ESP-MESH is a networking protocol built atop the Wi-Fi protocol. ESP-MESH allows numerous devices (henceforth referred to as nodes) spread over a large physical area (both indoors and outdoors) to be interconnected under a single WLAN (Wireless Local-Area Network). ESP-MESH is self-organizing and self-healing meaning the network can be built and maintained autonomously.
ESP-WIFI-MESH is a networking protocol built atop the Wi-Fi protocol. ESP-WIFI-MESH allows numerous devices (henceforth referred to as nodes) spread over a large physical area (both indoors and outdoors) to be interconnected under a single WLAN (Wireless Local-Area Network). ESP-WIFI-MESH is self-organizing and self-healing meaning the network can be built and maintained autonomously.
The ESP-MESH guide is split into the following sections:
The ESP-WIFI-MESH guide is split into the following sections:
1. :ref:`mesh-introduction`
@ -49,99 +47,87 @@ Introduction
A traditional infrastructure Wi-Fi network is a point-to-multipoint network where a single central node known as the access point (AP) is directly connected to all other nodes known as stations. The AP is responsible for arbitrating and forwarding transmissions between the stations. Some APs also relay transmissions to/from an external IP network via a router. Traditional infrastructure Wi-Fi networks suffer the disadvantage of limited coverage area due to the requirement that every station must be in range to directly connect with the AP. Furthermore, traditional Wi-Fi networks are susceptible to overloading as the maximum number of stations permitted in the network is limited by the capacity of the AP.
.. figure:: ../../_static/mesh-esp-mesh-network-architecture.png
.. figure:: ../../_static/mesh-esp-wifi-mesh-network-architecture.png
:align: center
:alt: Diagram of ESP-MESH Network Architecture
:alt: Diagram of ESP-WIFI-MESH Network Architecture
:figclass: align-center
ESP-MESH Network Architecture
ESP-WIFI-MESH Network Architecture
ESP-MESH differs from traditional infrastructure Wi-Fi networks in that nodes are not required to connect to a central node. Instead, nodes are permitted to connect with neighboring nodes. Nodes are mutually responsible for relaying each others transmissions. This allows an ESP-MESH network to have much greater coverage area as nodes can still achieve interconnectivity without needing to be in range of the central node. Likewise, ESP-MESH is also less susceptible to overloading as the number of nodes permitted on the network is no longer limited by a single central node.
ESP-WIFI-MESH differs from traditional infrastructure Wi-Fi networks in that nodes are not required to connect to a central node. Instead, nodes are permitted to connect with neighboring nodes. Nodes are mutually responsible for relaying each others transmissions. This allows an ESP-WIFI-MESH network to have much greater coverage area as nodes can still achieve interconnectivity without needing to be in range of the central node. Likewise, ESP-WIFI-MESH is also less susceptible to overloading as the number of nodes permitted on the network is no longer limited by a single central node.
.. -------------------------- ESP-MESH Concepts -------------------------------
.. -------------------------- ESP-WIFI-MESH Concepts -------------------------------
.. _mesh-concepts:
ESP-MESH Concepts
-----------------
ESP-WIFI-MESH Concepts
---------------------------
Terminology
^^^^^^^^^^^
+--------------------------+----------------------------------------------------------------+
| Term | Description |
+==========================+================================================================+
| Node | Any device that **is** or **can be** part of an ESP-MESH |
| | network |
+--------------------------+----------------------------------------------------------------+
| Root Node | The top node in the network |
+--------------------------+----------------------------------------------------------------+
| Child Node | A node X is a child node when it is connected to another node |
| | Y where the connection makes node X more distant from the root |
| | node than node Y (in terms of number of connections). |
+--------------------------+----------------------------------------------------------------+
| Parent Node | The converse notion of a child node |
+--------------------------+----------------------------------------------------------------+
| Descendant Node | Any node reachable by repeated proceeding from parent to child |
+--------------------------+----------------------------------------------------------------+
| Sibling Nodes | Nodes that share the same parent node |
+--------------------------+----------------------------------------------------------------+
| Connection | A traditional Wi-Fi association between an AP and a station. |
| | A node in ESP-MESH will use its station interface to associate |
| | with the softAP interface of another node, thus forming a |
| | connection. The connection process includes the authentication |
| | and association processes in Wi-Fi. |
+--------------------------+----------------------------------------------------------------+
| Upstream Connection | The connection from a node to its parent node |
+--------------------------+----------------------------------------------------------------+
| Downstream Connection | The connection from a node to one of its child nodes |
+--------------------------+----------------------------------------------------------------+
| Wireless Hop | The portion of the path between source and destination nodes |
| | that corresponds to a single wireless connection. A data |
| | packet that traverses a single connection is known as |
| | **single-hop** whereas traversing multiple connections is |
| | known as **multi-hop**. |
+--------------------------+----------------------------------------------------------------+
| Subnetwork | A subnetwork is subdivision of an ESP-MESH network which |
| | consists of a node and all of its descendant nodes. Therefore |
| | the subnetwork of the root node consists of all nodes in an |
| | ESP-MESH network. |
+--------------------------+----------------------------------------------------------------+
| MAC Address | Media Access Control Address used to uniquely identify each |
| | node or router within an ESP-MESH network. |
+--------------------------+----------------------------------------------------------------+
| DS | Distribution System (External IP Network) |
+--------------------------+----------------------------------------------------------------+
.. list-table::
:header-rows: 1
:widths: 25 75
* - Term
- Description
* - Node
- Any device that **is** or **can be** part of an ESP-WIFI-MESH network
* - Root Node
- The top node in the network
* - Child Node
- A node X is a child node when it is connected to another node Y where the connection makes node X more distant from the root node than node Y (in terms of number of connections).
* - Parent Node
- The converse notion of a child node
* - Descendant Node
- Any node reachable by repeated proceeding from parent to child
* - Sibling Nodes
- Nodes that share the same parent node
* - Connection
- A traditional Wi-Fi association between an AP and a station. A node in ESP-WIFI-MESH will use its station interface to associate with the softAP interface of another node, thus forming a connection. The connection process includes the authentication and association processes in Wi-Fi.
* - Upstream Connection
- The connection from a node to its parent node
* - Downstream Connection
- The connection from a node to one of its child nodes
* - Wireless Hop
- The portion of the path between source and destination nodes that corresponds to a single wireless connection. A data packet that traverses a single connection is known as **single-hop** whereas traversing multiple connections is known as **multi-hop**.
* - Subnetwork
- A subnetwork is subdivision of an ESP-WIFI-MESH network which consists of a node and all of its descendant nodes. Therefore the subnetwork of the root node consists of all nodes in an ESP-WIFI-MESH network.
* - MAC Address
- Media Access Control Address used to uniquely identify each node or router within an ESP-WIFI-MESH network.
* - DS
- Distribution System (External IP Network)
Tree Topology
^^^^^^^^^^^^^
ESP-MESH is built atop the infrastructure Wi-Fi protocol and can be thought of as a networking protocol that combines many individual Wi-Fi networks into a single WLAN. In Wi-Fi, stations are limited to a single connection with an AP (upstream connection) at any time, whilst an AP can be simultaneously connected to multiple stations (downstream connections). However ESP-MESH allows nodes to simultaneously act as a station and an AP. Therefore a node in ESP-MESH can have **multiple downstream connections using its softAP interface**, whilst simultaneously having **a single upstream connection using its station interface**. This naturally results in a tree network topology with a parent-child hierarchy consisting of multiple layers.
ESP-WIFI-MESH is built atop the infrastructure Wi-Fi protocol and can be thought of as a networking protocol that combines many individual Wi-Fi networks into a single WLAN. In Wi-Fi, stations are limited to a single connection with an AP (upstream connection) at any time, whilst an AP can be simultaneously connected to multiple stations (downstream connections). However ESP-WIFI-MESH allows nodes to simultaneously act as a station and an AP. Therefore a node in ESP-WIFI-MESH can have **multiple downstream connections using its softAP interface**, whilst simultaneously having **a single upstream connection using its station interface**. This naturally results in a tree network topology with a parent-child hierarchy consisting of multiple layers.
.. figure:: ../../_static/mesh-tree-topology.png
:align: center
:alt: Diagram of ESP-MESH Tree Topology
:alt: Diagram of ESP-WIFI-MESH Tree Topology
:figclass: align-center
ESP-MESH Tree Topology
ESP-WIFI-MESH Tree Topology
ESP-MESH is a multiple hop (multi-hop) network meaning nodes can transmit packets to other nodes in the network through one or more wireless hops. Therefore, nodes in ESP-MESH not only transmit their own packets, but simultaneously serve as relays for other nodes. Provided that a path exists between any two nodes on the physical layer (via one or more wireless hops), any pair of nodes within an ESP-MESH network can communicate.
ESP-WIFI-MESH is a multiple hop (multi-hop) network meaning nodes can transmit packets to other nodes in the network through one or more wireless hops. Therefore, nodes in ESP-WIFI-MESH not only transmit their own packets, but simultaneously serve as relays for other nodes. Provided that a path exists between any two nodes on the physical layer (via one or more wireless hops), any pair of nodes within an ESP-WIFI-MESH network can communicate.
.. note::
The size (total number of nodes) in an ESP-MESH network is dependent on the maximum number of layers permitted in the network, and the maximum number of downstream connections each node can have. Both of these variables can be configured to limit the size of the network.
The size (total number of nodes) in an ESP-WIFI-MESH network is dependent on the maximum number of layers permitted in the network, and the maximum number of downstream connections each node can have. Both of these variables can be configured to limit the size of the network.
Node Types
^^^^^^^^^^
.. figure:: ../../_static/mesh-node-types.png
:align: center
:alt: Diagram of ESP-MESH Node Types
:alt: Diagram of ESP-WIFI-MESH Node Types
:figclass: align-center
ESP-MESH Node Types
ESP-WIFI-MESH Node Types
**Root Node:** The root node is the top node in the network and serves as the only interface between the ESP-MESH network and an external IP network. The root node is connected to a conventional Wi-Fi router and relays packets to/from the external IP network to nodes within the ESP-MESH network. **There can only be one root node within an ESP-MESH network** and the root node's upstream connection may only be with the router. Referring to the diagram above, node A is the root node of the network.
**Root Node:** The root node is the top node in the network and serves as the only interface between the ESP-WIFI-MESH network and an external IP network. The root node is connected to a conventional Wi-Fi router and relays packets to/from the external IP network to nodes within the ESP-WIFI-MESH network. **There can only be one root node within an ESP-WIFI-MESH network** and the root node's upstream connection may only be with the router. Referring to the diagram above, node A is the root node of the network.
**Leaf Nodes:** A leaf node is a node that is not permitted to have any child nodes (no downstream connections). Therefore a leaf node can only transmit or receive its own packets, but cannot forward the packets of other nodes. If a node is situated on the network's maximum permitted layer, it will be assigned as a leaf node. This prevents the node from forming any downstream connections thus ensuring the network does not add an extra layer. Some nodes without a softAP interface (station only) will also be assigned as leaf nodes due to the requirement of a softAP interface for any downstream connections. Referring to the diagram above, nodes L/M/N are situated on the networks maximum permitted layer hence have been assigned as leaf nodes .
@ -152,7 +138,7 @@ Node Types
Beacon Frames & RSSI Thresholding
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Every node in ESP-MESH that is able to form downstream connections (i.e. has a softAP interface) will periodically transmit Wi-Fi beacon frames. A node uses beacon frames to allow other nodes to detect its presence and know of its status. Idle nodes will listen for beacon frames to generate a list of potential parent nodes, one of which the idle node will form an upstream connection with. ESP-MESH uses the Vendor Information Element to store metadata such as:
Every node in ESP-WIFI-MESH that is able to form downstream connections (i.e. has a softAP interface) will periodically transmit Wi-Fi beacon frames. A node uses beacon frames to allow other nodes to detect its presence and know of its status. Idle nodes will listen for beacon frames to generate a list of potential parent nodes, one of which the idle node will form an upstream connection with. ESP-WIFI-MESH uses the Vendor Information Element to store metadata such as:
- Node Type (Root, Intermediate Parent, Leaf, Idle)
- Current layer of Node
@ -160,7 +146,7 @@ Every node in ESP-MESH that is able to form downstream connections (i.e. has a s
- Current number of child nodes
- Maximum number of downstream connections to accept
The signal strength of a potential upstream connection is represented by RSSI (Received Signal Strength Indication) of the beacon frames of the potential parent node. To prevent nodes from forming a weak upstream connection, ESP-MESH implements an RSSI threshold mechanism for beacon frames. If a node detects a beacon frame with an RSSI below a preconfigured threshold, the transmitting node will be disregarded when forming an upstream connection.
The signal strength of a potential upstream connection is represented by RSSI (Received Signal Strength Indication) of the beacon frames of the potential parent node. To prevent nodes from forming a weak upstream connection, ESP-WIFI-MESH implements an RSSI threshold mechanism for beacon frames. If a node detects a beacon frame with an RSSI below a preconfigured threshold, the transmitting node will be disregarded when forming an upstream connection.
.. figure:: ../../_static/mesh-beacon-frame-rssi.png
:align: center
@ -174,7 +160,7 @@ The signal strength of a potential upstream connection is represented by RSSI (R
**Panel B** of the illustration above demonstrates how an RF shielding object can lower the RSSI of a potential parent node. Due to the RF shielding object, the area in which the RSSI of node X is above the threshold is significantly reduced. This causes the idle node to disregard node X even though node X is physically adjacent. The idle node will instead form an upstream connection with the physically distant node Y due to a stronger RSSI.
.. note::
Nodes technically still receive all beacon frames on the MAC layer. The RSSI threshold is an ESP-MESH feature that simply filters out all received beacon frames that are below the preconfigured threshold.
Nodes technically still receive all beacon frames on the MAC layer. The RSSI threshold is an ESP-WIFI-MESH feature that simply filters out all received beacon frames that are below the preconfigured threshold.
Preferred Parent Node
^^^^^^^^^^^^^^^^^^^^^
@ -184,7 +170,7 @@ When an idle node has multiple parent nodes candidates (potential parent nodes),
- Which layer the parent node candidate is situated on
- The number of downstream connections (child nodes) the parent node candidate currently has
The selection of the preferred parent node will always prioritize the parent node candidate on the shallowest layer of the network (including the root node). This helps minimize the total number of layers in an ESP-MESH network when upstream connections are formed. For example, given a second layer node and a third layer node, the second layer node will always be preferred.
The selection of the preferred parent node will always prioritize the parent node candidate on the shallowest layer of the network (including the root node). This helps minimize the total number of layers in an ESP-WIFI-MESH network when upstream connections are formed. For example, given a second layer node and a third layer node, the second layer node will always be preferred.
If there are multiple parent node candidates within the same layer, the parent node candidate with the least child nodes will be preferred. This criteria has the effect of balancing the number of downstream connections amongst nodes of the same layer.
@ -197,7 +183,7 @@ If there are multiple parent node candidates within the same layer, the parent n
**Panel A** of the illustration above demonstrates an example of how the idle node G selects a preferred parent node given the five parent node candidates B/C/D/E/F. Nodes on the shallowest layer are preferred, hence nodes B/C are prioritized since they are second layer nodes whereas nodes D/E/F are on the third layer. Node C is selected as the preferred parent node due it having fewer downstream connections (fewer child nodes) compared to node B.
**Panel B** of the illustration above demonstrates the case where the root node is within range of the idle node G. In other words, the root node's beacon frames are above the RSSI threshold when received by node G. The root node is always the shallowest node in an ESP-MESH network hence is always the preferred parent node given multiple parent node candidates.
**Panel B** of the illustration above demonstrates the case where the root node is within range of the idle node G. In other words, the root node's beacon frames are above the RSSI threshold when received by node G. The root node is always the shallowest node in an ESP-WIFI-MESH network hence is always the preferred parent node given multiple parent node candidates.
.. note::
Users may also define their own algorithm for selecting a preferred parent node, or force a node to only connect with a specific parent node (see the :example:`Mesh Manual Networking Example<mesh/manual_networking>`).
@ -205,27 +191,25 @@ If there are multiple parent node candidates within the same layer, the parent n
Routing Tables
^^^^^^^^^^^^^^
Each node within an ESP-MESH network will maintain its individual routing table used to correctly route ESP-MESH packets (see `ESP-MESH Packet`_) to the correct destination node. The routing table of a particular node will **consist of the MAC addresses of all nodes within the particular node's subnetwork** (including the MAC address of the particular node itself). Each routing table is internally partitioned into multiple subtables with each subtable corresponding to the subnetwork of each child node.
Each node within an ESP-WIFI-MESH network will maintain its individual routing table used to correctly route ESP-WIFI-MESH packets (see `ESP-WIFI-MESH Packet`_) to the correct destination node. The routing table of a particular node will **consist of the MAC addresses of all nodes within the particular node's subnetwork** (including the MAC address of the particular node itself). Each routing table is internally partitioned into multiple subtables with each subtable corresponding to the subnetwork of each child node.
.. figure:: ../../_static/mesh-routing-tables-example.png
:align: center
:alt: Diagram of ESP-MESH Routing Tables Example
:alt: Diagram of ESP-WIFI-MESH Routing Tables Example
:figclass: align-center
ESP-MESH Routing Tables Example
ESP-WIFI-MESH Routing Tables Example
Using the diagram above as an example, the routing table of node B would consist of the MAC addresses of nodes B to I (i.e. equivalent to the subnetwork of node B). Node B's routing table is internally partitioned into two subtables containing of nodes C to F and nodes G to I (i.e. equivalent to the subnetworks of nodes C and G respectively).
**ESP-MESH utilizes routing tables to determine whether an ESP-MESH packet should be forwarded upstream or downstream based on the following rules.**
**ESP-WIFI-MESH utilizes routing tables to determine whether an ESP-WIFI-MESH packet should be forwarded upstream or downstream based on the following rules.**
**1.** If the packet's destination MAC address is within the current node's routing table and is not the current node, select the subtable that contains the destination MAC address and forward the data packet downstream to the child node corresponding to the subtable.
**2.** If the destination MAC address is not within the current node's routing table, forward the data packet upstream to the current node's parent node. Doing so repeatedly will result in the packet arriving at the root node where the routing table should contain all nodes within the network.
.. note::
Users can call :cpp:func:`esp_mesh_get_routing_table` to obtain a node's routing table, or :cpp:func:`esp_mesh_get_routing_table_size` to obtain the size of a node's routing table.
:cpp:func:`esp_mesh_get_subnet_nodes_list` can be used to obtain the corresponding subtable of a specific child node. Likewise :cpp:func:`esp_mesh_get_subnet_nodes_num` can be used to obtain the size of the subtable.
Users can call :cpp:func:`esp_mesh_get_routing_table` to obtain a node's routing table, or :cpp:func:`esp_mesh_get_routing_table_size` to obtain the size of a node's routing table. :cpp:func:`esp_mesh_get_subnet_nodes_list` can be used to obtain the corresponding subtable of a specific child node. Likewise :cpp:func:`esp_mesh_get_subnet_nodes_num` can be used to obtain the size of the subtable.
.. ------------------------ Building a Mesh Network ---------------------------
@ -239,16 +223,16 @@ General Process
^^^^^^^^^^^^^^^
.. warning::
Before the ESP-MESH network building process can begin, certain parts of the configuration must be uniform across each node in the network (see :cpp:type:`mesh_cfg_t`). Each node must be configured with **the same Mesh Network ID, router configuration, and softAP configuration**.
Before the ESP-WIFI-MESH network building process can begin, certain parts of the configuration must be uniform across each node in the network (see :cpp:type:`mesh_cfg_t`). Each node must be configured with **the same Mesh Network ID, router configuration, and softAP configuration**.
An ESP-MESH network building process involves selecting a root node, then forming downstream connections layer by layer until all nodes have joined the network. The exact layout of the network can be dependent on factors such as root node selection, parent node selection, and asynchronous power-on reset. However, the ESP-MESH network building process can be generalized into the following steps:
An ESP-WIFI-MESH network building process involves selecting a root node, then forming downstream connections layer by layer until all nodes have joined the network. The exact layout of the network can be dependent on factors such as root node selection, parent node selection, and asynchronous power-on reset. However, the ESP-WIFI-MESH network building process can be generalized into the following steps:
.. figure:: ../../_static/mesh-network-building.png
:align: center
:alt: Diagram of ESP-MESH Network Building Process
:alt: Diagram of ESP-WIFI-MESH Network Building Process
:figclass: align-center
ESP-MESH Network Building Process
ESP-WIFI-MESH Network Building Process
1. Root Node Selection
""""""""""""""""""""""
@ -275,7 +259,7 @@ Each node will then simultaneously scan for the beacon frames from other idle no
After all iterations, each node will individually check for its **vote percentage** (``number of votes/number of nodes participating in election``) to determine if it should become the root node. **If a node has a vote percentage larger than a preconfigured threshold (90% by default), the node will become a root node**.
The following diagram demonstrates how an ESP-MESH network is built when the root node is automatically selected.
The following diagram demonstrates how an ESP-WIFI-MESH network is built when the root node is automatically selected.
.. figure:: ../../_static/mesh-root-node-election-example.png
:align: center
@ -296,12 +280,12 @@ The following diagram demonstrates how an ESP-MESH network is built when the roo
The minimum number of iterations for the election process can be configured using :cpp:func:`esp_mesh_set_attempts`. Users should adjust the number of iterations based on the number of nodes within the network (i.e. the larger the network the larger number of scan iterations required).
.. warning::
**Vote percentage threshold** can also be configured using :cpp:func:`esp_mesh_set_vote_percentage`. Setting a low vote percentage threshold **can result in two or more nodes becoming root nodes** within the same ESP-MESH network leading to the building of multiple networks. If such is the case, ESP-MESH has internal mechanisms to autonomously resolve the **root node conflict**. The networks of the multiple root nodes will be combined into a single network with a single root node. However, root node conflicts where two or more root nodes have the same router SSID but different router BSSID are not handled.
**Vote percentage threshold** can also be configured using :cpp:func:`esp_mesh_set_vote_percentage`. Setting a low vote percentage threshold **can result in two or more nodes becoming root nodes** within the same ESP-WIFI-MESH network leading to the building of multiple networks. If such is the case, ESP-WIFI-MESH has internal mechanisms to autonomously resolve the **root node conflict**. The networks of the multiple root nodes will be combined into a single network with a single root node. However, root node conflicts where two or more root nodes have the same router SSID but different router BSSID are not handled.
User Designated Root Node
^^^^^^^^^^^^^^^^^^^^^^^^^
The root node can also be designated by user which will entail the designated root node to directly connect with the router and forgo the election process. When a root node is designated, all other nodes within the network must also forgo the election process to prevent the occurrence of a root node conflict. The following diagram demonstrates how an ESP-MESH network is built when the root node is designated by the user.
The root node can also be designated by user which will entail the designated root node to directly connect with the router and forgo the election process. When a root node is designated, all other nodes within the network must also forgo the election process to prevent the occurrence of a root node conflict. The following diagram demonstrates how an ESP-WIFI-MESH network is built when the root node is designated by the user.
.. figure:: ../../_static/mesh-root-node-designated-example.png
:align: center
@ -324,14 +308,14 @@ The root node can also be designated by user which will entail the designated ro
Parent Node Selection
^^^^^^^^^^^^^^^^^^^^^
By default, ESP-MESH is self organizing meaning that each node will autonomously select which potential parent node to form an upstream connection with. The autonomously selected parent node is known as the preferred parent node. The criteria used for selecting the preferred parent node is designed to reduce the number of layers in the ESP-MESH network and to balance the number of downstream connections between potential parent nodes (see section on `Preferred Parent Node`_).
By default, ESP-WIFI-MESH is self organizing meaning that each node will autonomously select which potential parent node to form an upstream connection with. The autonomously selected parent node is known as the preferred parent node. The criteria used for selecting the preferred parent node is designed to reduce the number of layers in the ESP-WIFI-MESH network and to balance the number of downstream connections between potential parent nodes (see section on `Preferred Parent Node`_).
However ESP-MESH also allows users to disable self-organizing behavior which will allow users to define their own criteria for parent node selection, or to configure nodes to have designated parent nodes (see the :example:`Mesh Manual Networking Example<mesh/manual_networking>`).
However ESP-WIFI-MESH also allows users to disable self-organizing behavior which will allow users to define their own criteria for parent node selection, or to configure nodes to have designated parent nodes (see the :example:`Mesh Manual Networking Example<mesh/manual_networking>`).
Asynchronous Power-on Reset
^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH network building can be affected by the order in which nodes power-on. If certain nodes within the network power-on asynchronously (i.e. separated by several minutes), **the final structure of the network could differ from the ideal case where all nodes are powered on synchronously**. Nodes that are delayed in powering on will adhere to the following rules:
ESP-WIFI-MESH network building can be affected by the order in which nodes power-on. If certain nodes within the network power-on asynchronously (i.e. separated by several minutes), **the final structure of the network could differ from the ideal case where all nodes are powered on synchronously**. Nodes that are delayed in powering on will adhere to the following rules:
**Rule 1:** If a root node already exists in the network, the delayed node will not attempt to elect a new root node, even if it has a stronger RSSI with the router. The delayed node will instead join the network like any other idle node by connecting with a preferred parent node. If the delayed node is the designated root node, all other nodes in the network will remain idle until the delayed node powers-on.
@ -359,14 +343,14 @@ The following example demonstrates the effects of asynchronous power-on with reg
**Synchronous Power-On:** Had all nodes powered-on synchronously, node E would have become the root node as it has the strongest router RSSI (-10 dB). This would result in a significantly different network layout compared to the network formed under the conditions of asynchronous power-on. **However the synchronous power-on network layout can still be reached if the user manually switches the root node** (see :cpp:func:`esp_mesh_waive_root`).
.. note::
Differences in parent node selection caused by asynchronous power-on are autonomously corrected for to some extent in ESP-MESH (see `Parent Node Switching`_)
Differences in parent node selection caused by asynchronous power-on are autonomously corrected for to some extent in ESP-WIFI-MESH (see `Parent Node Switching`_)
Loop-back Avoidance, Detection, and Handling
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A loop-back is the situation where a particular node forms an upstream connection with one of its descendant nodes (a node within the particular node's subnetwork). This results in a circular connection path thereby breaking the tree topology. ESP-MESH prevents loop-back during parent selection by excluding nodes already present in the selecting node's routing table (see `Routing Tables`_) thus prevents a particular node from attempting to connect to any node within its subnetwork.
A loop-back is the situation where a particular node forms an upstream connection with one of its descendant nodes (a node within the particular node's subnetwork). This results in a circular connection path thereby breaking the tree topology. ESP-WIFI-MESH prevents loop-back during parent selection by excluding nodes already present in the selecting node's routing table (see `Routing Tables`_) thus prevents a particular node from attempting to connect to any node within its subnetwork.
In the event that a loop-back occurs, ESP-MESH utilizes a path verification mechanism and energy transfer mechanism to detect the loop-back occurrence. The parent node of the upstream connection that caused the loop-back will then inform the child node of the loop-back and initiate a disconnection.
In the event that a loop-back occurs, ESP-WIFI-MESH utilizes a path verification mechanism and energy transfer mechanism to detect the loop-back occurrence. The parent node of the upstream connection that caused the loop-back will then inform the child node of the loop-back and initiate a disconnection.
.. -------------------------- Network Management ------------------------------
@ -375,7 +359,7 @@ In the event that a loop-back occurs, ESP-MESH utilizes a path verification mech
Managing a Network
------------------
**ESP-MESH is a self healing network meaning it can detect and correct for failures in network routing**. Failures occur when a parent node with one or more child nodes breaks down, or when the connection between a parent node and its child nodes becomes unstable. Child nodes in ESP-MESH will autonomously select a new parent node and form an upstream connection with it to maintain network interconnectivity. ESP-MESH can handle both Root Node Failures and Intermediate Parent Node Failures.
**ESP-WIFI-MESH is a self healing network meaning it can detect and correct for failures in network routing**. Failures occur when a parent node with one or more child nodes breaks down, or when the connection between a parent node and its child nodes becomes unstable. Child nodes in ESP-WIFI-MESH will autonomously select a new parent node and form an upstream connection with it to maintain network interconnectivity. ESP-WIFI-MESH can handle both Root Node Failures and Intermediate Parent Node Failures.
Root Node Failure
^^^^^^^^^^^^^^^^^
@ -428,7 +412,7 @@ The following diagram illustrates an example of self healing from an Intermediat
Root Node Switching
^^^^^^^^^^^^^^^^^^^
ESP-MESH does not automatically switch the root node unless the root node breaks down. Even if the root node's router RSSI degrades to the point of disconnection, the root node will remain unchanged. Root node switching is the act of explicitly starting a new election such that a node with a stronger router RSSI will be elected as the new root node. This can be a useful method of adapting to degrading root node performance.
ESP-WIFI-MESH does not automatically switch the root node unless the root node breaks down. Even if the root node's router RSSI degrades to the point of disconnection, the root node will remain unchanged. Root node switching is the act of explicitly starting a new election such that a node with a stronger router RSSI will be elected as the new root node. This can be a useful method of adapting to degrading root node performance.
To trigger a root node switch, the current root node must explicitly call :cpp:func:`esp_mesh_waive_root` to trigger a new election. The current root node will signal all nodes within the network to begin transmitting and scanning for beacon frames (see `Automatic Root Node Selection`_) **whilst remaining connected to the network (i.e. not idle)**. If another node receives more votes than the current root node, a root node switch will be initiated. **The root node will remain unchanged otherwise**.
@ -452,14 +436,14 @@ The following diagram illustrates an example of a root node switch.
**4.** Node C selects node B as its preferred parent node, forms an upstream connection, and becomes a second layer node. The network layout is similar after the switch as node C still maintains the same subnetwork. However each node in node C's subnetwork has been placed one layer deeper as a result of the switch. `Parent Node Switching`_ may adjust the network layout afterwards if any nodes have a new preferred parent node as a result of the root node switch.
.. note::
Root node switching must require an election hence is only supported when using a self-organized ESP-MESH network. In other words, root node switching cannot occur if a designated root node is used.
Root node switching must require an election hence is only supported when using a self-organized ESP-WIFI-MESH network. In other words, root node switching cannot occur if a designated root node is used.
Parent Node Switching
^^^^^^^^^^^^^^^^^^^^^
Parent Node Switching entails a child node switching its upstream connection to another parent node of a shallower layer. **Parent Node Switching occurs autonomously** meaning that a child node will change its upstream connection automatically if a potential parent node of a shallower layer becomes available (i.e. due to a `Asynchronous Power-on Reset`_).
All potential parent nodes periodically transmit beacon frames (see `Beacon Frames & RSSI Thresholding`_) allowing for a child node to scan for the availability of a shallower parent node. Due to parent node switching, a self-organized ESP-MESH network can dynamically adjust its network layout to ensure each connection has a good RSSI and that the number of layers in the network is minimized.
All potential parent nodes periodically transmit beacon frames (see `Beacon Frames & RSSI Thresholding`_) allowing for a child node to scan for the availability of a shallower parent node. Due to parent node switching, a self-organized ESP-WIFI-MESH network can dynamically adjust its network layout to ensure each connection has a good RSSI and that the number of layers in the network is minimized.
.. --------------------------- Data Transmission ------------------------------
@ -469,43 +453,43 @@ All potential parent nodes periodically transmit beacon frames (see `Beacon Fram
Data Transmission
-----------------
ESP-MESH Packet
^^^^^^^^^^^^^^^
ESP-WIFI-MESH Packet
^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH network data transmissions use ESP-MESH packets. ESP-MESH packets are **entirely contained within the frame body of a Wi-Fi data frame**. A multi-hop data transmission in an ESP-MESH network will involve a single ESP-MESH packet being carried over each wireless hop by a different Wi-Fi data frame.
ESP-WIFI-MESH network data transmissions use ESP-WIFI-MESH packets. ESP-WIFI-MESH packets are **entirely contained within the frame body of a Wi-Fi data frame**. A multi-hop data transmission in an ESP-WIFI-MESH network will involve a single ESP-WIFI-MESH packet being carried over each wireless hop by a different Wi-Fi data frame.
The following diagram shows the structure of an ESP-MESH packet and its relation with a Wi-Fi data frame.
The following diagram shows the structure of an ESP-WIFI-MESH packet and its relation with a Wi-Fi data frame.
.. figure:: ../../_static/mesh-packet.png
:align: center
:alt: Diagram of ESP-MESH Packet
:alt: Diagram of ESP-WIFI-MESH Packet
:figclass: align-center
ESP-MESH Packet
ESP-WIFI-MESH Packet
**The header** of an ESP-MESH packet contains the MAC addresses of the source and destination nodes. The options field contains information pertaining to the special types of ESP-MESH packets such as a group transmission or a packet originating from the external IP network (see :c:macro:`MESH_OPT_SEND_GROUP` and :c:macro:`MESH_OPT_RECV_DS_ADDR`).
**The header** of an ESP-WIFI-MESH packet contains the MAC addresses of the source and destination nodes. The options field contains information pertaining to the special types of ESP-WIFI-MESH packets such as a group transmission or a packet originating from the external IP network (see :c:macro:`MESH_OPT_SEND_GROUP` and :c:macro:`MESH_OPT_RECV_DS_ADDR`).
**The payload** of an ESP-MESH packet contains the actual application data. This data can be raw binary data, or encoded under an application layer protocol such as HTTP, MQTT, and JSON (see :cpp:type:`mesh_proto_t`).
**The payload** of an ESP-WIFI-MESH packet contains the actual application data. This data can be raw binary data, or encoded under an application layer protocol such as HTTP, MQTT, and JSON (see :cpp:type:`mesh_proto_t`).
.. note::
When sending an ESP-MESH packet to the external IP network, the destination address field of the header will contain the IP address and port of the target server rather than the MAC address of a node (see :cpp:type:`mesh_addr_t`). Furthermore the root node will handle the formation of the outgoing TCP/IP packet.
When sending an ESP-WIFI-MESH packet to the external IP network, the destination address field of the header will contain the IP address and port of the target server rather than the MAC address of a node (see :cpp:type:`mesh_addr_t`). Furthermore the root node will handle the formation of the outgoing TCP/IP packet.
Group Control & Multicasting
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Multicasting is a feature that allows a single ESP-MESH packet to be transmitted simultaneously to multiple nodes within the network. Multicasting in ESP-MESH can be achieved by either specifying a list of target nodes, or specifying a preconfigured group of nodes. Both methods of multicasting are called via :cpp:func:`esp_mesh_send`.
Multicasting is a feature that allows a single ESP-WIFI-MESH packet to be transmitted simultaneously to multiple nodes within the network. Multicasting in ESP-WIFI-MESH can be achieved by either specifying a list of target nodes, or specifying a preconfigured group of nodes. Both methods of multicasting are called via :cpp:func:`esp_mesh_send`.
To multicast by specifying a list of target nodes, users must first set the ESP-MESH packet's destination address to the **Multicast-Group Address** (``01:00:5E:xx:xx:xx``). This signifies that the ESP-MESH packet is a multicast packet with a group of addresses, and that the address should be obtained from the header options. Users must then list the MAC addresses of the target nodes as options (see :cpp:type:`mesh_opt_t` and :c:macro:`MESH_OPT_SEND_GROUP`). This method of multicasting requires no prior setup but can incur a large amount of overhead data as each target node's MAC address must be listed in the options field of the header.
To multicast by specifying a list of target nodes, users must first set the ESP-WIFI-MESH packet's destination address to the **Multicast-Group Address** (``01:00:5E:xx:xx:xx``). This signifies that the ESP-WIFI-MESH packet is a multicast packet with a group of addresses, and that the address should be obtained from the header options. Users must then list the MAC addresses of the target nodes as options (see :cpp:type:`mesh_opt_t` and :c:macro:`MESH_OPT_SEND_GROUP`). This method of multicasting requires no prior setup but can incur a large amount of overhead data as each target node's MAC address must be listed in the options field of the header.
Multicasting by group allows a ESP-MESH packet to be transmitted to a preconfigured group of nodes. Each grouping is identified by a unique ID, and a node can be placed into a group via :cpp:func:`esp_mesh_set_group_id`. Multicasting to a group involves setting the destination address of the ESP-MESH packet to the target group ID. Furthermore, the :c:macro:`MESH_DATA_GROUP` flag must set. Using groups to multicast incurs less overhead, but requires nodes to previously added into groups.
Multicasting by group allows a ESP-WIFI-MESH packet to be transmitted to a preconfigured group of nodes. Each grouping is identified by a unique ID, and a node can be placed into a group via :cpp:func:`esp_mesh_set_group_id`. Multicasting to a group involves setting the destination address of the ESP-WIFI-MESH packet to the target group ID. Furthermore, the :c:macro:`MESH_DATA_GROUP` flag must set. Using groups to multicast incurs less overhead, but requires nodes to previously added into groups.
.. note::
During a multicast, all nodes within the network still receive the ESP-MESH packet on the MAC layer. However, nodes not included in the MAC address list or the target group will simply filter out the packet.
During a multicast, all nodes within the network still receive the ESP-WIFI-MESH packet on the MAC layer. However, nodes not included in the MAC address list or the target group will simply filter out the packet.
Broadcasting
^^^^^^^^^^^^
Broadcasting is a feature that allows a single ESP-MESH packet to be transmitted simultaneously to all nodes within the network. Each node essentially forwards a broadcast packet to all of its upstream and downstream connections such that the packet propagates throughout the network as quickly as possible. However, ESP-MESH utilizes the following methods to avoid wasting bandwidth during a broadcast.
Broadcasting is a feature that allows a single ESP-WIFI-MESH packet to be transmitted simultaneously to all nodes within the network. Each node essentially forwards a broadcast packet to all of its upstream and downstream connections such that the packet propagates throughout the network as quickly as possible. However, ESP-WIFI-MESH utilizes the following methods to avoid wasting bandwidth during a broadcast.
**1.** When an intermediate parent node receives a broadcast packet from its parent, it will forward the packet to each of its child nodes whilst storing a copy of the packet for itself.
@ -526,7 +510,7 @@ Broadcasting is a feature that allows a single ESP-MESH packet to be transmitted
Upstream Flow Control
^^^^^^^^^^^^^^^^^^^^^
ESP-MESH relies on parent nodes to control the upstream data flow of their immediate child nodes. To prevent a parent node's message buffer from overflowing due to an overload of upstream transmissions, a parent node will allocate a quota for upstream transmissions known as a **receiving window** for each of its child nodes. **Each child node must apply for a receiving window before it is permitted to transmit upstream**. The size of a receiving window can be dynamically adjusted. An upstream transmission from a child node to the parent node consists of the following steps:
ESP-WIFI-MESH relies on parent nodes to control the upstream data flow of their immediate child nodes. To prevent a parent node's message buffer from overflowing due to an overload of upstream transmissions, a parent node will allocate a quota for upstream transmissions known as a **receiving window** for each of its child nodes. **Each child node must apply for a receiving window before it is permitted to transmit upstream**. The size of a receiving window can be dynamically adjusted. An upstream transmission from a child node to the parent node consists of the following steps:
**1.** Before each transmission, the child node sends a window request to its parent node. The window request consists of a sequence number which corresponds to the child node's data packet that is pending transmission.
@ -535,26 +519,26 @@ ESP-MESH relies on parent nodes to control the upstream data flow of their immed
**3.** The child node transmits the data packet in accordance with the window size specified by the parent node. If the child node depletes its receiving window, it must obtain another receiving windows by sending a request before it is permitted to continue transmitting.
.. note::
ESP-MESH does not support any downstream flow control.
ESP-WIFI-MESH does not support any downstream flow control.
.. warning::
Due to `Parent Node Switching`_, packet loss may occur during upstream transmissions.
Due to the fact that the root node acts as the sole interface to an external IP network, it is critical that downstream nodes are aware of the root node's connection status with the external IP network. Failing to do so can lead to nodes attempting to pass data upstream to the root node whilst it is disconnected from the IP network. This results in unnecessary transmissions and packet loss. ESP-MESH address this issue by providing a mechanism to stabilize the throughput of outgoing data based on the connection status between the root node and the external IP network. The root node can broadcast its external IP network connection status to all other nodes by calling :cpp:func:`esp_mesh_post_toDS_state`.
Due to the fact that the root node acts as the sole interface to an external IP network, it is critical that downstream nodes are aware of the root node's connection status with the external IP network. Failing to do so can lead to nodes attempting to pass data upstream to the root node whilst it is disconnected from the IP network. This results in unnecessary transmissions and packet loss. ESP-WIFI-MESH address this issue by providing a mechanism to stabilize the throughput of outgoing data based on the connection status between the root node and the external IP network. The root node can broadcast its external IP network connection status to all other nodes by calling :cpp:func:`esp_mesh_post_toDS_state`.
Bi-Directional Data Stream
^^^^^^^^^^^^^^^^^^^^^^^^^^
The following diagram illustrates the various network layers involved in an ESP-MESH Bidirectional Data Stream.
The following diagram illustrates the various network layers involved in an ESP-WIFI-MESH Bidirectional Data Stream.
.. figure:: ../../_static/mesh-bidirectional-data-stream.png
:align: center
:alt: Diagram of ESP-MESH Bidirectional Data Stream
:alt: Diagram of ESP-WIFI-MESH Bidirectional Data Stream
:figclass: align-center
ESP-MESH Bidirectional Data Stream
ESP-WIFI-MESH Bidirectional Data Stream
Due to the use of `Routing Tables`_, **ESP-MESH is able to handle pack forwarding entirely on the mesh layer**. A TCP/IP layer is only required on the root node when it transmits/receives a packet to/from an external IP network.
Due to the use of `Routing Tables`_, **ESP-WIFI-MESH is able to handle pack forwarding entirely on the mesh layer**. A TCP/IP layer is only required on the root node when it transmits/receives a packet to/from an external IP network.
.. --------------------------- Channel Switching -------------------------------
@ -575,60 +559,60 @@ In an infrastructure Wi-Fi network, network channel switches are triggered by th
A CSA element contains information regarding the **New Channel Number** and a **Channel Switch Count** which indicates the number of beacon frame intervals (TBTTs) remaining until the network channel switch occurs. Therefore, the Channel Switch Count is decremented every beacon frame and allows connected stations to synchronize their channel switch with the AP.
ESP-MESH Network Channel Switching
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-WIFI-MESH Network Channel Switching
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH Network Channel Switching also utilize beacon frames that contain a CSA element. However, being a multi-hop network makes the switching process in ESP-MESH is more complex due to the fact that a beacon frame might not be able to reach all nodes within the network (i.e. in a single hop). Therefore, an ESP-MESH network relies on nodes to forward the CSA element so that it is propagated throughout the network.
ESP-WIFI-MESH Network Channel Switching also utilize beacon frames that contain a CSA element. However, being a multi-hop network makes the switching process in ESP-WIFI-MESH is more complex due to the fact that a beacon frame might not be able to reach all nodes within the network (i.e. in a single hop). Therefore, an ESP-WIFI-MESH network relies on nodes to forward the CSA element so that it is propagated throughout the network.
When an intermediate parent node with one or more child nodes receives a beacon frame containing a CSA, the node will forward the CSA element by including the element in its next transmitted beacon frame (i.e. with the same **New Channel Number** and **Channel Switch Count**). Given that all nodes within an ESP-MESH network receive the same CSA, the nodes can synchronize their channel switches using the Channel Switch Count, albeit with a short delay due to CSA element forwarding.
When an intermediate parent node with one or more child nodes receives a beacon frame containing a CSA, the node will forward the CSA element by including the element in its next transmitted beacon frame (i.e. with the same **New Channel Number** and **Channel Switch Count**). Given that all nodes within an ESP-WIFI-MESH network receive the same CSA, the nodes can synchronize their channel switches using the Channel Switch Count, albeit with a short delay due to CSA element forwarding.
An ESP-MESH network channel switch can be triggered by either the router or the root node.
An ESP-WIFI-MESH network channel switch can be triggered by either the router or the root node.
Root Node Triggered
"""""""""""""""""""
**A root node triggered channel switch can only occur when the ESP-MESH network is not connected to a router**. By calling :cpp:func:`esp_mesh_switch_channel`, the root node will set an initial Channel Switch Count value and begin including a CSA element in its beacon frames. Each CSA element is then received by second layer nodes, and forwarded downstream in the their own beacon frames.
**A root node triggered channel switch can only occur when the ESP-WIFI-MESH network is not connected to a router**. By calling :cpp:func:`esp_mesh_switch_channel`, the root node will set an initial Channel Switch Count value and begin including a CSA element in its beacon frames. Each CSA element is then received by second layer nodes, and forwarded downstream in the their own beacon frames.
Router Triggered
""""""""""""""""
When an ESP-MESH network is connected to a router, the entire network must use the same channel as the router. Therefore, **the root node will not be permitted to trigger a channel switch when it is connected to a router**.
When an ESP-WIFI-MESH network is connected to a router, the entire network must use the same channel as the router. Therefore, **the root node will not be permitted to trigger a channel switch when it is connected to a router**.
When the root node receives beacon frame containing a CSA element from the router, **the root node will set Channel Switch Count value in the CSA element to a custom value before forwarding it downstream via beacon frames**. It will also decrement the Channel Switch Count of subsequent CSA elements relative to the custom value. This custom value can be based on factors such as the number of network layers, the current number of nodes etc.
The setting the Channel Switch Count value to a custom value is due to the fact that the ESP-MESH network and its router may have a different and varying beacon intervals. Therefore, the Channel Switch Count value provided by the router is irrelevant to an ESP-MESH network. By using a custom value, nodes within the ESP-MESH network are able to switch channels synchronously relative to the ESP-MESH network's beacon interval. However, this will also result in the ESP-MESH network's channel switch being unsynchronized with the channel switch of the router and its connected stations.
The setting the Channel Switch Count value to a custom value is due to the fact that the ESP-WIFI-MESH network and its router may have a different and varying beacon intervals. Therefore, the Channel Switch Count value provided by the router is irrelevant to an ESP-WIFI-MESH network. By using a custom value, nodes within the ESP-WIFI-MESH network are able to switch channels synchronously relative to the ESP-WIFI-MESH network's beacon interval. However, this will also result in the ESP-WIFI-MESH network's channel switch being unsynchronized with the channel switch of the router and its connected stations.
Impact of Network Channel Switching
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Due to the ESP-MESH network channel switch being unsynchronized with the router's channel switch, there will be a **temporary channel discrepancy** between the ESP-MESH network and the router.
- The ESP-MESH network's channel switch time is dependent on the ESP-MESH network's beacon interval and the root node's custom Channel Switch Count value.
- The channel discrepancy prevents any data exchange between the root node and the router during that ESP-MESH network's switch.
- In the ESP-MESH network, the root node and intermediate parent nodes will request their connected child nodes to stop transmissions until the channel switch takes place by setting the **Channel Switch Mode** field in the CSA element to 1.
- Frequent router triggered network channel switches can degrade the ESP-MESH network's performance. Note that this can be caused by the ESP-MESH network itself (e.g. due to wireless medium contention with ESP-MESH network). If this is the case, users should disable the automatic channel switching on the router and use a specified channel instead.
- Due to the ESP-WIFI-MESH network channel switch being unsynchronized with the router's channel switch, there will be a **temporary channel discrepancy** between the ESP-WIFI-MESH network and the router.
- The ESP-WIFI-MESH network's channel switch time is dependent on the ESP-WIFI-MESH network's beacon interval and the root node's custom Channel Switch Count value.
- The channel discrepancy prevents any data exchange between the root node and the router during that ESP-WIFI-MESH network's switch.
- In the ESP-WIFI-MESH network, the root node and intermediate parent nodes will request their connected child nodes to stop transmissions until the channel switch takes place by setting the **Channel Switch Mode** field in the CSA element to 1.
- Frequent router triggered network channel switches can degrade the ESP-WIFI-MESH network's performance. Note that this can be caused by the ESP-WIFI-MESH network itself (e.g. due to wireless medium contention with ESP-WIFI-MESH network). If this is the case, users should disable the automatic channel switching on the router and use a specified channel instead.
- When there is a **temporary channel discrepancy**, the root node remains technically connected to the router.
- Disconnection occurs after the root node fails to receive any beacon frames or probe responses from the router over a fixed number of router beacon intervals.
- Upon disconnection, the root node will automatically re-scan all channels for the presence of a router.
- If the root node is unable to receive any of the router's CSA beacon frames (e.g. due to short switch time given by the router), the router will switch channels without the ESP-MESH network's knowledge.
- If the root node is unable to receive any of the router's CSA beacon frames (e.g. due to short switch time given by the router), the router will switch channels without the ESP-WIFI-MESH network's knowledge.
- After the router switches channels, the root node will no longer be able to receive the router's beacon frames and probe responses and result in a disconnection after a fixed number of beacon intervals.
- The root node will re-scan all channels for the router after disconnection.
- The root node will maintain downstream connections throughout this process.
.. note::
Although ESP-MESH network channel switching aims to move all nodes within the network to a new operating channel, it should be recognized that a channel switch might not successfully move all nodes (e.g. due to reasons such as node failures).
Although ESP-WIFI-MESH network channel switching aims to move all nodes within the network to a new operating channel, it should be recognized that a channel switch might not successfully move all nodes (e.g. due to reasons such as node failures).
Channel and Router Switching Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH allows for autonomous channel switching to be enabled/disabled via configuration. Likewise, autonomous router switching (i.e. when a root node autonomously connects to another router) can also be enabled/disabled by configuration. Autonomous channel switching and router switching is dependent on the following configuration parameters and run-time conditions.
ESP-WIFI-MESH allows for autonomous channel switching to be enabled/disabled via configuration. Likewise, autonomous router switching (i.e. when a root node autonomously connects to another router) can also be enabled/disabled by configuration. Autonomous channel switching and router switching is dependent on the following configuration parameters and run-time conditions.
**Allow Channel Switch:** This parameter is set via the ``allow_channel_switch`` field of the :cpp:type:`mesh_cfg_t` structure and permits an ESP-MESH network to dynamically switch channels when set.
**Allow Channel Switch:** This parameter is set via the ``allow_channel_switch`` field of the :cpp:type:`mesh_cfg_t` structure and permits an ESP-WIFI-MESH network to dynamically switch channels when set.
**Preset Channel:** An ESP-MESH network can have a preset channel by setting the ``channel`` field of the :cpp:type:`mesh_cfg_t` structure to the desired channel number. If this field is unset, the ``allow_channel_switch`` parameter is overridden such that channel switches are always permitted.
**Preset Channel:** An ESP-WIFI-MESH network can have a preset channel by setting the ``channel`` field of the :cpp:type:`mesh_cfg_t` structure to the desired channel number. If this field is unset, the ``allow_channel_switch`` parameter is overridden such that channel switches are always permitted.
**Allow Router Switch:** This parameter is set via the ``allow_router_switch`` field of the :cpp:type:`mesh_router_t` and permits an ESP-MESH to dynamically switch to a different router when set.
**Allow Router Switch:** This parameter is set via the ``allow_router_switch`` field of the :cpp:type:`mesh_router_t` and permits an ESP-WIFI-MESH to dynamically switch to a different router when set.
**Preset Router BSSID:** An ESP-MESH network can have a preset router by setting the ``bssid`` field of the :cpp:type:`mesh_router_t` structure to the
**Preset Router BSSID:** An ESP-WIFI-MESH network can have a preset router by setting the ``bssid`` field of the :cpp:type:`mesh_router_t` structure to the
BSSID of the desired router. If this field is unset, the ``allow_router_switch`` parameter is overridden such that router switches are always permitted.
**Root Node Present:** The presence of a root node will can also affect whether or a channel or router switch is permitted.
@ -725,17 +709,17 @@ The following table illustrates how the different combinations of parameters/con
Performance
-----------
The performance of an ESP-MESH network can be evaluated based on multiple metrics such as the following:
The performance of an ESP-WIFI-MESH network can be evaluated based on multiple metrics such as the following:
**Network Building Time:** The amount of time taken to build an ESP-MESH network from scratch.
**Network Building Time:** The amount of time taken to build an ESP-WIFI-MESH network from scratch.
**Healing Time:** The amount of time taken for the network to detect a node break down and carry out appropriate actions to heal the network (such as generating a new root node or forming new connections).
**Per-hop latency:** The latency of data transmission over one wireless hop. In other words, the time taken to transmit a data packet from a parent node to a child node or vice versa.
**Network Node Capacity:** The total number of nodes the ESP-MESH network can simultaneously support. This number is determined by the maximum number of downstream connections a node can accept and the maximum number of layers permissible in the network.
**Network Node Capacity:** The total number of nodes the ESP-WIFI-MESH network can simultaneously support. This number is determined by the maximum number of downstream connections a node can accept and the maximum number of layers permissible in the network.
The following table lists the common performance figures of an ESP-MESH network:
The following table lists the common performance figures of an ESP-WIFI-MESH network:
* Network Building Time: < 60 seconds
* Healing time:
@ -754,7 +738,7 @@ The following table lists the common performance figures of an ESP-MESH network:
Throughput depends on packet error rate and hop count.
.. note::
The throughput of root node's access to the external IP network is directly affected by the number of nodes in the ESP-MESH network and the bandwidth of the router.
The throughput of root node's access to the external IP network is directly affected by the number of nodes in the ESP-WIFI-MESH network and the bandwidth of the router.
.. note::
The performance figures can vary greatly between installations based on network configuration and operating environment.

2
docs/en/api-guides/event-handling.rst
View File

@ -130,7 +130,7 @@ Event IDs and Corresponding Data Structures
Mesh Events
-----------
ESP-MESH uses a system similar to the :ref:`legacy-event-loop` to deliver events to the application. See :ref:`mesh-events` for details.
ESP-WIFI-MESH uses a system similar to the :ref:`legacy-event-loop` to deliver events to the application. See :ref:`mesh-events` for details.
Bluetooth Events
----------------

2
docs/en/api-guides/index.rst
View File

@ -15,7 +15,7 @@ API Guides
:SOC_USB_SUPPORTED: Device Firmware Upgrade through USB <dfu>
Error Handling <error-handling>
:SOC_BT_SUPPORTED: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
ESP-WIFI-MESH <esp-wifi-mesh>
Core Dump <core_dump>
Event Handling <event-handling>
:SOC_SPIRAM_SUPPORTED: External SPI-connected RAM <external-ram>

128
docs/en/api-reference/network/esp_mesh.rst → docs/en/api-reference/network/esp-wifi-mesh.rst
View File

@ -1,7 +1,9 @@
ESP-MESH Programming Guide
==========================
ESP-WIFI-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:
:link_to_translation:`zh_CN:[中文]`
This is a programming guide for ESP-WIFI-MESH, including the API reference and coding examples. This guide is split into the following parts:
1. :ref:`mesh-programming-model`
@ -13,62 +15,62 @@ This is a programming guide for ESP-MESH, including the API reference and coding
5. :ref:`mesh-api-reference`
For documentation regarding the ESP-MESH protocol, please see the :doc:`ESP-MESH API Guide<../../api-guides/mesh>`. For more information about ESP-MESH Development Framework, please see `ESP-MESH Development Framework <https://github.com/espressif/esp-mdf>`_.
For documentation regarding the ESP-WIFI-MESH protocol, please see the :doc:`ESP-WIFI-MESH API Guide<../../api-guides/esp-wifi-mesh>`. For more information about ESP-WIFI-MESH Development Framework, please see `ESP-WIFI-MESH Development Framework <https://github.com/espressif/esp-mdf>`_.
.. ---------------------- ESP-MESH Programming Model --------------------------
.. ---------------------- ESP-WIFI-MESH Programming Model --------------------------
.. _mesh-programming-model:
ESP-MESH Programming Model
--------------------------
ESP-WIFI-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.
The ESP-WIFI-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-WIFI-MESH software stack.
.. _mesh-going-to-software-stack:
.. figure:: ../../../_static/mesh-software-stack.png
:align: center
:alt: ESP-MESH Software Stack
:alt: ESP-WIFI-MESH Software Stack
:figclass: align-center
ESP-MESH Software Stack
ESP-WIFI-MESH Software Stack
.. _mesh-events:
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.
An application interfaces with ESP-WIFI-MESH via **ESP-WIFI-MESH Events**. Since ESP-WIFI-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-WIFI-MESH application.
.. figure:: ../../../_static/mesh-events-delivery.png
:align: center
:alt: ESP-MESH System Events Delivery
:alt: ESP-WIFI-MESH System Events Delivery
:figclass: align-center
ESP-MESH System Events Delivery
ESP-WIFI-MESH System Events Delivery
The :cpp:type:`mesh_event_id_t` defines all possible ESP-MESH events and can indicate events such as the connection/disconnection of parent/child. Before ESP-MESH events can be used, the application must register a **Mesh Events handler** via :cpp:func:`esp_event_handler_register` to the default event task. The Mesh Events handler that is registered contain handlers for each ESP-MESH event relevant to the application.
The :cpp:type:`mesh_event_id_t` defines all possible ESP-WIFI-MESH events and can indicate events such as the connection/disconnection of parent/child. Before ESP-WIFI-MESH events can be used, the application must register a **Mesh Events handler** via :cpp:func:`esp_event_handler_register` to the default event task. The Mesh Events handler that is registered contain handlers for each ESP-WIFI-MESH event relevant to the application.
Typical use cases of mesh 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:`IP_EVENT_STA_GOT_IP` and :cpp:enumerator:`IP_EVENT_STA_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.
When using ESP-WIFI-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-WIFI-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
^^^^^^^^^^^^^^^
LwIP & ESP-WIFI-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.
The application can access the ESP-WIFI-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.
The following code snippet demonstrates how to initialize LwIP for ESP-WIFI-MESH applications.
.. code-block:: c
@ -84,17 +86,17 @@ The following code snippet demonstrates how to initialize LwIP for ESP-MESH appl
.. 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.
ESP-WIFI-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
-------------------------------
Writing an ESP-WIFI-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.
The prerequisites for starting ESP-WIFI-MESH is to initialize LwIP and Wi-Fi, The following code snippet demonstrates the necessary prerequisite steps before ESP-WIFI-MESH itself can be initialized.
.. code-block:: c
@ -118,7 +120,7 @@ The prerequisites for starting ESP-MESH is to initialize LwIP and Wi-Fi, The fol
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:
After initializing LwIP and Wi-Fi, the process of getting an ESP-WIFI-MESH network up and running can be summarized into the following three steps:
1. :ref:`mesh-initialize-mesh`
2. :ref:`mesh-configuring-mesh`
@ -129,7 +131,7 @@ After initializing LwIP and Wi-Fi, the process of getting an ESP-MESH network up
Initialize Mesh
^^^^^^^^^^^^^^^
The following code snippet demonstrates how to initialize ESP-MESH
The following code snippet demonstrates how to initialize ESP-WIFI-MESH
.. code-block:: c
@ -140,32 +142,38 @@ The following code snippet demonstrates how to initialize ESP-MESH
.. _mesh-configuring-mesh:
Configuring an ESP-MESH Network
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configuring an ESP-WIFI-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:
ESP-WIFI-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-WIFI-MESH:
+------------------+-------------------------------------+
| Parameter | Description |
+==================+=====================================+
| Channel | Range from 1 to 14 |
+------------------+-------------------------------------+
| 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.
.. list-table::
:header-rows: 1
:widths: 15 25
* - Parameter
- Description
* - Channel
- Range from 1 to 14
* - Mesh ID
- ID of ESP-WIFI-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-WIFI-MESH.
.. code-block:: c
@ -191,30 +199,30 @@ The following code snippet demonstrates how to configure ESP-MESH.
Start Mesh
^^^^^^^^^^
The following code snippet demonstrates how to start ESP-MESH.
The following code snippet demonstrates how to start ESP-WIFI-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`.
After starting ESP-WIFI-MESH, the application should check for ESP-WIFI-MESH events to determine when it has connected to the network. After connecting, the application can start transmitting and receiving packets over the ESP-WIFI-MESH network using :cpp:func:`esp_mesh_send` and :cpp:func:`esp_mesh_recv`.
.. --------------------- ESP-MESH Application Examples ------------------------
.. --------------------- ESP-WIFI-MESH Application Examples ------------------------
.. _mesh-self-organized-behavior:
Self Organized Networking
-------------------------
Self organized networking is a feature of ESP-MESH where nodes can autonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-MESH network to operate with high degree of autonomy by making the network robust to dynamic network topologies and conditions. With self organized networking enabled, nodes in an ESP-MESH network are able to carry out the following actions without autonomously:
Self organized networking is a feature of ESP-WIFI-MESH where nodes can autonomously scan/select/connect/reconnect to other nodes and routers. This feature allows an ESP-WIFI-MESH network to operate with high degree of autonomy by making the network robust to dynamic network topologies and conditions. With self organized networking enabled, nodes in an ESP-WIFI-MESH network are able to carry out the following actions without autonomously:
- Selection or election of the root node (see **Automatic Root Node Selection** in :ref:`mesh-building-a-network`)
- Selection of a preferred parent node (see **Parent Node Selection** in :ref:`mesh-building-a-network`)
- Automatic reconnection upon detecting a disconnection (see **Intermediate Parent Node Failure** in :ref:`mesh-managing-a-network`)
When self organized networking is enabled, the ESP-MESH stack will internally make calls to Wi-Fi APIs. Therefore, **the application layer should not make any calls to Wi-Fi APIs whilst self organized networking is enabled as doing so would risk interfering with ESP-MESH**.
When self organized networking is enabled, the ESP-WIFI-MESH stack will internally make calls to Wi-Fi APIs. Therefore, **the application layer should not make any calls to Wi-Fi APIs whilst self organized networking is enabled as doing so would risk interfering with ESP-WIFI-MESH**.
Toggling Self Organized Networking
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -234,7 +242,7 @@ The following code snippet demonstrates how to disable self organized networking
//Disable self organized networking
esp_mesh_set_self_organized(false, false);
ESP-MESH will attempt to maintain the node's current Wi-Fi state when disabling self organized networking.
ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when disabling self organized networking.
- If the node was previously connected to other nodes, it will remain connected.
- If the node was previously disconnected and was scanning for a parent node or router, it will stop scanning.
@ -243,7 +251,7 @@ ESP-MESH will attempt to maintain the node's current Wi-Fi state when disabling
Enabling Self Organized Networking
""""""""""""""""""""""""""""""""""
ESP-MESH will attempt to maintain the node's current Wi-Fi state when enabling self organized networking. However, depending on the node type and whether a new parent is selected, the Wi-Fi state of the node can change. The following table shows effects of enabling self organized networking.
ESP-WIFI-MESH will attempt to maintain the node's current Wi-Fi state when enabling self organized networking. However, depending on the node type and whether a new parent is selected, the Wi-Fi state of the node can change. The following table shows effects of enabling self organized networking.
+---------------+--------------+------------------------------------------------------------------------------------------------------------------+
| Select Parent | Is Root Node | Effects |
@ -278,9 +286,9 @@ The following code snipping demonstrates how to enable self organized networking
Calling Wi-Fi API
^^^^^^^^^^^^^^^^^
There can be instances in which an application may want to directly call Wi-Fi API whilst using ESP-MESH. For example, an application may want to manually scan for neighboring APs. However, **self organized networking must be disabled before the application calls any Wi-Fi APIs**. This will prevent the ESP-MESH stack from attempting to call any Wi-Fi APIs and potentially interfering with the application's calls.
There can be instances in which an application may want to directly call Wi-Fi API whilst using ESP-WIFI-MESH. For example, an application may want to manually scan for neighboring APs. However, **self organized networking must be disabled before the application calls any Wi-Fi APIs**. This will prevent the ESP-WIFI-MESH stack from attempting to call any Wi-Fi APIs and potentially interfering with the application's calls.
Therefore, application calls to Wi-Fi APIs should be placed in between calls of :cpp:func:`esp_mesh_set_self_organized` which disable and enable self organized networking. The following code snippet demonstrates how an application can safely call :cpp:func:`esp_wifi_scan_start` whilst using ESP-MESH.
Therefore, application calls to Wi-Fi APIs should be placed in between calls of :cpp:func:`esp_mesh_set_self_organized` which disable and enable self organized networking. The following code snippet demonstrates how an application can safely call :cpp:func:`esp_wifi_scan_start` whilst using ESP-WIFI-MESH.
.. code-block:: c
@ -311,21 +319,21 @@ Therefore, application calls to Wi-Fi APIs should be placed in between calls of
esp_mesh_connect(); //Manually reconnect to router
.. --------------------- ESP-MESH Application Examples ------------------------
.. --------------------- ESP-WIFI-MESH Application Examples ------------------------
.. _mesh-application-examples:
Application Examples
--------------------
ESP-IDF contains these ESP-MESH example projects:
ESP-IDF contains these ESP-WIFI-MESH example projects:
:example:`The Internal Communication Example<mesh/internal_communication>` demonstrates how to set up a ESP-MESH network and have the root node send a data packet to every node within the network.
:example:`The Internal Communication Example<mesh/internal_communication>` demonstrates how to set up a ESP-WIFI-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.
:example:`The Manual Networking Example<mesh/manual_networking>` demonstrates how to use ESP-WIFI-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 ---------------------------
.. ------------------------- ESP-WIFI-MESH API Reference ---------------------------
.. _mesh-api-reference:

4
docs/en/api-reference/network/index.rst
View File

@ -12,11 +12,11 @@ Wi-Fi
Wi-Fi <esp_wifi>
SmartConfig <esp_smartconfig>
ESP-NOW <esp_now>
ESP Mesh <esp_mesh>
ESP-WIFI-MESH <esp-wifi-mesh>
Code examples for the Wi-Fi API are provided in the :example:`wifi` directory of ESP-IDF examples.
Code examples for ESP-MESH are provided in the :example:`mesh` directory of ESP-IDF examples.
Code examples for ESP-WIFI-MESH are provided in the :example:`mesh` directory of ESP-IDF examples.
Ethernet

4
docs/page_redirects.txt
View File

@ -77,3 +77,7 @@ hw-reference/esp32s2/user-guide-kaluga-1-v1.2 hw-reference/esp32s2/user-guide-
api-guides/jtag-debugging/configure-wrover api-guides/jtag-debugging/configure-ft2232h-jtag
hw-reference/modules-and-boards "https://www.espressif.com/en/products/modules"
hw-reference/modules-and-boards-previous "https://www.espressif.com/en/products/modules"
# rename ESP-MESH to ESP-WIFI-MESH
api-guides/mesh api-guides/esp-wifi-mesh
api-reference/network/esp_mesh api-reference/network/esp-wifi-mesh

2
docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-index.rst
View File

@ -21,7 +21,7 @@ ESP-BLE-MESH 的实现和认证基于最新的 `Mesh Profile v1.0.1 <https://www
.. note::
如果您在寻找 ESP32 基于 Wi-Fi 的 mesh 方案，请查阅乐鑫的另一款产品 ESP-MESH。更多相关信息及文档，请参见 :doc:`ESP-MESH <../../api-reference/network/esp_mesh>`。
如果您在寻找 ESP32 基于 Wi-Fi 的 mesh 方案，请查阅乐鑫的另一款产品 ESP-WIFI-MESH。更多相关信息及文档，请参见 :doc:`ESP-WIFI-MESH <../../api-reference/network/esp-wifi-mesh>`。
.. _getting-started-with-ble-mesh:

194
docs/zh_CN/api-guides/mesh.rst → docs/zh_CN/api-guides/esp-wifi-mesh.rst
View File

@ -1,18 +1,18 @@
ESP-MESH
=========
ESP-WIFI-MESH
==================
:link_to_translation:`en:[English]`
本指南提供有关 ESP-MESH 协议的介绍。更多有关 API 使用的信息，请见 :doc:`MESH API 参考 <../api-reference/network/esp_mesh>`。
本指南提供有关 ESP-WIFI-MESH 协议的介绍。更多有关 API 使用的信息，请见 :doc:`ESP-WIFI-MESH API 参考 <../api-reference/network/esp-wifi-mesh>`。
.. -------------------------------概述 -----------------------------------
概述
--------
ESP-MESH 是一套建立在 Wi-Fi 协议之上的网络协议。ESP-MESH 允许分布在大范围区域内（室内和室外）的大量设备（下文称节点）在同一个 WLAN（无线局域网）中相互连接。ESP-MESH 具有自组网和自修复的特性，也就是说 mesh 网络可以自主地构建和维护。
ESP-WIFI-MESH 是一套建立在 Wi-Fi 协议之上的网络协议。ESP-WIFI-MESH 允许分布在大范围区域内（室内和室外）的大量设备（下文称节点）在同一个 WLAN（无线局域网）中相互连接。ESP-WIFI-MESH 具有自组网和自修复的特性，也就是说 mesh 网络可以自主地构建和维护。
本 ESP-MESH 指南分为以下几个部分：
本 ESP-WIFI-MESH 指南分为以下几个部分：
1. :ref:`mesh-introduction`
@ -47,22 +47,22 @@ ESP-MESH 是一套建立在 Wi-Fi 协议之上的网络协议。ESP-MESH 允许
传统基础设施 Wi-Fi 网络是一个“单点对多点”的网络。这种网络架构的中心节点为接入点 (AP)，其他节点 (station) 均与 AP 直接相连。其中，AP 负责各个 station 之间的仲裁和转发，一些 AP 还会通过路由器与外部 IP 网络交换数据。在传统 Wi-Fi 网络架构中，1）由于所有 station 均需与 AP 直接相连，不能距离 AP 太远，因此覆盖区域相对有限；2）受到 AP 容量的限制，因此网络中允许的 station 数量相对有限，很容易超载。
.. figure:: ../../_static/mesh-esp-mesh-network-architecture.png
.. figure:: ../../_static/mesh-esp-wifi-mesh-network-architecture.png
:align: center
:alt: ESP-MESH 网络架构示意图
:alt: ESP-WIFI-MESH 网络架构示意图
:figclass: align-center
ESP-MESH 网络架构示意图
ESP-WIFI-MESH 网络架构示意图
ESP-MESH 与传统 Wi-Fi 网络的不同之处在于：网络中的节点不需要连接到中心节点，而是可以与相邻节点连接。各节点均负责相连节点的数据中继。由于无需受限于距离中心节点的位置，所有节点仍可互连，因此 ESP-MESH 网络的覆盖区域更广。类似地，由于不再受限于中心节点的容量限制，ESP-MESH 允许更多节点接入，也不易于超载。
ESP-WIFI-MESH 与传统 Wi-Fi 网络的不同之处在于：网络中的节点不需要连接到中心节点，而是可以与相邻节点连接。各节点均负责相连节点的数据中继。由于无需受限于距离中心节点的位置，所有节点仍可互连，因此 ESP-WIFI-MESH 网络的覆盖区域更广。类似地，由于不再受限于中心节点的容量限制，ESP-WIFI-MESH 允许更多节点接入，也不易于超载。
.. --------------------------ESP-MESH 概念-------------------------------
.. --------------------------ESP-WIFI-MESH 概念-------------------------------
.. _mesh-concepts:
ESP-MESH 概念
-----------------
ESP-WIFI-MESH 概念
-------------------------
术语
^^^^^^^^^^^
@ -74,7 +74,7 @@ ESP-MESH 概念
* - 术语
- 描述
* - 节点
- 任何 **属于** 或 **可以成为** ESP-MESH 网络一部分的设备
- 任何 **属于** 或 **可以成为** ESP-WIFI-MESH 网络一部分的设备
* - 根节点
- 网络顶部的节点
* - 子节点
@ -86,7 +86,7 @@ ESP-MESH 概念
* - 兄弟节点
- 连接至同一个父节点的所有节点
* - 连接
- AP 和 station 之间的传统 Wi-Fi 关联。ESP-MESH 中的节点使用 station 接口与另一个节点的 SoftAP 接口产生关联，进而形成连接。连接包括 Wi-Fi 网络中的身份验证和关联过程。
- AP 和 station 之间的传统 Wi-Fi 关联。ESP-WIFI-MESH 中的节点使用 station 接口与另一个节点的 SoftAP 接口产生关联，进而形成连接。连接包括 Wi-Fi 网络中的身份验证和关联过程。
* - 上行连接
- 从节点到其父节点的连接
* - 下行连接
@ -94,42 +94,42 @@ ESP-MESH 概念
* - 无线 hop
- 源节点和目标节点间无线连接路径中的一部分。**单跳** 指遍历单个连接的数据包，**多跳** 指遍历多个连接的数据包。
* - 子网
- 子网指 ESP-MESH 网络的一部分，包括一个节点及其所有后代节点。因此，根节点的子网包括 ESP-MESH 网络中的所有节点。
- 子网指 ESP-WIFI-MESH 网络的一部分，包括一个节点及其所有后代节点。因此，根节点的子网包括 ESP-WIFI-MESH 网络中的所有节点。
* - MAC 地址
- 在 ESP-MESH 网络中用于区别每个节点或路由器的唯一地址
- 在 ESP-WIFI-MESH 网络中用于区别每个节点或路由器的唯一地址
* - DS
- 分布式系统（外部 IP 网络）
树型拓扑
^^^^^^^^^^^^^
ESP-MESH 建立在传统 Wi-Fi 协议之上，可被视为一种将多个独立 Wi-Fi 网络组合为一个单一 WLAN 网络的组网协议。在 Wi-Fi 网络中，station 在任何时候都仅限于与 AP 建立单个连接（上行连接），而 AP 则可以同时连接到多个 station（下行连接）。然而，ESP-MESH 网络则允许节点同时充当 station 和 AP。因此，ESP-MESH 中的节点可以使用 **其 SoftAP 接口建立多个下行连接**，同时使用 **其 station 接口建立一个上行连接**。这将自然产生一个由多层父子结构组成的树型网络拓扑结构。
ESP-WIFI-MESH 建立在传统 Wi-Fi 协议之上，可被视为一种将多个独立 Wi-Fi 网络组合为一个单一 WLAN 网络的组网协议。在 Wi-Fi 网络中，station 在任何时候都仅限于与 AP 建立单个连接（上行连接），而 AP 则可以同时连接到多个 station（下行连接）。然而，ESP-WIFI-MESH 网络则允许节点同时充当 station 和 AP。因此，ESP-WIFI-MESH 中的节点可以使用 **其 SoftAP 接口建立多个下行连接**，同时使用 **其 station 接口建立一个上行连接**。这将自然产生一个由多层父子结构组成的树型网络拓扑结构。
.. figure:: ../../_static/mesh-tree-topology.png
:align: center
:alt: ESP-MESH 树型拓扑图
:alt: ESP-WIFI-MESH 树型拓扑图
:figclass: align-center
ESP-MESH 树型拓扑
ESP-WIFI-MESH 树型拓扑
ESP-MESH 是一个多跳网络，也就是说网络中的节点可以通过单跳或多跳向网络中的其他节点传送数据包。因此，ESP-MESH 中的节点不仅传输自己的数据包，而且同时充当其他节点的中继。假设 ESP-MESH 网络中的任意两个节点存在物理层上连接（通过单跳或多跳），则这两个节点可以进行通信。
ESP-WIFI-MESH 是一个多跳网络，也就是说网络中的节点可以通过单跳或多跳向网络中的其他节点传送数据包。因此，ESP-WIFI-MESH 中的节点不仅传输自己的数据包，而且同时充当其他节点的中继。假设 ESP-WIFI-MESH 网络中的任意两个节点存在物理层上连接（通过单跳或多跳），则这两个节点可以进行通信。
.. note::
ESP-MESH 网络中的大小（节点总数）取决于网络中允许的最大层级，以及每个节点可以具有的最大下行连接数。因此，这两个变量可用于配置 ESP-MESH 网络的大小。
ESP-WIFI-MESH 网络中的大小（节点总数）取决于网络中允许的最大层级，以及每个节点可以具有的最大下行连接数。因此，这两个变量可用于配置 ESP-WIFI-MESH 网络的大小。
节点类型
^^^^^^^^^^
.. figure:: ../../_static/mesh-node-types.png
:align: center
:alt: ESP-MESH 节点类型图
:alt: ESP-WIFI-MESH 节点类型图
:figclass: align-center
ESP-MESH 节点类型
ESP-WIFI-MESH 节点类型
**根节点**： 指网络顶部的节点，是 ESP-MESH 网络和外部 IP 网络之间的唯一接口。根节点直接连接至传统的 Wi-Fi 路由器，并在 ESP-MESH 网络的节点和外部 IP 网络之间中继数据包。 **ESP-MESH 网络中只能有一个根节点**，且根节点的上行连接只能是路由器。如上图所示，节点 A 即为该 ESP-MESH 网络的根节点。
**根节点**： 指网络顶部的节点，是 ESP-WIFI-MESH 网络和外部 IP 网络之间的唯一接口。根节点直接连接至传统的 Wi-Fi 路由器，并在 ESP-WIFI-MESH 网络的节点和外部 IP 网络之间中继数据包。 **ESP-WIFI-MESH 网络中只能有一个根节点**，且根节点的上行连接只能是路由器。如上图所示，节点 A 即为该 ESP-WIFI-MESH 网络的根节点。
**叶子节点**： 指不允许拥有任何子节点（即无下行连接）的节点。因此，叶子节点只能传输或接收自己的数据包，但不能转发其他节点的数据包。如果节点处于 ESP-MESH 网络的最大允许层级，则该节点将成为叶子节点。叶子节点不回再产生下行连接，这可以防止节点继续生成下行连接，从而确保网络层级不会超出限制。由于建立下行连接必须使用 SoftAP 接口，因此一些没有 SoftAP 接口的节点（仅有 station 接口）也将被分配为叶子节点。如上图所示，位于网络最外层的 L/M/N 节点即为叶子节点。
**叶子节点**： 指不允许拥有任何子节点（即无下行连接）的节点。因此，叶子节点只能传输或接收自己的数据包，但不能转发其他节点的数据包。如果节点处于 ESP-WIFI-MESH 网络的最大允许层级，则该节点将成为叶子节点。叶子节点不回再产生下行连接，这可以防止节点继续生成下行连接，从而确保网络层级不会超出限制。由于建立下行连接必须使用 SoftAP 接口，因此一些没有 SoftAP 接口的节点（仅有 station 接口）也将被分配为叶子节点。如上图所示，位于网络最外层的 L/M/N 节点即为叶子节点。
**中间父节点**：既不是属于根节点也不属于叶子节点的节点即为中间父节点。中间父节点必须有且仅有一个上行连接（即一个父节点），但可以具有 0 个或多个下行连接（即 0 个或多个子节点）。因此，中间父节点可以发送和接收自己的数据包，也可以转发其上行和下行连接的数据包。如上图所示，节点 B 到 J 即为中间父节点。 **注意，E/F/G/I/J 等没有下行连接的中间父节点并不等同于叶子节点**，原因在于这些节点仍允许形成下行连接。
@ -138,7 +138,7 @@ ESP-MESH 是一个多跳网络，也就是说网络中的节点可以通过单
信标帧和 RSSI 阈值
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH 中能够形成下行连接的每个节点（即具有 SoftAP 接口）都会定期传输 Wi-Fi 信标帧。节点可以通过信标帧让其他节点检测自己的存在和状态。空闲节点将侦听信标帧以生成一个潜在父节点列表，并与其中一个潜在父节点形成上行连接。ESP-MESH 使用“供应商信息元素”来存储元数据，例如：
ESP-WIFI-MESH 中能够形成下行连接的每个节点（即具有 SoftAP 接口）都会定期传输 Wi-Fi 信标帧。节点可以通过信标帧让其他节点检测自己的存在和状态。空闲节点将侦听信标帧以生成一个潜在父节点列表，并与其中一个潜在父节点形成上行连接。ESP-WIFI-MESH 使用“供应商信息元素”来存储元数据，例如：
- 节点类型（根节点、中间父节点、叶子节点、空闲节点)
- 节点当前所处的层级
@ -146,7 +146,7 @@ ESP-MESH 中能够形成下行连接的每个节点（即具有 SoftAP 接口）
- 当前子节点数量
- 可接受的最大下行连接数量
潜在上行连接的信号强度可由潜在父节点信标帧的 RSSI 表示。为了防止节点形成弱上行连接，ESP-MESH 采用了针对信标帧的 RSSI 阈值控制机制。如果节点检测到某节点的信标帧 RSSI 过低（即低于预设阈值），则会在尝试形成上行连接时忽略该节点。
潜在上行连接的信号强度可由潜在父节点信标帧的 RSSI 表示。为了防止节点形成弱上行连接，ESP-WIFI-MESH 采用了针对信标帧的 RSSI 阈值控制机制。如果节点检测到某节点的信标帧 RSSI 过低（即低于预设阈值），则会在尝试形成上行连接时忽略该节点。
.. figure:: ../../_static/mesh-beacon-frame-rssi.png
:align: center
@ -160,7 +160,7 @@ ESP-MESH 中能够形成下行连接的每个节点（即具有 SoftAP 接口）
**上图（B 侧）** 展示了 RF 屏蔽物将如何降低潜在父节点的 RSSI。由于存在 RF 屏蔽物，节点 X 的 RSSI 高于阈值的区域显著减小。这会导致空闲节点忽略节点 X，即使从地理位置上看 X 就在空闲节点附近。相反，该空闲节点将从更远的地方找到一个 RSSI 更强的节点 Y 形成上行连接。
.. note::
事实上，ESP-MESH 网络中的节点在 MAC 层仍可以接收所有的信标帧，但 RSSI 阈值控制功能可以过滤掉所有 RSSI 低于预设阈值的信标帧。
事实上，ESP-WIFI-MESH 网络中的节点在 MAC 层仍可以接收所有的信标帧，但 RSSI 阈值控制功能可以过滤掉所有 RSSI 低于预设阈值的信标帧。
首选父节点
^^^^^^^^^^^^^^^^^^^^^
@ -170,7 +170,7 @@ ESP-MESH 中能够形成下行连接的每个节点（即具有 SoftAP 接口）
- 候选父节点所处的层级
- 候选父节点当前具有的下行连接（子节点）数量
在网络中所处层级较浅的候选父节点（包括根节点）将优先成为首选父节点。这有助于在形成上行连接时控制 ESP-MESH 网络中的总层级使之最小。例如，在位于第二层和第三层的候选父节点间选择时，位于第二层的候选父节点将始终优先成为首选父节点。
在网络中所处层级较浅的候选父节点（包括根节点）将优先成为首选父节点。这有助于在形成上行连接时控制 ESP-WIFI-MESH 网络中的总层级使之最小。例如，在位于第二层和第三层的候选父节点间选择时，位于第二层的候选父节点将始终优先成为首选父节点。
如果同一层上存在多个候选父节点，则子节点最少的候选父节点将优先成为首选父节点。这有助于平衡同一层节点的下行连接数量。
@ -191,18 +191,18 @@ ESP-MESH 中能够形成下行连接的每个节点（即具有 SoftAP 接口）
路由表
^^^^^^^^^^^^^^
ESP-MESH 网络中的每个节点均会维护自己的路由表，并按路由表将数据包（请见 `ESP-MESH 数据包`_）沿正确的路线发送至正确的目标节点。某个特定节点的路由表将包含 **该节点的子网中所有节点的 MAC 地址**，也包括该节点自己的 MAC 地址。每个路由表会划分为多个子路由表，与每个子节点的子网对应。
ESP-WIFI-MESH 网络中的每个节点均会维护自己的路由表，并按路由表将数据包（请见 `ESP-WIFI-MESH 数据包`_）沿正确的路线发送至正确的目标节点。某个特定节点的路由表将包含 **该节点的子网中所有节点的 MAC 地址**，也包括该节点自己的 MAC 地址。每个路由表会划分为多个子路由表，与每个子节点的子网对应。
.. figure:: ../../_static/mesh-routing-tables-example.png
:align: center
:alt: ESP-MESH 路由表示例图
:alt: ESP-WIFI-MESH 路由表示例图
:figclass: align-center
ESP-MESH 路由表示例
ESP-WIFI-MESH 路由表示例
以上图为例，节点 B 的路由表中将包含节点 B 到节点 I 的 MAC 地址（即相当于节点 B 的子网）。节点 B 的路由表可划分为节点 C 和 G 的子路由表，分别包含节点 C 到节点 F 的 MAC 地址、节点 G 到节点 I 的 MAC 地址。
**ESP-MESH 利用路由表来使用以下规则进行转发，确定 ESP-MESH 数据包应根据向上行转发还是向下行转发。**
**ESP-WIFI-MESH 利用路由表来使用以下规则进行转发，确定 ESP-WIFI-MESH 数据包应根据向上行转发还是向下行转发。**
**1.** 如果数据包的目标 MAC 地址处于当前节点的路由表中且不是当前节点本身，则选择包含目标 MAC 地址的子路由表，并将数据包向下转发给子路由表对应的子节点。
@ -223,16 +223,16 @@ ESP-MESH 网络中的每个节点均会维护自己的路由表，并按路由
^^^^^^^^^^^^^^^
.. warning::
ESP-MESH 正式开始构建网络前，必须确保网络中所有节点具有相同的配置（见 :cpp:type:`mesh_cfg_t`）。每个节点必须配置 **相同 MESH 网络 ID、路由器配置和 SoftAP 配置**。
ESP-WIFI-MESH 正式开始构建网络前，必须确保网络中所有节点具有相同的配置（见 :cpp:type:`mesh_cfg_t`）。每个节点必须配置 **相同 MESH 网络 ID、路由器配置和 SoftAP 配置**。
ESP-MESH 网络将首先选择根节点，然后逐层形成下行连接，直到所有节点均加入网络。网络的布局可能取决于诸如根节点选择、父节点选择和异步上电复位等因素。但简单来说，一个 ESP-MESH 网络的构建过程可以概括为以下步骤：
ESP-WIFI-MESH 网络将首先选择根节点，然后逐层形成下行连接，直到所有节点均加入网络。网络的布局可能取决于诸如根节点选择、父节点选择和异步上电复位等因素。但简单来说，一个 ESP-WIFI-MESH 网络的构建过程可以概括为以下步骤：
.. figure:: ../../_static/mesh-network-building.png
:align: center
:alt: ESP-MESH 网络构建过程示意图
:alt: ESP-WIFI-MESH 网络构建过程示意图
:figclass: align-center
ESP-MESH 网络构建过程
ESP-WIFI-MESH 网络构建过程
1. 根节点选择
""""""""""""""""""""""
@ -259,7 +259,7 @@ ESP-MESH 网络将首先选择根节点，然后逐层形成下行连接，直
在达到预设迭代次数后，每个节点将单独检查其 **得票百分比** （``得票数/总票数``）以确定它是否应该成为根节点。 **如果节点的得票百分比大于预设的阈值（默认为 90%），则该节点将成为根节点**。
下图展示了在 ESP-MESH 网络中，根节点的自动选择过程。
下图展示了在 ESP-WIFI-MESH 网络中，根节点的自动选择过程。
.. figure:: ../../_static/mesh-root-node-election-example.png
:align: center
@ -280,12 +280,12 @@ ESP-MESH 网络将首先选择根节点，然后逐层形成下行连接，直
用户可以通过 :cpp:func:`esp_mesh_set_attempts` 配置选举的最小迭代次数。用户应根据网络内的节点数量配置迭代次数（即 mesh 网络越大，所需的迭代次数越高）。
.. warning::
**得票百分比阈值** 也可以使用 :cpp:func:`esp_mesh_set_vote_percentage` 进行配置。得票百分比阈值过低 **可能导致同一 mesh 网络中两个或多个节点成为根节点**，进而分化为多个 mesh 网络。如果发生这种情况，ESP-MESH 具有内部机制，可自主解决 **根节点冲突**。这些具有多个根节点的网络将围绕一个根节点形成一个网络。然而，两个或多个路由器 SSID 相同但路由器 BSSID 不同的根节点冲突尚无法解决。
**得票百分比阈值** 也可以使用 :cpp:func:`esp_mesh_set_vote_percentage` 进行配置。得票百分比阈值过低 **可能导致同一 mesh 网络中两个或多个节点成为根节点**，进而分化为多个 mesh 网络。如果发生这种情况，ESP-WIFI-MESH 具有内部机制，可自主解决 **根节点冲突**。这些具有多个根节点的网络将围绕一个根节点形成一个网络。然而，两个或多个路由器 SSID 相同但路由器 BSSID 不同的根节点冲突尚无法解决。
用户指定根节点
^^^^^^^^^^^^^^^^^^^^^^^^^
根节点也可以由用户指定，即直接让指定的根节点与路由器连接，并放弃选举过程。当根节点指定后，网络内的所有其他节点也必须放弃选举过程，以防止根节点冲突的发生。下图展示了在 ESP-MESH 网络中，根节点的手动选择过程。
根节点也可以由用户指定，即直接让指定的根节点与路由器连接，并放弃选举过程。当根节点指定后，网络内的所有其他节点也必须放弃选举过程，以防止根节点冲突的发生。下图展示了在 ESP-WIFI-MESH 网络中，根节点的手动选择过程。
.. figure:: ../../_static/mesh-root-node-designated-example.png
:align: center
@ -308,14 +308,14 @@ ESP-MESH 网络将首先选择根节点，然后逐层形成下行连接，直
选择父节点
^^^^^^^^^^^^^^^^^^^^^
默认情况下，ESP-MESH 具有可以自组网的特点，也就是每个节点都可以自主选择与其形成上行连接的潜在父节点。自主选择出的父节点被称为首选父节点。用于选择首选父节点的标准旨在减少 ESP-MESH 网络的层级，并平衡各个潜在父节点的下行连接数（参见 `首选父节点`_）。
默认情况下，ESP-WIFI-MESH 具有可以自组网的特点，也就是每个节点都可以自主选择与其形成上行连接的潜在父节点。自主选择出的父节点被称为首选父节点。用于选择首选父节点的标准旨在减少 ESP-WIFI-MESH 网络的层级，并平衡各个潜在父节点的下行连接数（参见 `首选父节点`_）。
不过，ESP-MESH 也允许用户禁用自组网功能，即允许用户自己定义父节点选择标准，或直接指定某个节点为父节点（见： :example:`Mesh 手动组网示例 <mesh/manual_networking>`）。
不过，ESP-WIFI-MESH 也允许用户禁用自组网功能，即允许用户自己定义父节点选择标准，或直接指定某个节点为父节点（见： :example:`Mesh 手动组网示例 <mesh/manual_networking>`）。
异步上电复位
^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH 网络构建可能会受到节点上电顺序的影响。如果网络中的某些节点为异步上电（即相隔几分钟上电），**网络的最终结构可能与所有节点同步上电时的理想情况不同**。延迟上电的节点将遵循以下规则：
ESP-WIFI-MESH 网络构建可能会受到节点上电顺序的影响。如果网络中的某些节点为异步上电（即相隔几分钟上电），**网络的最终结构可能与所有节点同步上电时的理想情况不同**。延迟上电的节点将遵循以下规则：
**规则 1**：如果网络中已存在根节点，则延迟节点不会尝试选举成为新的根节点，即使自身的路由器 RSSI 更强。相反，延迟节点与任何其他空闲节点无异，将通过与首选父节点连接来加入网络。如果该延迟节点为用户指定的根节点，则网络中的所有其他节点将保持空闲状态，直到延迟节点完成上电。
@ -343,14 +343,14 @@ ESP-MESH 网络构建可能会受到节点上电顺序的影响。如果网络
**同步上电**：如果所有节点均同步上电，节点 E （-10 dB）由于路由器 RSSI 最强而成为根节点。此时形成的网络结构将与异步上电的情况截然不同。**但是，如果用户手动切换根节点，则仍可以达到同步上电的网络结构** （请见 :cpp:func:`esp_mesh_waive_root`）。
.. note::
从某种程度上，ESP-MESH 可以自动修复部分因异步上电引起的父节点选择的偏差（请见 `父节点切换`_)
从某种程度上，ESP-WIFI-MESH 可以自动修复部分因异步上电引起的父节点选择的偏差（请见 `父节点切换`_)
环路避免、检测和处理
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
环路是指特定节点与其后代节点（特定节点子网中的节点）形成上行连接的情况。因此产生的循环连接路径将打破 mesh 网络的树型拓扑结构。ESP-MESH 的节点在选择父节点时将主动排除路由表（见 `路由表`_）中的节点，从而避免与其子网中的节点建立上行连接并形成环路。
环路是指特定节点与其后代节点（特定节点子网中的节点）形成上行连接的情况。因此产生的循环连接路径将打破 mesh 网络的树型拓扑结构。ESP-WIFI-MESH 的节点在选择父节点时将主动排除路由表（见 `路由表`_）中的节点，从而避免与其子网中的节点建立上行连接并形成环路。
在存在环路的情况下，ESP-MESH 可利用路径验证机制和能量传递机制来检测环路的产生。因与子节点建立上行连接而导致环路形成的父节点将通知子节点环路的存在，并主动断开连接。
在存在环路的情况下，ESP-WIFI-MESH 可利用路径验证机制和能量传递机制来检测环路的产生。因与子节点建立上行连接而导致环路形成的父节点将通知子节点环路的存在，并主动断开连接。
.. --------------------------管理网络 ------------------------------
@ -359,7 +359,7 @@ ESP-MESH 网络构建可能会受到节点上电顺序的影响。如果网络
管理网络
------------------
**作为一个自修复网络，ESP-MESH 可以检测并修正网络路由中的故障**。当具有一个或多个子节点的父节点断开或父节点与其子节点之间的连接不稳定时，会发生故障。ESP-MESH 中的子节点将自主选择一个新的父节点，并与其形成上行连接，以维持网络互连。ESP-MESH 可以处理根节点故障和中间父节点故障。
**作为一个自修复网络，ESP-WIFI-MESH 可以检测并修正网络路由中的故障**。当具有一个或多个子节点的父节点断开或父节点与其子节点之间的连接不稳定时，会发生故障。ESP-WIFI-MESH 中的子节点将自主选择一个新的父节点，并与其形成上行连接，以维持网络互连。ESP-WIFI-MESH 可以处理根节点故障和中间父节点故障。
根节点故障
^^^^^^^^^^^^^^^^^
@ -412,7 +412,7 @@ ESP-MESH 网络构建可能会受到节点上电顺序的影响。如果网络
根节点切换
^^^^^^^^^^^^^^^^^^^
除非根节点断开，否则 ESP-MESH 不会自动切换根节点。即使根节点的路由器 RSSI 降低至必须断开的情况，根节点也将保持不变。根节点切换是指明确启动新选举过程的行为，即具有更强路由器 RSSI 的节点选为新的根节点。这可以用于应对根节点性能降低的情况。
除非根节点断开，否则 ESP-WIFI-MESH 不会自动切换根节点。即使根节点的路由器 RSSI 降低至必须断开的情况，根节点也将保持不变。根节点切换是指明确启动新选举过程的行为，即具有更强路由器 RSSI 的节点选为新的根节点。这可以用于应对根节点性能降低的情况。
要触发根节点切换，当前根节点必须明确调用 :cpp:func:`esp_mesh_waive_root` 以触发新的选举。当下根节点将指示网络中的所有节点开始发送并扫描信标帧（见 `自动根节点选择`_），**但与此同时一直保持联网（即不会变为空闲节点）**。如果另一个节点收到的票数超过当前根节点，则将启动根节点切换过程，**否则根节点将保持不变**。
@ -436,14 +436,14 @@ ESP-MESH 网络构建可能会受到节点上电顺序的影响。如果网络
**4.** 节点 C 选择节点 B 作为其的首选父节点，与之形成上行连接，并成为一个第二层节点。由于节点 C 仍保持相同的子网，因此根节点切换后的网络结构没有变化。然后，由于切换的发生，节点 C 子网中每个节点的所处层级均增加了一层。如果根节点切换过程中产生了新的根节点，则 `父节点切换`_ 可以随后调整网络结构。
.. note::
根节点切换必须要求选举，因此只有在使用自组网 ESP-MESH 网络时才支持。换句话说，如果使用指定的根节点，则不能进行根节点切换。
根节点切换必须要求选举，因此只有在使用自组网 ESP-WIFI-MESH 网络时才支持。换句话说，如果使用指定的根节点，则不能进行根节点切换。
父节点切换
^^^^^^^^^^^^^^^^^^^^^
父节点切换是指一个子节点将其上行连接切换到更浅一层的另一个父节点。**父节点切换是自动的**，这意味着如果较浅层出现了可用的潜在父节点（因“异步上电复位”产生），子节点将自动更改其上行连接。
所有潜在的父节点将定期发送信标帧（参见 `信标帧和 RSSI 阈值`_），从而允许子节点扫描较浅层的父节点的可用性。由于父节点切换，自组网 ESP-MESH 网络可以动态调整其网络结构，以确保每个连接均具有良好的 RSSI 值，并且网络中的层级最小。
所有潜在的父节点将定期发送信标帧（参见 `信标帧和 RSSI 阈值`_），从而允许子节点扫描较浅层的父节点的可用性。由于父节点切换，自组网 ESP-WIFI-MESH 网络可以动态调整其网络结构，以确保每个连接均具有良好的 RSSI 值，并且网络中的层级最小。
.. ---------------------------数据传输 ------------------------------
@ -453,43 +453,43 @@ ESP-MESH 网络构建可能会受到节点上电顺序的影响。如果网络
数据传输
-----------------
ESP-MESH 数据包
^^^^^^^^^^^^^^^
ESP-WIFI-MESH 数据包
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH 网络使用 ESP-MESH 数据包传输数据。ESP-MESH 数据包 **完全包含在 Wi-Fi 数据帧** 中。ESP-MESH 网络中的多跳数据传输将涉及通过不同 Wi-Fi 数据帧在每个无线跳上传输的单个 ESP-MESH 数据包。
ESP-WIFI-MESH 网络使用 ESP-WIFI-MESH 数据包传输数据。ESP-WIFI-MESH 数据包 **完全包含在 Wi-Fi 数据帧** 中。ESP-WIFI-MESH 网络中的多跳数据传输将涉及通过不同 Wi-Fi 数据帧在每个无线跳上传输的单个 ESP-WIFI-MESH 数据包。
下图显示了 ESP-MESH 数据包的结构及其与 Wi-Fi 数据帧的关系。
下图显示了 ESP-WIFI-MESH 数据包的结构及其与 Wi-Fi 数据帧的关系。
.. figure:: ../../_static/mesh-packet.png
:align: center
:alt: ESP-MESH 数据包示意图
:alt: ESP-WIFI-MESH 数据包示意图
:figclass: align-center
ESP-MESH 数据包
ESP-WIFI-MESH 数据包
ESP-MESH 数据包的 **报头** 包含源节点和目标节点的 MAC 地址。**选项 (option)** 字段包含有关特殊类型 ESP-MESH 数据包的信息，例如组传输或来自外部 IP 网络的数据包（请参阅 :c:macro:`MESH_OPT_SEND_GROUP` 和 :c:macro:`MESH_OPT_RECV_DS_ADDR`）。
ESP-WIFI-MESH 数据包的 **报头** 包含源节点和目标节点的 MAC 地址。**选项 (option)** 字段包含有关特殊类型 ESP-WIFI-MESH 数据包的信息，例如组传输或来自外部 IP 网络的数据包（请参阅 :c:macro:`MESH_OPT_SEND_GROUP` 和 :c:macro:`MESH_OPT_RECV_DS_ADDR`）。
ESP-MESH 数据包的 **有效载荷** 包含实际的应用数据。该数据可以为原始二进制数据，也可以是使用 HTTP、MQTT 和 JSON 等应用层协议的编码数据（请见：:cpp:type:`mesh_proto_t`）。
ESP-WIFI-MESH 数据包的 **有效载荷** 包含实际的应用数据。该数据可以为原始二进制数据，也可以是使用 HTTP、MQTT 和 JSON 等应用层协议的编码数据（请见：:cpp:type:`mesh_proto_t`）。
.. note::
当向外部 IP 网络发送 ESP-MESH 数据包时，报头的目标地址字段将包含目标服务器的 IP 地址和端口号，而不是节点的 MAC 地址（请见：:cpp:type:`mesh_addr_t`）。此外，根节点将处理外发 TCP/IP 数据包的形成。
当向外部 IP 网络发送 ESP-WIFI-MESH 数据包时，报头的目标地址字段将包含目标服务器的 IP 地址和端口号，而不是节点的 MAC 地址（请见：:cpp:type:`mesh_addr_t`）。此外，根节点将处理外发 TCP/IP 数据包的形成。
组控制和组播
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
组播功能允许将单个 ESP-MESH 数据包同时发送给网络中的多个节点。ESP-MESH 中的组播可以通过“指定一个目标节点列表”或“预配置一个节点组”来实现。这两种组播方式均需调用 :cpp:func:`esp_mesh_send` 实现。
组播功能允许将单个 ESP-WIFI-MESH 数据包同时发送给网络中的多个节点。ESP-WIFI-MESH 中的组播可以通过“指定一个目标节点列表”或“预配置一个节点组”来实现。这两种组播方式均需调用 :cpp:func:`esp_mesh_send` 实现。
如果通过“指定目标节点列表”实现组播，用户必须首先将 ESP-MESH 数据包的目标地址设置为 **组播组地址** （比如 ``01:00:5E:xx:xx:xx``）。这表明 ESP-MESH 数据包是一个拥有一组地址的组播数据包，且该地址应该从报头选项中获得。然后，用户必须将目标节点的 MAC 地址列为选项（请见： :cpp:type:`mesh_opt_t` 和 :c:macro:`MESH_OPT_SEND_GROUP`）。这种组播方法不需要进行提前设置，但由于每个目标节点的 MAC 地址均需列为报头的选项字段，因此会产生大量开销数据。
如果通过“指定目标节点列表”实现组播，用户必须首先将 ESP-WIFI-MESH 数据包的目标地址设置为 **组播组地址** （比如 ``01:00:5E:xx:xx:xx``）。这表明 ESP-WIFI-MESH 数据包是一个拥有一组地址的组播数据包，且该地址应该从报头选项中获得。然后，用户必须将目标节点的 MAC 地址列为选项（请见： :cpp:type:`mesh_opt_t` 和 :c:macro:`MESH_OPT_SEND_GROUP`）。这种组播方法不需要进行提前设置，但由于每个目标节点的 MAC 地址均需列为报头的选项字段，因此会产生大量开销数据。
分组组播允许 ESP-MESH 数据包被发送到一个预先配置的节点组。每个分组都有一个具有唯一性的 ID 标识。用户可通过 :cpp:func:`esp_mesh_set_group_id` 将节点加入一个组。分组组播需要将 ESP-MESH 数据包的目标地址设置为目标组的 ID，还必须设置 :c:macro:`MESH_DATA_GROUP` 标志位。分组组播产生的开销更小，但必须提前将节点加入分组中。
分组组播允许 ESP-WIFI-MESH 数据包被发送到一个预先配置的节点组。每个分组都有一个具有唯一性的 ID 标识。用户可通过 :cpp:func:`esp_mesh_set_group_id` 将节点加入一个组。分组组播需要将 ESP-WIFI-MESH 数据包的目标地址设置为目标组的 ID，还必须设置 :c:macro:`MESH_DATA_GROUP` 标志位。分组组播产生的开销更小，但必须提前将节点加入分组中。
.. note::
在组播期间，网络中的所有节点在 MAC 层都会收到 ESP-MESH 数据包。然而，不包括在 MAC 地址列表或目标组中的节点将简单地过滤掉这些数据包。
在组播期间，网络中的所有节点在 MAC 层都会收到 ESP-WIFI-MESH 数据包。然而，不包括在 MAC 地址列表或目标组中的节点将简单地过滤掉这些数据包。
广播
^^^^^^^^^^^^
广播功能允许将单个 ESP-MESH 数据包同时发送给网络中的所有节点。每个节点可以将一个广播包转发至其所有上行和下行连接，使得数据包尽可能快地在整个网络中传播。但是，ESP-MESH 利用以下方法来避免在广播期间浪费带宽。
广播功能允许将单个 ESP-WIFI-MESH 数据包同时发送给网络中的所有节点。每个节点可以将一个广播包转发至其所有上行和下行连接，使得数据包尽可能快地在整个网络中传播。但是，ESP-WIFI-MESH 利用以下方法来避免在广播期间浪费带宽。
**1.** 当中间父节点收到来自其父节点的广播包时，它会将该数据包转发给自己的各个子节点，同时为自己保存一份数据包的副本。
@ -510,7 +510,7 @@ ESP-MESH 数据包的 **有效载荷** 包含实际的应用数据。该数据
上行流量控制
^^^^^^^^^^^^^^^^^^^^^
ESP-MESH 依赖父节点来控制其直接子节点的上行数据流。为了防止父节点的消息缓冲因上行传输过载而溢出，父节点将为每个子节点分配一个称为 **接收窗口** 的上行传输配额。 **每个子节点均必须申请接收窗口才允许进行上行传输**。接收窗口的大小可以动态调整。完成从子节点到父节点的上行传输包括以下步骤：
ESP-WIFI-MESH 依赖父节点来控制其直接子节点的上行数据流。为了防止父节点的消息缓冲因上行传输过载而溢出，父节点将为每个子节点分配一个称为 **接收窗口** 的上行传输配额。 **每个子节点均必须申请接收窗口才允许进行上行传输**。接收窗口的大小可以动态调整。完成从子节点到父节点的上行传输包括以下步骤：
**1.** 在每次传输之前，子节点向其父节点发送窗口请求。窗口请求中包括一个序号，与子节点的待传输数据包相对应。
@ -519,26 +519,26 @@ ESP-MESH 依赖父节点来控制其直接子节点的上行数据流。为了
**3.** 子节点根据父节点指定的窗口大小发送数据包。如果子节点的接收窗口耗尽，它必须通过发送请求获得另一个接收窗口，然后才允许继续发送。
.. note::
ESP-MESH 不支持任何下行流量控制。
ESP-WIFI-MESH 不支持任何下行流量控制。
.. warning::
由于 `父节点切换`_，数据包可能会在上行传输期间丢失。
由于根节点是通向外部 IP 网络的唯一接口，因此下行节点必须了解根节点与外部 IP 网络的连接状态。否则，节点可能会尝试向一个已经与 IP 网络断开连接的根节点发送数据，从而造成不必要的传输和数据包丢失。ESP-MESH 可以基于监测根节点和外部 IP 网络的连接状态，提供一种稳定外发数据吞吐量的机制。根节点可以通过调用 :cpp:func:`esp_mesh_post_toDS_state` 将自身与外部 IP 网络的连接状态广播给所有其他节点。
由于根节点是通向外部 IP 网络的唯一接口，因此下行节点必须了解根节点与外部 IP 网络的连接状态。否则，节点可能会尝试向一个已经与 IP 网络断开连接的根节点发送数据，从而造成不必要的传输和数据包丢失。ESP-WIFI-MESH 可以基于监测根节点和外部 IP 网络的连接状态，提供一种稳定外发数据吞吐量的机制。根节点可以通过调用 :cpp:func:`esp_mesh_post_toDS_state` 将自身与外部 IP 网络的连接状态广播给所有其他节点。
双向数据流
^^^^^^^^^^^^^^^^^^^^^^^^^^
下图展示了 ESP-MESH 双向数据流涉及的各种网络层。
下图展示了 ESP-WIFI-MESH 双向数据流涉及的各种网络层。
.. figure:: ../../_static/mesh-bidirectional-data-stream.png
:align: center
:alt: ESP-MESH 双向数据流示意图
:alt: ESP-WIFI-MESH 双向数据流示意图
:figclass: align-center
ESP-MESH双向数据流
ESP-WIFI-MESH 双向数据流
由于使用 `路由表`_，**ESP-MESH 能够在 mesh 层中完全处理数据包的转发**。TCP/IP 层仅与 mesh 网络的根节点有关，可帮助根节点与外部 IP 网络的数据包传送。
由于使用 `路由表`_，**ESP-WIFI-MESH 能够在 mesh 层中完全处理数据包的转发**。TCP/IP 层仅与 mesh 网络的根节点有关，可帮助根节点与外部 IP 网络的数据包传送。
.. ---------------------------信道切换 -------------------------------
@ -559,60 +559,60 @@ ESP-MESH 依赖父节点来控制其直接子节点的上行数据流。为了
一个 CSA 元素包含有关 **新信道号** 和 **信道切换计数** 的信息。其中，**信道切换计数** 指示在网络信道切换之前剩余的信标帧间隔 (TBTT) 数量。因此，**信道切换计数** 依每个信标帧递减，并且允许与之连接的 station 与 AP 同步进行信道切换。
ESP-MESH 网络信道切换
ESP-WIFI-MESH 网络信道切换
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH 网络信道切换还利用包含 CSA 元素的信标帧。然而，ESP-MESH 作为一个多跳网络，其信标帧可能无法到达网络中的所有节点（这点与单跳网络不同），因此信道切换过程更加复杂。因此，ESP-MESH 网络依赖于通过节点转发 CSA 元素，从而实现在整个网络中的传播。
ESP-WIFI-MESH 网络信道切换还利用包含 CSA 元素的信标帧。然而，ESP-WIFI-MESH 作为一个多跳网络，其信标帧可能无法到达网络中的所有节点（这点与单跳网络不同），因此信道切换过程更加复杂。因此，ESP-WIFI-MESH 网络依赖于通过节点转发 CSA 元素，从而实现在整个网络中的传播。
当具有一个或多个子节点的中间父节点接收到包含 CSA 元素的信标帧时，该节点会将该元素包含在其下一个发送的信标帧（即具有相同的 **新信道号** 和 **信道切换计数**）中，从而实现该 CSA 元素的转发。鉴于 ESP-MESH 网络中的所有节点都接收到相同的 CSA 元素，这些节点可以使用 **信道切换计数** 来同步其信道切换，但也会经历因 CSA 元素转发造成的延迟。
当具有一个或多个子节点的中间父节点接收到包含 CSA 元素的信标帧时，该节点会将该元素包含在其下一个发送的信标帧（即具有相同的 **新信道号** 和 **信道切换计数**）中，从而实现该 CSA 元素的转发。鉴于 ESP-WIFI-MESH 网络中的所有节点都接收到相同的 CSA 元素，这些节点可以使用 **信道切换计数** 来同步其信道切换，但也会经历因 CSA 元素转发造成的延迟。
ESP-MESH 网络信道切换可以由路由器或根节点触发。
ESP-WIFI-MESH 网络信道切换可以由路由器或根节点触发。
根节点触发
"""""""""""""""""""
**由根节点触发的信道切换只能在 ESP-MESH 网络未连接到路由器** 时才会发生。通过调用 :cpp:func:`esp_mesh_switch_channel`，根节点将设置一个初始 **信道切换计数** 值，并开始在其信标帧中包含 CSA 元素。接着，每个 CSA 元素将抵达第二层节点，并通过第二层节点自己的信标帧继续进行向下转发。
**由根节点触发的信道切换只能在 ESP-WIFI-MESH 网络未连接到路由器** 时才会发生。通过调用 :cpp:func:`esp_mesh_switch_channel`，根节点将设置一个初始 **信道切换计数** 值，并开始在其信标帧中包含 CSA 元素。接着，每个 CSA 元素将抵达第二层节点，并通过第二层节点自己的信标帧继续进行向下转发。
路由器触发
""""""""""""""""
当 ESP-MESH 网络连接到路由器时，整个网络必须与路由器采用同一个信道。因此，**根节点在连接到路由器时无法触发信道切换**。
当 ESP-WIFI-MESH 网络连接到路由器时，整个网络必须与路由器采用同一个信道。因此，**根节点在连接到路由器时无法触发信道切换**。
当根节点从路由器接收到包含 CSA 元素的信标帧时，**根节点将 CSA 元素中的信道切换计数值设置为自定义值，然后再通过信标帧继续向下转发**。此后，该 **信道切换计数** 将依转发次数相对于自定义值依次递减。该自定义值可以基于诸如网络层级、当前节点数等因素。
ESP-MESH 网络及其路由器可能具有不同且变化的信标间隔，因此需要将 **信道切换计数** 值设置为自定义值。也就是说，路由器提供的 **信道切换计数** 值与 ESP-MESH 网络无关。通过使用自定义值，ESP-MESH 网络中的节点能够相对于 ESP-MESH 网络的信标间隔同步切换信道。也正因如此，ESP-MESH 网络也会出现信道与路由器及其连接 station 的信道切换不同步的情况。
ESP-WIFI-MESH 网络及其路由器可能具有不同且变化的信标间隔，因此需要将 **信道切换计数** 值设置为自定义值。也就是说，路由器提供的 **信道切换计数** 值与 ESP-WIFI-MESH 网络无关。通过使用自定义值，ESP-WIFI-MESH 网络中的节点能够相对于 ESP-WIFI-MESH 网络的信标间隔同步切换信道。也正因如此，ESP-WIFI-MESH 网络也会出现信道与路由器及其连接 station 的信道切换不同步的情况。
网络信道切换的影响
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- 由于 ESP-MESH 网络信道切换与路由器的信道切换不同步，ESP-MESH 网络和路由器之间会出现 **临时信道差异**。
- ESP-MESH 网络的信道切换时间取决于 ESP-MESH 网络的信标间隔和根节点的自定义 **信道切换计数**。
- 在 ESP-MESH 网络切换期间，信道差异将阻止根节点和路由器之间的任何数据交换。
- 在 ESP-MESH 网络中，根节点和中间父节点将请求与其连接的子节点停止传输，直至信道切换发生（通过将 CSA 元素的 **信道切换模式** 字段置为 1）。
- 频繁的路由器触发网络信道切换可能会降低 ESP-MESH 网络的性能。请注意，这可能是由 ESP-MESH 网络本身造成的（例如由于 ESP-MESH 网络的无线介质争用等原因）。此时，用户应该禁用路由器触发的自主信道切换，并直接指定一个信道。
- 由于 ESP-WIFI-MESH 网络信道切换与路由器的信道切换不同步，ESP-WIFI-MESH 网络和路由器之间会出现 **临时信道差异**。
- ESP-WIFI-MESH 网络的信道切换时间取决于 ESP-WIFI-MESH 网络的信标间隔和根节点的自定义 **信道切换计数**。
- 在 ESP-WIFI-MESH 网络切换期间，信道差异将阻止根节点和路由器之间的任何数据交换。
- 在 ESP-WIFI-MESH 网络中，根节点和中间父节点将请求与其连接的子节点停止传输，直至信道切换发生（通过将 CSA 元素的 **信道切换模式** 字段置为 1）。
- 频繁的路由器触发网络信道切换可能会降低 ESP-WIFI-MESH 网络的性能。请注意，这可能是由 ESP-WIFI-MESH 网络本身造成的（例如由于 ESP-WIFI-MESH 网络的无线介质争用等原因）。此时，用户应该禁用路由器触发的自主信道切换，并直接指定一个信道。
- 当存在 **临时信道差异** 时，根节点从技术上来说仍保持连接至路由器。
- 如果根节点经过一定数量信标间隔仍无法接到信标帧或探测来自路由器的响应，则会断开连接。
- 断开连接时，根节点将自动重新扫描所有信道以确定是否存在路由器。
- 如果根节点无法接收任何路由器的 CSA 信标帧（例如短暂的路由器切换时间），则路由器将在没有 ESP-MESH 网络的情况下切换信道。
- 如果根节点无法接收任何路由器的 CSA 信标帧（例如短暂的路由器切换时间），则路由器将在没有 ESP-WIFI-MESH 网络的情况下切换信道。
- 在路由器切换信道后，根节点将不再能够接收路由器的信标帧和探测响应，并导致在一定数量的信标间隔后断开连接。
- 在断开连接后，根节点将重新所有信道，寻找路由器。
- 根节点将在整个过程中维护与之相连的下行连接。
.. note::
虽然 ESP-MESH 网络信道切换的目的是将网络内的所有节点移动到新的工作信道，但也应该认识到，信道切换可能无法成功移动所有节点（比如由于节点故障等原因）。
虽然 ESP-WIFI-MESH 网络信道切换的目的是将网络内的所有节点移动到新的工作信道，但也应该认识到，信道切换可能无法成功移动所有节点（比如由于节点故障等原因）。
信道和路由器切换配置
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ESP-MESH 允许通过配置启用或禁用自主信道切换。同样，也可以通过配置启用或禁用自主路由器切换（即当根节点自主连接到另一个路由器时）。自主信道切换和自主路由器切换取决于以下配置参数和运行时间条件。
ESP-WIFI-MESH 允许通过配置启用或禁用自主信道切换。同样，也可以通过配置启用或禁用自主路由器切换（即当根节点自主连接到另一个路由器时）。自主信道切换和自主路由器切换取决于以下配置参数和运行时间条件。
**允许信道切换**：本参数决定是否允许 ESP-MESH 网络进行自主信道切换，具体可通过 :cpp:type:`mesh_cfg_t` 结构体中的 ``allow_channel_switch`` 字段进行配置。
**允许信道切换**：本参数决定是否允许 ESP-WIFI-MESH 网络进行自主信道切换，具体可通过 :cpp:type:`mesh_cfg_t` 结构体中的 ``allow_channel_switch`` 字段进行配置。
**预设信道**：ESP-MESH 网络可以将 :cpp:type:`mesh_cfg_t` 结构体中的 ``channel`` 字段设置为相应的信道号，而具备一个预设信道。如果未设置此字段，则 ``allow_channel_switch`` 的设置将被覆盖，即始终允许信道切换。
**预设信道**：ESP-WIFI-MESH 网络可以将 :cpp:type:`mesh_cfg_t` 结构体中的 ``channel`` 字段设置为相应的信道号，而具备一个预设信道。如果未设置此字段，则 ``allow_channel_switch`` 的设置将被覆盖，即始终允许信道切换。
**允许路由器切换**：本参数决定是否允许 ESP-MESH 网络进行自主路由器切换，具体可通过 :cpp:type:`mesh_router_t` 结构体中的 ``allow_router_switch`` 字段进行配置。
**允许路由器切换**：本参数决定是否允许 ESP-WIFI-MESH 网络进行自主路由器切换，具体可通过 :cpp:type:`mesh_router_t` 结构体中的 ``allow_router_switch`` 字段进行配置。
**预设路由器 BSSID**：ESP-MESH 网络可以将 :cpp:type:`mesh_router_t` 结构体的 ``bssid`` 字段设置为
**预设路由器 BSSID**：ESP-WIFI-MESH 网络可以将 :cpp:type:`mesh_router_t` 结构体的 ``bssid`` 字段设置为
目标路由器的 BSSID，而预设一个路由器。如果未设置此字段，则 ``allow_router_switch`` 的设置将被覆盖，即始终允许路由器切换。
**存在根节点**：根节点的存在也会影响是否允许信道或路由器切换。
@ -701,6 +701,7 @@ ESP-MESH 允许通过配置启用或禁用自主信道切换。同样，也可
- Y
- Y
- 信道与路由器
.. ------------------------------性能 ---------------------------------
.. _mesh-network-performance:
@ -708,17 +709,17 @@ ESP-MESH 允许通过配置启用或禁用自主信道切换。同样，也可
性能
-----------
ESP-MESH 网络的性能可以基于以下多个指标进行评估：
ESP-WIFI-MESH 网络的性能可以基于以下多个指标进行评估：
**组网时长**：从头开始构建 ESP-MESH 网络所需的总时长。
**组网时长**：从头开始构建 ESP-WIFI-MESH 网络所需的总时长。
**修复时间**：从网络检测到节点断开到执行适当操作（例如生成新的根节点或形成新的连接等）以修复网络所需的时间。
**每跳延迟**：数据每经过一次无线 hop 而经历的延迟，即从父节点向子节点（或从子节点向父节点）发送一个数据包所需的时间。
**网络节点容量**：ESP-MESH 网络可以同时支持的节点总数。该指标取决于节点可以接受到的最大下行连接数和网络中允许的最大层级。
**网络节点容量**：ESP-WIFI-MESH 网络可以同时支持的节点总数。该指标取决于节点可以接受到的最大下行连接数和网络中允许的最大层级。
ESP-MESH 网络的常见性能指标如下表所示：
ESP-WIFI-MESH 网络的常见性能指标如下表所示：
* 组网时长：< 60 秒
* 修复时间
@ -737,10 +738,10 @@ ESP-MESH 网络的常见性能指标如下表所示：
吞吐量取决于数据包错误率和 hop 数量。
.. note::
根节点访问外部 IP 网络的吞吐量直接受到 ESP-MESH 网络中节点数量和路由器带宽的影响。
根节点访问外部 IP 网络的吞吐量直接受到 ESP-WIFI-MESH 网络中节点数量和路由器带宽的影响。
.. note::
用户应注意，ESP-MESH 网络的性能与网络配置和工作环境密切相关。
用户应注意，ESP-WIFI-MESH 网络的性能与网络配置和工作环境密切相关。
.. -----------------------------更多注意事项 --------------------------------
@ -755,4 +756,3 @@ ESP-MESH 网络的常见性能指标如下表所示：
本文图片中使用的路由器与互联网图标来自 `www.flaticon.com <https://smashicons.com>`_ 的 `Smashicons <https://smashicons.com>`_。

2
docs/zh_CN/api-guides/index.rst
View File

@ -15,7 +15,7 @@ API 指南
:esp32s2: 通过 USB 升级设备固件 <dfu>
错误处理 <error-handling>
:SOC_BT_SUPPORTED: ESP-BLE-MESH <esp-ble-mesh/ble-mesh-index>
ESP-MESH (Wi-Fi) <mesh>
ESP-WIFI-MESH <esp-wifi-mesh>
核心转储 <core_dump>
事件处理 <event-handling>
:SOC_SPIRAM_SUPPORTED: 片外 SPI RAM <external-ram>

116
docs/zh_CN/api-reference/network/esp_mesh.rst → docs/zh_CN/api-reference/network/esp-wifi-mesh.rst
View File

@ -1,9 +1,9 @@
ESP-MESH 编程指南
ESP-WIFI-MESH 编程指南
==========================
:link_to_translation:`en:[English]`
这是 ESP-MESH 的编程指南，包括 API 参考和编码示例。本指南分为以下部分：
这是 ESP-WIFI-MESH 的编程指南，包括 API 参考和编码示例。本指南分为以下部分：
1. :ref:`mesh-programming-model`
@ -15,62 +15,62 @@ ESP-MESH 编程指南
5. :ref:`mesh-api-reference`
有关 ESP-MESH 协议的文档，请见 :doc:`ESP-MESH API 指南 <../../api-guides/mesh>`。有关 ESP-MESH 开发框架的更多内容，请见 `ESP-MESH 开发框架 <https://github.com/espressif/esp-mdf>`_。
有关 ESP-WIFI-MESH 协议的文档，请见 :doc:`ESP-WIFI-MESH API 指南 <../../api-guides/esp-wifi-mesh>`。有关 ESP-WIFI-MESH 开发框架的更多内容，请见 `ESP-WIFI-MESH 开发框架 <https://github.com/espressif/esp-mdf>`_。
.. ----------------------ESP-MESH 编程模型 --------------------------
.. ----------------------ESP-WIFI-MESH 编程模型 --------------------------
.. _mesh-programming-model:
ESP-MESH 编程模型
ESP-WIFI-MESH 编程模型
--------------------------
软件栈
^^^^^^^^^^^^^^
ESP-MESH 软件栈基于 Wi-Fi 驱动程序和 FreeRTOS 构建，某些情况下（如根节点）也会使用 LwIP 软件栈。下图展示了 ESP-MESH 软件栈。
ESP-WIFI-MESH 软件栈基于 Wi-Fi 驱动程序和 FreeRTOS 构建，某些情况下（如根节点）也会使用 LwIP 软件栈。下图展示了 ESP-WIFI-MESH 软件栈。
.. _mesh-going-to-software-stack:
.. figure:: ../../../_static/mesh-software-stack.png
:align: center
:alt: ESP-MESH 软件栈
:alt: ESP-WIFI-MESH 软件栈
:figclass: align-center
ESP-MESH 软件栈
ESP-WIFI-MESH 软件栈
.. _mesh-events:
系统事件
^^^^^^^^^^^^^
应用程序可通过 **ESP-MESH 事件** 与 ESP-MESH 交互。由于 ESP-MESH 构建在 Wi-Fi 软件栈之上，因此也可以通过 **Wi-Fi 事件任务** 与 Wi-Fi 驱动程序进行交互。下图展示了 ESP-MESH 应用程序中各种系统事件的接口。
应用程序可通过 **ESP-WIFI-MESH 事件** 与 ESP-WIFI-MESH 交互。由于 ESP-WIFI-MESH 构建在 Wi-Fi 软件栈之上，因此也可以通过 **Wi-Fi 事件任务** 与 Wi-Fi 驱动程序进行交互。下图展示了 ESP-WIFI-MESH 应用程序中各种系统事件的接口。
.. figure:: ../../../_static/mesh-events-delivery.png
:align: center
:alt: ESP-MESH 系统事件交付
:alt: ESP-WIFI-MESH 系统事件交付
:figclass: align-center
ESP-MESH 系统事件交付
ESP-WIFI-MESH 系统事件交付
:cpp:type:`mesh_event_id_t` 定义了所有可能的 ESP-MESH 事件，并且可以指示父节点和子节点的连接或断开等事件。应用程序如需使用 ESP-MESH 事件，则必须通过 :cpp:func:`esp_event_handler_register` 将 **Mesh 事件处理程序** 注册在默认事件任务中。注册完成后，ESP-MESH 事件将包含与应用程序所有相关事件相关的处理程序。
:cpp:type:`mesh_event_id_t` 定义了所有可能的 ESP-WIFI-MESH 事件，并且可以指示父节点和子节点的连接或断开等事件。应用程序如需使用 ESP-WIFI-MESH 事件，则必须通过 :cpp:func:`esp_event_handler_register` 将 **Mesh 事件处理程序** 注册在默认事件任务中。注册完成后，ESP-WIFI-MESH 事件将包含与应用程序所有相关事件相关的处理程序。
Mesh 事件的典型应用场景包括：使用 :cpp:enumerator:`MESH_EVENT_PARENT_CONNECTED` 和 :cpp:enumerator:`MESH_EVENT_CHILD_CONNECTED` 事件来指示节点何时可以分别开始传输上行和下行的数据。同样，也可以使用 :cpp:enumerator:`IP_EVENT_STA_GOT_IP` 和 :cpp:enumerator:`IP_EVENT_STA_LOST_IP` 事件来指示根节点何时可以向外部 IP 网络传输数据。
.. warning::
在自组网模式下使用 ESP-MESH 时，用户必须确保不得调用 Wi-Fi API。原因在于：自组网模式将在内部调用 Wi-Fi API 实现连接/断开/扫描等操作。 **此时，如果外部应用程序调用 Wi-Fi API（包括来自回调函数和 Wi-Fi 事件处理程序的调用）都可能会干扰 ESP-MESH 的自组网行为**。因此，用户不应该在 :cpp:func:`esp_mesh_start` 和 :cpp:func:`esp_mesh_stop` 之间调用 Wi-Fi API。
在自组网模式下使用 ESP-WIFI-MESH 时，用户必须确保不得调用 Wi-Fi API。原因在于：自组网模式将在内部调用 Wi-Fi API 实现连接/断开/扫描等操作。 **此时，如果外部应用程序调用 Wi-Fi API（包括来自回调函数和 Wi-Fi 事件处理程序的调用）都可能会干扰 ESP-WIFI-MESH 的自组网行为**。因此，用户不应该在 :cpp:func:`esp_mesh_start` 和 :cpp:func:`esp_mesh_stop` 之间调用 Wi-Fi API。
LwIP & ESP-MESH
^^^^^^^^^^^^^^^
LwIP & ESP-WIFI-MESH
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
应用程序无需通过 LwIP 层便可直接访问 ESP-MESH 软件栈，LwIP 层仅在根节点和外部 IP 网络的数据发送与接收时会用到。但是，由于每个节点都有可能成为根节点（由于自动根节点选择机制的存在），每个节点仍必须初始化 LwIP 软件栈。
应用程序无需通过 LwIP 层便可直接访问 ESP-WIFI-MESH 软件栈，LwIP 层仅在根节点和外部 IP 网络的数据发送与接收时会用到。但是，由于每个节点都有可能成为根节点（由于自动根节点选择机制的存在），每个节点仍必须初始化 LwIP 软件栈。
**每个节点都需要通过调用** :cpp:func:`tcpip_adapter_init` **初始化 LwIP 软件栈**。 为了防止非根节点访问 LwIP，应用程序应该在 LwIP 初始化完成后停止以下服务：
- SoftAP 接口上的 DHCP 服务器服务。
- Station 接口上的 DHCP 客户端服务。
下方代码片段展示如何为 ESP-MESH 应用程序进行 LwIP 初始化。
下方代码片段展示如何为 ESP-WIFI-MESH 应用程序进行 LwIP 初始化。
.. code-block:: c
@ -86,17 +86,17 @@ LwIP & ESP-MESH
.. note::
ESP-MESH 的根节点必须与路由器连接。因此，当一个节点成为根节点时，**该节点对应的处理程序必须启动 DHCP 客户端服务并立即获取 IP 地址。** 这样做将允许其他节点开始向/从外部 IP 网络发送/接收数据包。但是，如果使用静态 IP 设置，则不需要执行此步骤。
ESP-WIFI-MESH 的根节点必须与路由器连接。因此，当一个节点成为根节点时，**该节点对应的处理程序必须启动 DHCP 客户端服务并立即获取 IP 地址。** 这样做将允许其他节点开始向/从外部 IP 网络发送/接收数据包。但是，如果使用静态 IP 设置，则不需要执行此步骤。
.. ---------------------- Writing a Mesh Application --------------------------
.. _mesh-writing-mesh-application:
编写 ESP-MESH 应用程序
编写 ESP-WIFI-MESH 应用程序
-------------------------------
ESP-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。下方代码展示了 ESP-MESH 在开始自身初始化前必须完成的步骤。
ESP-WIFI-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。下方代码展示了 ESP-WIFI-MESH 在开始自身初始化前必须完成的步骤。
.. code-block:: c
@ -120,7 +120,7 @@ ESP-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。下方
ESP_ERROR_CHECK(esp_wifi_set_storage(WIFI_STORAGE_FLASH));
ESP_ERROR_CHECK(esp_wifi_start());
在完成 LwIP 和 Wi-Fi 的初始化后，需完成以下三个步骤以启动并运行 ESP-MESH。
在完成 LwIP 和 Wi-Fi 的初始化后，需完成以下三个步骤以启动并运行 ESP-WIFI-MESH。
1. :ref:`mesh-initialize-mesh`
2. :ref:`mesh-configuring-mesh`
@ -131,7 +131,7 @@ ESP-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。下方
初始化 Mesh
^^^^^^^^^^^^^^^
下方代码片段展示如何初始化 ESP-MESH。
下方代码片段展示如何初始化 ESP-WIFI-MESH。
.. code-block:: c
@ -142,28 +142,38 @@ ESP-MESH 在正常启动前必须先初始化 LwIP 和 Wi-Fi 软件栈。下方
.. _mesh-configuring-mesh:
配置 ESP-MESH 网络
配置 ESP-WIFI-MESH 网络
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. todo - Add note about unified configuration
ESP-MESH 可通过 :cpp:func:`esp_mesh_set_config` 进行配置，并使用 :cpp:type:`mesh_cfg_t` 结构体传递参数。该结构体包含以下 ESP-MESH 的配置参数：
ESP-WIFI-MESH 可通过 :cpp:func:`esp_mesh_set_config` 进行配置，并使用 :cpp:type:`mesh_cfg_t` 结构体传递参数。该结构体包含以下 ESP-WIFI-MESH 的配置参数：
+------------------------------+----------------------------------------------------------+
| 参数 | 描述 |
+------------------------------+----------------------------------------------------------+
| Channel（信道） | 1 到 14 信道 |
+------------------------------+----------------------------------------------------------+
| Mesh ID | ESP-MESH 网络的 ID，见 :cpp:type:`mesh_addr_t`。 |
+------------------------------+----------------------------------------------------------+
| Router（路由器） | 路由器配置，见 :cpp:type:`mesh_router_t`。 |
+------------------------------+----------------------------------------------------------+
| Mesh AP | Mesh AP 配置，见 :cpp:type:`mesh_ap_cfg_t` |
+------------------------------+----------------------------------------------------------+
| Crypto Functions（加密函数） | Mesh IE 的加密函数，见 :cpp:type:`mesh_crypto_funcs_t`。 |
+------------------------------+----------------------------------------------------------+
下方代码片段展示如何配置 ESP-MESH。
.. list-table::
:header-rows: 1
:widths: 15 25
* - 参数
- 描述
* - Channel（信道）
- 1 到 14 信道
* - Mesh ID
- ESP-WIFI-MESH 网络的 ID，见 :cpp:type:`mesh_addr_t`。
* - Router（路由器）
- 路由器配置，见 :cpp:type:`mesh_router_t`。
* - Mesh AP
- Mesh AP 配置，见 :cpp:type:`mesh_ap_cfg_t`
* - Crypto Functions（加密函数）
- Mesh IE 的加密函数，见 :cpp:type:`mesh_crypto_funcs_t`。
下方代码片段展示如何配置 ESP-WIFI-MESH。
.. code-block:: c
@ -189,30 +199,30 @@ ESP-MESH 可通过 :cpp:func:`esp_mesh_set_config` 进行配置，并使用 :cpp
启动 Mesh
^^^^^^^^^^
下方代码片段展示如何启动 ESP-MESH。
下方代码片段展示如何启动 ESP-WIFI-MESH。
.. code-block:: c
/* 启动 Mesh */
ESP_ERROR_CHECK(esp_mesh_start());
启动 ESP-MESH 后，应用程序应检查 ESP-MESH 事件，以确定它是何时连接到网络的。连接后，应用程序可使用 :cpp:func:`esp_mesh_send` 和 :cpp:func:`esp_mesh_recv` 在 ESP-MESH 网络中发送、接收数据包。
启动 ESP-WIFI-MESH 后，应用程序应检查 ESP-WIFI-MESH 事件，以确定它是何时连接到网络的。连接后，应用程序可使用 :cpp:func:`esp_mesh_send` 和 :cpp:func:`esp_mesh_recv` 在 ESP-WIFI-MESH 网络中发送、接收数据包。
.. --------------------- ESP-MESH 应用程序示例 ------------------------
.. --------------------- ESP-WIFI-MESH 应用程序示例 ------------------------
.. _mesh-self-organized-behavior:
自组网
-------------------------
自组网是 ESP-MESH 的功能之一，允许节点自动扫描/选择/连接/重新连接到其他节点和路由器。此功能允许 ESP-MESH 网络具有很高的自主性，可适应变化的动态网络拓扑结构和环境。启用自组网功能后，ESP-MESH 网络中的节点能够自主完成以下操作：
自组网是 ESP-WIFI-MESH 的功能之一，允许节点自动扫描/选择/连接/重新连接到其他节点和路由器。此功能允许 ESP-WIFI-MESH 网络具有很高的自主性，可适应变化的动态网络拓扑结构和环境。启用自组网功能后，ESP-WIFI-MESH 网络中的节点能够自主完成以下操作：
- 选择或选举根节点（见 :ref:`mesh-building-a-network` 中的 **自动根节点选择**）
- 选择首选的父节点（见 :ref:`mesh-building-a-network` 中的 **父节点选择**）
- 网络断开时自动重新连接（见 :ref:`mesh-managing-a-network` 中的 **中间父节点失败**）
启用自组网功能后，ESP-MESH 软件栈将内部调用 Wi-Fi API。因此，**在启用自组网功能时，应用层不得调用 Wi-Fi API，否则会干扰 ESP-MESH 的工作。**
启用自组网功能后，ESP-WIFI-MESH 软件栈将内部调用 Wi-Fi API。因此，**在启用自组网功能时，应用层不得调用 Wi-Fi API，否则会干扰 ESP-WIFI-MESH 的工作。**
开关自组网
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -232,7 +242,7 @@ ESP-MESH 可通过 :cpp:func:`esp_mesh_set_config` 进行配置，并使用 :cpp
//禁用自组网
esp_mesh_set_self_organized(false, false);
ESP-MESH 将在禁用自组网时尝试维护节点的当前 Wi-Fi 状态。
ESP-WIFI-MESH 将在禁用自组网时尝试维护节点的当前 Wi-Fi 状态。
- 如果节点先前已连接到其他节点，则将保持连接。
- 如果节点先前已断开连接并且正在扫描父节点或路由器，则将停止扫描。
@ -241,7 +251,7 @@ ESP-MESH 将在禁用自组网时尝试维护节点的当前 Wi-Fi 状态。
启用自组网
""""""""""""""""""""""""""""""""""
ESP-MESH 将尝试在启用自组网时保持节点的当前 Wi-Fi 状态。但是，根据节点类型以及是否选择了新的父节点，节点的 Wi-Fi 状态可能会发生变化。下表显示了启用自组网的效果。
ESP-WIFI-MESH 将尝试在启用自组网时保持节点的当前 Wi-Fi 状态。但是，根据节点类型以及是否选择了新的父节点，节点的 Wi-Fi 状态可能会发生变化。下表显示了启用自组网的效果。
+----------------+--------------+------------------------------------------------------------------------------------------------------------------------+
| 是否选择父节点 | 是否为根结点 | 作用 |
@ -274,13 +284,12 @@ ESP-MESH 将尝试在启用自组网时保持节点的当前 Wi-Fi 状态。但
esp_mesh_set_self_organized(true, false);
esp_mesh_connect();
调用 Wi-Fi API
^^^^^^^^^^^^^^^^
在有些情况下，应用程序可能希望在使用 ESP-MESH 期间调用 Wi-Fi API。例如，应用程序可能需要手动扫描邻近的接入点 (AP)。**但在应用程序调用任何 Wi-Fi API 之前，必须先禁用自组网。** 否则，ESP-MESH 软件栈可能会同时调用 Wi-Fi API，进而影响应用程序的正常调用。
在有些情况下，应用程序可能希望在使用 ESP-WIFI-MESH 期间调用 Wi-Fi API。例如，应用程序可能需要手动扫描邻近的接入点 (AP)。**但在应用程序调用任何 Wi-Fi API 之前，必须先禁用自组网。** 否则，ESP-WIFI-MESH 软件栈可能会同时调用 Wi-Fi API，进而影响应用程序的正常调用。
应用程序不应在 :cpp:func:`esp_mesh_set_self_organized` 之间调用 Wi-Fi API。下方代码片段展示了应用程序如何在 ESP-MESH 运行期间安全地调用 :cpp:func:`esp_wifi_scan_start`。
应用程序不应在 :cpp:func:`esp_mesh_set_self_organized` 之间调用 Wi-Fi API。下方代码片段展示了应用程序如何在 ESP-WIFI-MESH 运行期间安全地调用 :cpp:func:`esp_wifi_scan_start`。
.. code-block:: c
@ -310,22 +319,21 @@ ESP-MESH 将尝试在启用自组网时保持节点的当前 Wi-Fi 状态。但
esp_mesh_set_self_organized(1, 0); //不选择新的父节点
esp_mesh_connect(); //手动重新连接到路由器
.. --------------------- ESP-MESH 应用程序示例 ------------------------
.. --------------------- ESP-WIFI-MESH 应用程序示例 ------------------------
.. _mesh-application-examples:
应用实例
--------------------
ESP-IDF 包含以下 ESP-MESH 示例项目：
ESP-IDF 包含以下 ESP-WIFI-MESH 示例项目：
:example:`内部通信示例 <mesh/internal_communication>` 展示了如何搭建 ESP-MESH 网络，并让根节点向网络中的每个节点发送数据包。
:example:`内部通信示例 <mesh/internal_communication>` 展示了如何搭建 ESP-WIFI-MESH 网络，并让根节点向网络中的每个节点发送数据包。
:example:`手动连网示例 <mesh/manual_networking>` 展示了如何在禁用自组网功能的情况下使用 ESP-MESH。此示例展示了如何对节点进行编程，以手动扫描潜在父节点的列表，并根据自定义标准选择父节点。
:example:`手动连网示例 <mesh/manual_networking>` 展示了如何在禁用自组网功能的情况下使用 ESP-WIFI-MESH。此示例展示了如何对节点进行编程，以手动扫描潜在父节点的列表，并根据自定义标准选择父节点。
.. -------------------------ESP-MESH API 参考 ---------------------------
.. -------------------------ESP-WIFI-MESH API 参考 ---------------------------
.. _mesh-api-reference:

4
docs/zh_CN/api-reference/network/index.rst
View File

@ -12,11 +12,11 @@ Wi-Fi
Wi-Fi <esp_wifi>
Smart Config <esp_smartconfig>
ESP-NOW <esp_now>
ESP Mesh <esp_mesh>
ESP-WIFI-MESH <esp-wifi-mesh>
本部分的 Wi-Fi API 示例代码存放在 ESP-IDF 示例项目的 :example:`wifi` 目录下。
ESP-MESH 的示例代码存放在 ESP-IDF 示例项目的 :example:`mesh` 目录下。
ESP-WIFI-MESH 的示例代码存放在 ESP-IDF 示例项目的 :example:`mesh` 目录下。
以太网