11/*
2- * SPDX-FileCopyrightText: 2017-2021 Espressif Systems (Shanghai) CO LTD
2+ * SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD
33 *
44 * SPDX-License-Identifier: Apache-2.0
55 */
@@ -25,6 +25,9 @@ extern "C" {
2525/*******************************************************
2626 * Structures
2727 *******************************************************/
28+ /**
29+ * @brief Mesh attempts
30+ */
2831typedef struct {
2932 int scan ; /**< minimum scan times before being a root, default:10 */
3033 int vote ; /**< max vote times in self-healing, default:1000 */
@@ -33,86 +36,100 @@ typedef struct {
3336 int monitor_ie ; /**< acceptable times of parent networking IE change before update its own networking IE. default:3 */
3437} mesh_attempts_t ;
3538
39+ /**
40+ * @brief Mesh switch parent
41+ */
3642typedef struct {
37- int duration_ms ; /* parent weak RSSI monitor duration, if the RSSI continues to be weak during this duration_ms,
43+ int duration_ms ; /**< parent weak RSSI monitor duration, if the RSSI continues to be weak during this duration_ms,
3844 device will search for a new parent. */
39- int cnx_rssi ; /* RSSI threshold for keeping a good connection with parent.
45+ int cnx_rssi ; /**< RSSI threshold for keeping a good connection with parent.
4046 If set a value greater than -120 dBm, a timer will be armed to monitor parent RSSI at a period time of duration_ms. */
41- int select_rssi ; /* RSSI threshold for parent selection. It should be a value greater than switch_rssi. */
42- int switch_rssi ; /* Disassociate with current parent and switch to a new parent when the RSSI is greater than this set threshold. */
43- int backoff_rssi ; /* RSSI threshold for connecting to the root */
47+ int select_rssi ; /**< RSSI threshold for parent selection. It should be a value greater than switch_rssi. */
48+ int switch_rssi ; /**< Disassociate with current parent and switch to a new parent when the RSSI is greater than this set threshold. */
49+ int backoff_rssi ; /**< RSSI threshold for connecting to the root */
4450} mesh_switch_parent_t ;
4551
52+ /**
53+ * @brief Mesh RSSI threshold
54+ */
4655typedef struct {
47- int high ;
48- int medium ;
49- int low ;
56+ int high ; /**< high RSSI threshold, used to determine whether the new parent and the current parent are in the same RSSI range */
57+ int medium ; /**< medium RSSI threshold, used to determine whether the new parent and the current parent are in the same RSSI range */
58+ int low ; /**< low RSSI threshold. If the parent's RSSI is lower than low for a period time of duration_ms,
59+ then the mesh node will post MESH_WEAK_RSSI event.
60+ Also used to determine whether the new parent and the current parent are in the same RSSI range */
5061} mesh_rssi_threshold_t ;
5162
5263/**
5364 * @brief Mesh networking IE
5465 */
5566typedef struct {
5667 /**< mesh networking IE head */
57- uint8_t eid ; /**< element ID */
58- uint8_t len ; /**< element length */
59- uint8_t oui [3 ]; /**< organization identifier */
60- /**< mesh networking IE content */
61- uint8_t type ; /** ESP defined IE type */
68+ uint8_t eid ; /**< element ID, vendor specific, 221 */
69+ uint8_t len ; /**< element length, the length after this member */
70+ uint8_t oui [3 ]; /**< organization identifier, 0x18fe34 */
71+ uint8_t type ; /**< ESP defined IE type, include Assoc IE, SSID IE, Ext Assoc IE, Roots IE, etc. */
6272 uint8_t encrypted : 1 ; /**< whether mesh networking IE is encrypted */
63- uint8_t version : 7 ; /**< mesh networking IE version */
73+ uint8_t version : 7 ; /**< mesh networking IE version, equal to 2 if mesh PS is enabled, equal to 1 otherwise */
6474 /**< content */
65- uint8_t mesh_type ; /**< mesh device type */
66- uint8_t mesh_id [6 ]; /**< mesh ID */
67- uint8_t layer_cap ; /**< max layer */
68- uint8_t layer ; /**< current layer */
69- uint8_t assoc_cap ; /**< max connections of mesh AP */
70- uint8_t assoc ; /**< current connections */
71- uint8_t leaf_cap ; /**< leaf capacity */
72- uint8_t leaf_assoc ; /**< the number of current connected leaf */
73- uint16_t root_cap ; /**< root capacity */
74- uint16_t self_cap ; /**< self capacity */
75- uint16_t layer2_cap ; /**< layer2 capacity */
76- uint16_t scan_ap_num ; /**< the number of scanning APs */
77- int8_t rssi ; /**< RSSI of the parent */
78- int8_t router_rssi ; /**< RSSI of the router */
79- uint8_t flag ; /**< flag of networking */
80- uint8_t rc_addr [6 ]; /**< root address */
81- int8_t rc_rssi ; /**< root RSSI */
82- uint8_t vote_addr [6 ]; /**< voter address */
83- int8_t vote_rssi ; /**< vote RSSI of the router */
84- uint8_t vote_ttl ; /**< vote ttl */
85- uint16_t votes ; /**< votes */
86- uint16_t my_votes ; /**< my votes */
87- uint8_t reason ; /**< reason */
88- uint8_t child [6 ]; /**< child address */
89- uint8_t toDS ; /**< toDS state */
75+ uint8_t mesh_type ; /**< mesh device type, include idle, root, node, etc, refer to mesh_type_t */
76+ uint8_t mesh_id [6 ]; /**< mesh ID, only the same mesh id can form a unified mesh network */
77+ uint8_t layer_cap ; /**< layer_cap = max_layer - layer, indicates the number of remaining available layers of the mesh network */
78+ uint8_t layer ; /**< the current layer of this node */
79+ uint8_t assoc_cap ; /**< the maximum connections of this mesh AP */
80+ uint8_t assoc ; /**< current connections of this mesh AP */
81+ uint8_t leaf_cap ; /**< the maximum number of leaves in the mesh network */
82+ uint8_t leaf_assoc ; /**< the number of current connected leaves */
83+ uint16_t root_cap ; /**< the capacity of the root, equal to the total child numbers plus 1, root node updates root_cap and self_cap */
84+ uint16_t self_cap ; /**< the capacity of myself, total child numbers plus 1, all nodes update this member */
85+ uint16_t layer2_cap ; /**< the capacity of layer2 node, total child numbers plus 1, layer2 node updates layer2_cap and self_cap, root sets this to 0 */
86+ uint16_t scan_ap_num ; /**< the number of mesh APs around */
87+ int8_t rssi ; /**< RSSI of the connected parent, default value is -120, root node will not update this */
88+ int8_t router_rssi ; /**< RSSI of the router, default value is -120 */
89+ uint8_t flag ; /**< flag of networking, indicates the status of the network, refer to MESH_ASSOC_FLAG_XXX */
90+ /**< vote related */
91+ uint8_t rc_addr [6 ]; /**< the address of the root candidate, i.e. the voted addesss before connection, root node will update this with self address */
92+ int8_t rc_rssi ; /**< the router RSSI of the root candidate */
93+ uint8_t vote_addr [6 ]; /**< the voted address after connection */
94+ int8_t vote_rssi ; /**< the router RSSI of the voted address */
95+ uint8_t vote_ttl ; /**< vote ttl, indicate the voting is from myself or from other nodes */
96+ uint16_t votes ; /**< the number of all voting nodes */
97+ uint16_t my_votes ; /**< the number of nodes that voted for me */
98+ uint8_t reason ; /**< the reason why the voting happens, root initiated or child initiated, refer to mesh_vote_reason_t */
99+ uint8_t child [6 ]; /**< child address, not used currently */
100+ uint8_t toDS ; /**< state represents whether the root is able to access external IP network */
90101} __attribute__((packed )) mesh_assoc_t ;
91102
103+ /**
104+ * @brief Mesh chain layer
105+ */
92106typedef struct {
93- uint16_t layer_cap ;
94- uint16_t layer ;
107+ uint16_t layer_cap ; /**< max layer of the network */
108+ uint16_t layer ; /**< current layer of this node */
95109} mesh_chain_layer_t ;
96110
111+ /**
112+ * @brief Mesh chain assoc
113+ */
97114typedef struct {
98- mesh_assoc_t tree ;
99- mesh_chain_layer_t chain ;
115+ mesh_assoc_t tree ; /**< tree top, mesh_assoc IE */
116+ mesh_chain_layer_t chain ; /**< chain top, mesh_assoc IE */
100117} __attribute__((packed )) mesh_chain_assoc_t ;
101118
102119/* mesh max connections */
103120#define MESH_MAX_CONNECTIONS (10)
104121
105122/**
106- * @brief Mesh PS duties
123+ * @brief Mesh power save duties
107124 */
108125typedef struct {
109- uint8_t device ;
110- uint8_t parent ;
126+ uint8_t device ; /**< device power save duty*/
127+ uint8_t parent ; /**< parent power save duty*/
111128 struct {
112- bool used ;
113- uint8_t duty ;
114- uint8_t mac [6 ];
115- } child [MESH_MAX_CONNECTIONS ];
129+ bool used ; /**< whether the child is joined */
130+ uint8_t duty ; /**< power save duty of the child */
131+ uint8_t mac [6 ]; /**< mac address of the child */
132+ } child [MESH_MAX_CONNECTIONS ]; /**< child */
116133} esp_mesh_ps_duties_t ;
117134
118135/*******************************************************
@@ -121,7 +138,7 @@ typedef struct {
121138/**
122139 * @brief Set mesh softAP beacon interval
123140 *
124- * @param[in] interval beacon interval (msecs) (100 msecs ~ 60000 msecs)
141+ * @param[in] interval_ms beacon interval (msecs) (100 msecs ~ 60000 msecs)
125142 *
126143 * @return
127144 * - ESP_OK
@@ -133,7 +150,7 @@ esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
133150/**
134151 * @brief Get mesh softAP beacon interval
135152 *
136- * @param[out] interval beacon interval (msecs)
153+ * @param[out] interval_ms beacon interval (msecs)
137154 *
138155 * @return
139156 * - ESP_OK
@@ -185,7 +202,7 @@ esp_err_t esp_mesh_set_switch_parent_paras(mesh_switch_parent_t *paras);
185202esp_err_t esp_mesh_get_switch_parent_paras (mesh_switch_parent_t * paras );
186203
187204/**
188- * @brief Set RSSI threshold
205+ * @brief Set RSSI threshold of current parent
189206 * - The default high RSSI threshold value is -78 dBm.
190207 * - The default medium RSSI threshold value is -82 dBm.
191208 * - The default low RSSI threshold value is -85 dBm.
@@ -199,7 +216,7 @@ esp_err_t esp_mesh_get_switch_parent_paras(mesh_switch_parent_t *paras);
199216esp_err_t esp_mesh_set_rssi_threshold (const mesh_rssi_threshold_t * threshold );
200217
201218/**
202- * @brief Get RSSI threshold
219+ * @brief Get RSSI threshold of current parent
203220 *
204221 * @param[out] threshold RSSI threshold
205222 *
@@ -242,7 +259,7 @@ esp_err_t esp_mesh_print_rxQ_waiting(void);
242259/**
243260 * @brief Set passive scan time
244261 *
245- * @param[in] interval_ms passive scan time (msecs)
262+ * @param[in] time_ms passive scan time (msecs)
246263 *
247264 * @return
248265 * - ESP_OK
@@ -283,7 +300,9 @@ esp_err_t esp_mesh_set_announce_interval(int short_ms, int long_ms);
283300esp_err_t esp_mesh_get_announce_interval (int * short_ms , int * long_ms );
284301
285302/**
286- * @brief Get the running duties of device, parent and children
303+ * @brief Get the running duties of device, parent and children
304+ *
305+ * @param[out] ps_duties ps duties
287306 *
288307 * @return
289308 * - ESP_OK
0 commit comments