1 // Copyright 2017-2018 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef __ESP_MESH_INTERNAL_H__
16 #define __ESP_MESH_INTERNAL_H__
17 
18 #include "esp_err.h"
19 #include "esp_mesh.h"
20 #include "esp_wifi.h"
21 #include "esp_wifi_types.h"
22 #include "esp_private/wifi.h"
23 #include "esp_wifi_crypto_types.h"
24 
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28 
29 /*******************************************************
30  *                Constants
31  *******************************************************/
32 
33 /*******************************************************
34  *                Structures
35  *******************************************************/
36 typedef struct {
37     int scan;          /**< minimum scan times before being a root, default:10 */
38     int vote;          /**< max vote times in self-healing, default:1000 */
39     int fail;          /**< parent selection fail times, if the scan times reach this value,
40                             device will disconnect with associated children and join self-healing. default:60 */
41     int monitor_ie;    /**< acceptable times of parent networking IE change before update its own networking IE. default:3 */
42 } mesh_attempts_t;
43 
44 typedef struct {
45     int duration_ms;   /* parent weak RSSI monitor duration, if the RSSI continues to be weak during this duration_ms,
46                           device will search for a new parent. */
47     int cnx_rssi;      /* RSSI threshold for keeping a good connection with parent.
48                           If set a value greater than -120 dBm, a timer will be armed to monitor parent RSSI at a period time of duration_ms. */
49     int select_rssi;   /* RSSI threshold for parent selection. It should be a value greater than switch_rssi. */
50     int switch_rssi;   /* Disassociate with current parent and switch to a new parent when the RSSI is greater than this set threshold. */
51     int backoff_rssi;  /* RSSI threshold for connecting to the root */
52 } mesh_switch_parent_t;
53 
54 typedef struct {
55     int high;
56     int medium;
57     int low;
58 } mesh_rssi_threshold_t;
59 
60 /**
61  * @brief Mesh networking IE
62  */
63 typedef struct {
64     /**< mesh networking IE head */
65     uint8_t eid;             /**< element ID */
66     uint8_t len;             /**< element length */
67     uint8_t oui[3];          /**< organization identifier */
68     /**< mesh networking IE content */
69     uint8_t type;            /** ESP defined IE type */
70     uint8_t encrypted : 1;   /**< whether mesh networking IE is encrypted */
71     uint8_t version : 7;     /**< mesh networking IE version */
72     /**< content */
73     uint8_t mesh_type;       /**< mesh device type */
74     uint8_t mesh_id[6];      /**< mesh ID */
75     uint8_t layer_cap;       /**< max layer */
76     uint8_t layer;           /**< current layer */
77     uint8_t assoc_cap;       /**< max connections of mesh AP */
78     uint8_t assoc;           /**< current connections */
79     uint8_t leaf_cap;        /**< leaf capacity */
80     uint8_t leaf_assoc;      /**< the number of current connected leaf */
81     uint16_t root_cap;       /**< root capacity */
82     uint16_t self_cap;       /**< self capacity */
83     uint16_t layer2_cap;     /**< layer2 capacity */
84     uint16_t scan_ap_num;    /**< the number of scanning APs */
85     int8_t rssi;             /**< RSSI of the parent */
86     int8_t router_rssi;      /**< RSSI of the router */
87     uint8_t flag;            /**< flag of networking */
88     uint8_t rc_addr[6];      /**< root address */
89     int8_t rc_rssi;          /**< root RSSI */
90     uint8_t vote_addr[6];    /**< voter address */
91     int8_t vote_rssi;        /**< vote RSSI of the router */
92     uint8_t vote_ttl;        /**< vote ttl */
93     uint16_t votes;          /**< votes */
94     uint16_t my_votes;       /**< my votes */
95     uint8_t reason;          /**< reason */
96     uint8_t child[6];        /**< child address */
97     uint8_t toDS;            /**< toDS state */
98 } __attribute__((packed)) mesh_assoc_t;
99 
100 typedef struct {
101     uint16_t layer_cap;
102     uint16_t layer;
103 } mesh_chain_layer_t;
104 
105 typedef struct {
106     mesh_assoc_t tree;
107     mesh_chain_layer_t chain;
108 } __attribute__((packed)) mesh_chain_assoc_t;
109 
110 /**
111  * @brief Mesh PS duties
112  */
113 typedef struct {
114     uint8_t device;
115     uint8_t parent;
116     struct {
117         bool used;
118         uint8_t duty;
119         uint8_t mac[6];
120     } child[ESP_WIFI_MAX_CONN_NUM];
121 } esp_mesh_ps_duties_t;
122 
123 /*******************************************************
124  *                Function Definitions
125  *******************************************************/
126 /**
127  * @brief      Set mesh softAP beacon interval
128  *
129  * @param[in]  interval  beacon interval (msecs) (100 msecs ~ 60000 msecs)
130  *
131  * @return
132  *    - ESP_OK
133  *    - ESP_FAIL
134  *    - ESP_ERR_WIFI_ARG
135  */
136 esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
137 
138 /**
139  * @brief      Get mesh softAP beacon interval
140  *
141  * @param[out] interval  beacon interval (msecs)
142  *
143  * @return
144  *    - ESP_OK
145  */
146 esp_err_t esp_mesh_get_beacon_interval(int *interval_ms);
147 
148 /**
149  * @brief     Set attempts for mesh self-organized networking
150  *
151  * @param[in] attempts
152  *
153  * @return
154  *    - ESP_OK
155  *    - ESP_FAIL
156  */
157 esp_err_t esp_mesh_set_attempts(mesh_attempts_t *attempts);
158 
159 /**
160  * @brief      Get attempts for mesh self-organized networking
161  *
162  * @param[out] attempts
163  *
164  * @return
165  *    - ESP_OK
166  *    - ESP_ERR_MESH_ARGUMENT
167  */
168 esp_err_t esp_mesh_get_attempts(mesh_attempts_t *attempts);
169 
170 /**
171  * @brief      Set parameters for parent switch
172  *
173  * @param[in]  paras  parameters for parent switch
174  *
175  * @return
176  *    - ESP_OK
177  *    - ESP_ERR_MESH_ARGUMENT
178  */
179 esp_err_t esp_mesh_set_switch_parent_paras(mesh_switch_parent_t *paras);
180 
181 /**
182  * @brief      Get parameters for parent switch
183  *
184  * @param[out] paras  parameters for parent switch
185  *
186  * @return
187  *    - ESP_OK
188  *    - ESP_ERR_MESH_ARGUMENT
189  */
190 esp_err_t esp_mesh_get_switch_parent_paras(mesh_switch_parent_t *paras);
191 
192 /**
193  * @brief      Set RSSI threshold
194  *             - The default high RSSI threshold value is -78 dBm.
195  *             - The default medium RSSI threshold value is -82 dBm.
196  *             - The default low RSSI threshold value is -85 dBm.
197  *
198  * @param[in]  threshold  RSSI threshold
199  *
200  * @return
201  *    - ESP_OK
202  *    - ESP_ERR_MESH_ARGUMENT
203  */
204 esp_err_t esp_mesh_set_rssi_threshold(const mesh_rssi_threshold_t *threshold);
205 
206 /**
207  * @brief      Get RSSI threshold
208  *
209  * @param[out] threshold  RSSI threshold
210  *
211  * @return
212  *    - ESP_OK
213  *    - ESP_ERR_MESH_ARGUMENT
214  */
215 esp_err_t esp_mesh_get_rssi_threshold(mesh_rssi_threshold_t *threshold);
216 
217 /**
218  * @brief      Enable the minimum rate to 6 Mbps
219  *
220  * @attention  This API shall be called before Wi-Fi is started.
221  *
222  * @param[in]  is_6m  enable or not
223  *
224  * @return
225  *    - ESP_OK
226  */
227 esp_err_t esp_mesh_set_6m_rate(bool is_6m);
228 
229 /**
230  * @brief      Print the number of txQ waiting
231  *
232  * @return
233  *    - ESP_OK
234  *    - ESP_FAIL
235  */
236 esp_err_t esp_mesh_print_txQ_waiting(void);
237 
238 /**
239  * @brief      Print the number of rxQ waiting
240  *
241  * @return
242  *    - ESP_OK
243  *    - ESP_FAIL
244  */
245 esp_err_t esp_mesh_print_rxQ_waiting(void);
246 
247 /**
248  * @brief      Set passive scan time
249  *
250  * @param[in]  interval_ms  passive scan time (msecs)
251  *
252  * @return
253  *    - ESP_OK
254  *    - ESP_FAIL
255  *    - ESP_ERR_ARGUMENT
256  */
257 esp_err_t esp_mesh_set_passive_scan_time(int time_ms);
258 
259 /**
260  * @brief      Get passive scan time
261  *
262  * @return     interval_ms  passive scan time (msecs)
263  */
264 int esp_mesh_get_passive_scan_time(void);
265 
266 /**
267  * @brief      Set announce interval
268  *             - The default short interval is 500 milliseconds.
269  *             - The default long interval is 3000 milliseconds.
270  *
271  * @param[in]  short_ms  shall be greater than the default value
272  * @param[in]  long_ms  shall be greater than the default value
273  *
274  * @return
275  *    - ESP_OK
276  */
277 esp_err_t esp_mesh_set_announce_interval(int short_ms, int long_ms);
278 
279 /**
280  * @brief      Get announce interval
281  *
282  * @param[out] short_ms  short interval
283  * @param[out] long_ms  long interval
284  *
285  * @return
286  *    - ESP_OK
287  */
288 esp_err_t esp_mesh_get_announce_interval(int *short_ms, int *long_ms);
289 
290 /**
291   * @brief      Get the running duties of device, parent and children
292  *
293  * @return
294  *    - ESP_OK
295  */
296 esp_err_t esp_mesh_ps_get_duties(esp_mesh_ps_duties_t* ps_duties);
297 
298 /**
299  * @brief      Enable mesh print scan result
300  *
301  * @param[in]  enable  enable or not
302  *
303  * @return
304  *    - ESP_OK
305  */
306 esp_err_t esp_mesh_print_scan_result(bool enable);
307 #ifdef __cplusplus
308 }
309 #endif
310 #endif /* __ESP_MESH_INTERNAL_H__ */
311