granicus.if.org Git - esp-idf/blob - components/esp32/include/esp_mesh_internal.h

   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_wifi.h"
  20 #include "esp_wifi_types.h"
  21 #include "esp_wifi_internal.h"
  22 #include "esp_wifi_crypto_types.h"
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /*******************************************************
  29  *                Constants
  30  *******************************************************/
  31
  32 /*******************************************************
  33  *                Structures
  34  *******************************************************/
  35 typedef struct {
  36     int scan;          /**< minimum scan times before being a root, default:10 */
  37     int vote;          /**< max vote times in self-healing, default:10000 */
  38     int fail;          /**< parent selection fail times, if the scan times reach this value,
  39                             will disconnect with associated children and join self-healing. default:60 */
  40     int monitor_ie;    /**< acceptable times of parent ie change before update self ie, default:3 */
  41 } mesh_attempts_t;
  42
  43 typedef struct {
  44     int duration_ms;   /* parent weak RSSI monitor duration, if the RSSI continues to be weak during this duration_ms,
  45                           will switch to a better parent */
  46     int cnx_rssi;      /* RSSI threshold for keeping a good connection with parent.
  47                           if set a value greater than -120 dBm, will arm a timer to monitor current RSSI at a period time of
  48                           duration_ms. if keep the default value(-120 dBm), a timer at a random period(<3minutes) will
  49                           be armed to switch a better parent if there does have one.
  50                           The better parent must have RSSI greater than a high RSSI threshold(-78 dBm by default) and a top layer
  51                           than current one. */
  52     int select_rssi;   /* RSSI threshold for parent selection, should be a value greater than switch_rssi */
  53     int switch_rssi;   /* Disassociate current parent and switch to a new parent when the RSSI is greater than this set threshold */
  54     int backoff_rssi;  /* RSSI threshold for connecting to the root */
  55 } mesh_switch_parent_t;
  56
  57 typedef struct {
  58     int high;
  59     int medium;
  60     int low;
  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 */
  69     uint8_t len;             /**< element length */
  70     uint8_t oui[3];          /**< organization identifier */
  71     /**< mesh networking IE content */
  72     uint8_t type;            /** mesh networking IE type */
  73     uint8_t encryped : 1;    /**< if mesh networking IE is encrypted */
  74     uint8_t version : 7;     /**< mesh networking IE version */
  75     /**< content */
  76     uint8_t mesh_type;       /**< mesh device type */
  77     uint8_t mesh_id[6];      /**< mesh ID */
  78     uint8_t layer_cap;       /**< max layer */
  79     uint8_t layer;           /**< current layer */
  80     uint8_t assoc_cap;       /**< max connections of mesh AP */
  81     uint8_t assoc;           /**< current connections */
  82     uint8_t leaf_cap;        /**< leaf capacity */
  83     uint8_t leaf_assoc;      /**< the number of current connected leaf */
  84     uint16_t root_cap;       /**< root capacity */
  85     uint16_t self_cap;       /**< self capacity */
  86     uint16_t layer2_cap;     /**< layer2 capacity */
  87     uint16_t scan_ap_num;    /**< the number of scanned APs */
  88     int8_t rssi;             /**< RSSI of the parent */
  89     int8_t router_rssi;      /**< RSSI of the router */
  90     uint8_t flag;            /**< flag of networking */
  91     uint8_t rc_addr[6];      /**< root address */
  92     int8_t rc_rssi;          /**< root RSSI */
  93     uint8_t vote_addr[6];    /**< voter address */
  94     int8_t vote_rssi;        /**< vote RSSI of the router */
  95     uint8_t vote_ttl;        /**< vote ttl */
  96     uint16_t votes;          /**< votes */
  97     uint16_t my_votes;       /**< my votes */
  98     uint8_t reason;          /**< reason */
  99     uint8_t child[6];        /**< child address */
 100     uint8_t toDS;            /**< toDS state */
 101 } __attribute__((packed)) mesh_assoc_t;
 102
 103 /*******************************************************
 104  *                Function Definitions
 105  *******************************************************/
 106 /**
 107  * @brief     set mesh softAP beacon interval
 108  *
 109  * @param     interval  beacon interval(ms) (100ms ~ 60000ms)
 110  *
 111  * @return
 112  *    - ESP_OK
 113  *    - ESP_FAIL
 114  *    - ESP_ERR_WIFI_ARG
 115  */
 116 esp_err_t esp_mesh_set_beacon_interval(int interval_ms);
 117
 118 /**
 119  * @brief     get mesh softAP beacon interval
 120  *
 121  * @param     interval  beacon interval(ms)
 122  *
 123  * @return
 124  *    - ESP_OK
 125  */
 126 esp_err_t esp_mesh_get_beacon_interval(int *interval_ms);
 127
 128 /**
 129  * @brief    set attempts for mesh self-organized networking
 130  *
 131  * @param    attempts
 132  *
 133  * @return
 134  *    - ESP_OK
 135  *    - ESP_FAIL
 136  */
 137 esp_err_t esp_mesh_set_attempts(mesh_attempts_t *attempts);
 138
 139 /**
 140  * @brief    get attempts for mesh self-organized networking
 141  *
 142  * @param    attempts
 143  *
 144  * @return
 145  *    - ESP_OK
 146  *    - ESP_ERR_MESH_ARGUMENT
 147  */
 148 esp_err_t esp_mesh_get_attempts(mesh_attempts_t *attempts);
 149
 150 /**
 151  * @brief     set parameters for parent switch
 152  *
 153  * @param     paras  parameters for parent switch
 154  *
 155  * @return
 156  *    - ESP_OK
 157  *    - ESP_ERR_MESH_ARGUMENT
 158  */
 159 esp_err_t esp_mesh_set_switch_parent_paras(mesh_switch_parent_t *paras);
 160
 161 /**
 162  * @brief     get parameters for parent switch
 163  *
 164  * @param     paras  parameters for parent switch
 165  *
 166  * @return
 167  *    - ESP_OK
 168  *    - ESP_ERR_MESH_ARGUMENT
 169  */
 170 esp_err_t esp_mesh_get_switch_parent_paras(mesh_switch_parent_t *paras);
 171
 172 /**
 173  * @brief     set RSSI threshold
 174  *            The default high RSSI threshold value is -78 dBm.
 175  *            The default medium RSSI threshold value is -82 dBm.
 176  *            The default low RSSI threshold value is -85 dBm.
 177  *
 178  * @param     threshold  RSSI threshold
 179  *
 180  * @return
 181  *    - ESP_OK
 182  *    - ESP_ERR_MESH_ARGUMENT
 183  */
 184 esp_err_t esp_mesh_set_rssi_threshold(const mesh_rssi_threshold_t *threshold);
 185
 186 /**
 187  * @brief     get RSSI threshold
 188  * @param     threshold  RSSI threshold
 189  *
 190  * @return
 191  *    - ESP_OK
 192  *    - ESP_ERR_MESH_ARGUMENT
 193  */
 194 esp_err_t esp_mesh_get_rssi_threshold(mesh_rssi_threshold_t *threshold);
 195
 196 /**
 197  * @brief     enable the minimum rate to 6Mbps
 198  *
 199  * @attention This API shall be called before WiFi start.
 200  *
 201  * @param     is_6m  enable or not
 202  *
 203  * @return
 204  *    - ESP_OK
 205  */
 206 esp_err_t esp_mesh_set_6m_rate(bool is_6m);
 207
 208 /**
 209  * @brief     print the number of txQ waiting
 210  *
 211  * @return
 212  *    - ESP_OK
 213  *    - ESP_FAIL
 214  */
 215 esp_err_t esp_mesh_print_txQ_waiting(void);
 216
 217 /**
 218  * @brief     print the number of rxQ waiting
 219  *
 220  * @return
 221  *    - ESP_OK
 222  *    - ESP_FAIL
 223  */
 224 esp_err_t esp_mesh_print_rxQ_waiting(void);
 225
 226 /**
 227  * @brief     set passive scan time
 228  *
 229  * @param     interval_ms  passive scan time(ms)
 230  *
 231  * @return
 232  *    - ESP_OK
 233  *    - ESP_FAIL
 234  *    - ESP_ERR_ARGUMENT
 235  */
 236 esp_err_t esp_mesh_set_passive_scan_time(int time_ms);
 237
 238 /**
 239  * @brief     get passive scan time
 240  *
 241  * @return    interval_ms  passive scan time(ms)
 242  */
 243 int esp_mesh_get_passive_scan_time(void);
 244
 245 /**
 246  * @brief     set announce interval
 247  *            The default short interval is 500 milliseconds.
 248  *            The default long interval is 3000 milliseconds.
 249  *
 250  * @param     short_ms  shall be greater than the default value
 251  * @param     long_ms  shall be greater than the default value
 252  *
 253  * @return
 254  *    - ESP_OK
 255  */
 256 esp_err_t esp_mesh_set_announce_interval(int short_ms, int long_ms);
 257
 258 /**
 259  * @brief     get announce interval
 260  *
 261  * @param     short_ms  short interval
 262  * @param     long_ms  long interval
 263  *
 264  * @return
 265  *    - ESP_OK
 266  */
 267 esp_err_t esp_mesh_get_announce_interval(int *short_ms, int *long_ms);
 268
 269 #ifdef __cplusplus
 270 }
 271 #endif
 272 #endif /* __ESP_MESH_INTERNAL_H__ */