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
