1 /*
2  * SPDX-FileCopyrightText: 2017-2023 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 #ifndef __ESP_MESH_INTERNAL_H__
8 #define __ESP_MESH_INTERNAL_H__
9 
10 #include "esp_err.h"
11 #include "esp_mesh.h"
12 #include "esp_wifi.h"
13 #include "esp_wifi_types.h"
14 #include "esp_private/wifi.h"
15 #include "esp_wifi_crypto_types.h"
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20 
21 /*******************************************************
22  *                Constants
23  *******************************************************/
24 
25 /*******************************************************
26  *                Structures
27  *******************************************************/
28 /**
29  * @brief Mesh attempts
30  */
31 typedef struct {
32     int scan;          /**< minimum scan times before being a root, default:10 */
33     int vote;          /**< max vote times in self-healing, default:1000 */
34     int fail;          /**< parent selection fail times, if the scan times reach this value,
35                             device will disconnect with associated children and join self-healing. default:60 */
36     int monitor_ie;    /**< acceptable times of parent networking IE change before update its own networking IE. default:3 */
37 } mesh_attempts_t;
38 
39 /**
40  * @brief Mesh switch parent
41  */
42 typedef struct {
43     int duration_ms;   /**< parent weak RSSI monitor duration, if the RSSI continues to be weak during this duration_ms,
44                           device will search for a new parent. */
45     int cnx_rssi;      /**< RSSI threshold for keeping a good connection with parent.
46                           If set a value greater than -120 dBm, a timer will be armed to monitor parent RSSI at a period time of duration_ms. */
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 */
50 } mesh_switch_parent_t;
51 
52 /**
53  * @brief Mesh RSSI threshold
54  */
55 typedef struct {
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 */
61 } mesh_rssi_threshold_t;
62 
63 /**
64  * @brief Mesh networking IE
65  */
66 typedef struct {
67     /**< mesh networking IE head */
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. */
72     uint8_t encrypted : 1;   /**< whether mesh networking IE is encrypted */
73     uint8_t version : 7;     /**< mesh networking IE version, equal to 2 if mesh PS is enabled, equal to 1 otherwise */
74     /**< content */
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 */
101 } __attribute__((packed)) mesh_assoc_t;
102 
103 /**
104  * @brief Mesh chain layer
105  */
106 typedef struct {
107     uint16_t layer_cap;     /**< max layer of the network */
108     uint16_t layer;         /**< current layer of this node */
109 } mesh_chain_layer_t;
110 
111 /**
112  * @brief Mesh chain assoc
113  */
114 typedef struct {
115     mesh_assoc_t tree;          /**< tree top, mesh_assoc IE */
116     mesh_chain_layer_t chain;   /**< chain top, mesh_assoc IE */
117 } __attribute__((packed)) mesh_chain_assoc_t;
118 
119 /* mesh max connections */
120 #define MESH_MAX_CONNECTIONS (10)
121 
122 /**
123  * @brief Mesh power save duties
124  */
125 typedef struct {
126     uint8_t device;     /**< device power save duty*/
127     uint8_t parent;     /**< parent power save duty*/
128     struct {
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 */
133 } esp_mesh_ps_duties_t;
134 
135 /*******************************************************
136  *                Function Definitions
137  *******************************************************/
138 /**
139  * @brief      Set mesh softAP beacon interval
140  *
141  * @param[in]  interval_ms  beacon interval (msecs) (100 msecs ~ 60000 msecs)
142  *
143  * @return
144  *    - ESP_OK
145  *    - ESP_FAIL
146  *    - ESP_ERR_INVALID_ARG
147  */
148 esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
149 
150 /**
151  * @brief      Get mesh softAP beacon interval
152  *
153  * @param[out] interval_ms  beacon interval (msecs)
154  *
155  * @return
156  *    - ESP_OK
157  */
158 esp_err_t esp_mesh_get_beacon_interval(int *interval_ms);
159 
160 /**
161  * @brief     Set attempts for mesh self-organized networking
162  *
163  * @param[in] attempts
164  *
165  * @return
166  *    - ESP_OK
167  *    - ESP_FAIL
168  */
169 esp_err_t esp_mesh_set_attempts(mesh_attempts_t *attempts);
170 
171 /**
172  * @brief      Get attempts for mesh self-organized networking
173  *
174  * @param[out] attempts
175  *
176  * @return
177  *    - ESP_OK
178  *    - ESP_ERR_MESH_ARGUMENT
179  */
180 esp_err_t esp_mesh_get_attempts(mesh_attempts_t *attempts);
181 
182 /**
183  * @brief      Set parameters for parent switch
184  *
185  * @param[in]  paras  parameters for parent switch
186  *
187  * @return
188  *    - ESP_OK
189  *    - ESP_ERR_MESH_ARGUMENT
190  */
191 esp_err_t esp_mesh_set_switch_parent_paras(mesh_switch_parent_t *paras);
192 
193 /**
194  * @brief      Get parameters for parent switch
195  *
196  * @param[out] paras  parameters for parent switch
197  *
198  * @return
199  *    - ESP_OK
200  *    - ESP_ERR_MESH_ARGUMENT
201  */
202 esp_err_t esp_mesh_get_switch_parent_paras(mesh_switch_parent_t *paras);
203 
204 /**
205  * @brief      Set RSSI threshold of current parent
206  *             - The default high RSSI threshold value is -78 dBm.
207  *             - The default medium RSSI threshold value is -82 dBm.
208  *             - The default low RSSI threshold value is -85 dBm.
209  *
210  * @param[in]  threshold  RSSI threshold
211  *
212  * @return
213  *    - ESP_OK
214  *    - ESP_ERR_MESH_ARGUMENT
215  */
216 esp_err_t esp_mesh_set_rssi_threshold(const mesh_rssi_threshold_t *threshold);
217 
218 /**
219  * @brief      Get RSSI threshold of current parent
220  *
221  * @param[out] threshold  RSSI threshold
222  *
223  * @return
224  *    - ESP_OK
225  *    - ESP_ERR_MESH_ARGUMENT
226  */
227 esp_err_t esp_mesh_get_rssi_threshold(mesh_rssi_threshold_t *threshold);
228 
229 /**
230  * @brief      Enable the minimum rate to 6 Mbps
231  *
232  * @attention  This API shall be called before Wi-Fi is started.
233  *
234  * @param[in]  is_6m  enable or not
235  *
236  * @return
237  *    - ESP_OK
238  */
239 esp_err_t esp_mesh_set_6m_rate(bool is_6m);
240 
241 /**
242  * @brief      Print the number of txQ waiting
243  *
244  * @return
245  *    - ESP_OK
246  *    - ESP_FAIL
247  */
248 esp_err_t esp_mesh_print_txQ_waiting(void);
249 
250 /**
251  * @brief      Print the number of rxQ waiting
252  *
253  * @return
254  *    - ESP_OK
255  *    - ESP_FAIL
256  */
257 esp_err_t esp_mesh_print_rxQ_waiting(void);
258 
259 /**
260  * @brief      Set passive scan time
261  *
262  * @param[in]  time_ms  passive scan time (msecs)
263  *
264  * @return
265  *    - ESP_OK
266  *    - ESP_FAIL
267  *    - ESP_ERR_ARGUMENT
268  */
269 esp_err_t esp_mesh_set_passive_scan_time(int time_ms);
270 
271 /**
272  * @brief      Get passive scan time
273  *
274  * @return     interval_ms  passive scan time (msecs)
275  */
276 int esp_mesh_get_passive_scan_time(void);
277 
278 /**
279  * @brief      Set announce interval
280  *             - The default short interval is 500 milliseconds.
281  *             - The default long interval is 3000 milliseconds.
282  *
283  * @param[in]  short_ms  shall be greater than the default value
284  * @param[in]  long_ms  shall be greater than the default value
285  *
286  * @return
287  *    - ESP_OK
288  */
289 esp_err_t esp_mesh_set_announce_interval(int short_ms, int long_ms);
290 
291 /**
292  * @brief      Get announce interval
293  *
294  * @param[out] short_ms  short interval
295  * @param[out] long_ms  long interval
296  *
297  * @return
298  *    - ESP_OK
299  */
300 esp_err_t esp_mesh_get_announce_interval(int *short_ms, int *long_ms);
301 
302 /**
303  * @brief      Get the running duties of device, parent and children
304  *
305  * @param[out] ps_duties ps duties
306  *
307  * @return
308  *    - ESP_OK
309  */
310 esp_err_t esp_mesh_ps_get_duties(esp_mesh_ps_duties_t* ps_duties);
311 
312 /**
313  * @brief      Enable mesh print scan result
314  *
315  * @param[in]  enable  enable or not
316  *
317  * @return
318  *    - ESP_OK
319  */
320 esp_err_t esp_mesh_print_scan_result(bool enable);
321 #ifdef __cplusplus
322 }
323 #endif
324 #endif /* __ESP_MESH_INTERNAL_H__ */
325