1 /* 2 * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 8 /* Notes about WiFi Programming 9 * 10 * WiFi programming model can be depicted as following picture: 11 * 12 * 13 * default handler user handler 14 * ------------- --------------- --------------- 15 * | | event | | callback or | | 16 * | tcpip | ---------> | event | ----------> | application | 17 * | stack | | task | event | task | 18 * |-----------| |-------------| |-------------| 19 * /|\ | 20 * | | 21 * event | | 22 * | | 23 * | | 24 * --------------- | 25 * | | | 26 * | WiFi Driver |/__________________| 27 * | |\ API call 28 * | | 29 * |-------------| 30 * 31 * The WiFi driver can be consider as black box, it knows nothing about the high layer code, such as 32 * TCPIP stack, application task, event task etc, all it can do is to receive API call from high layer 33 * or post event queue to a specified Queue, which is initialized by API esp_wifi_init(). 34 * 35 * The event task is a daemon task, which receives events from WiFi driver or from other subsystem, such 36 * as TCPIP stack, event task will call the default callback function on receiving the event. For example, 37 * on receiving event WIFI_EVENT_STA_CONNECTED, it will call esp_netif API to start the DHCP 38 * client in it's default handler. 39 * 40 * Application can register it's own event callback function by API esp_event_init, then the application callback 41 * function will be called after the default callback. Also, if application doesn't want to execute the callback 42 * in the event task, what it needs to do is to post the related event to application task in the application callback function. 43 * 44 * The application task (code) generally mixes all these thing together, it calls APIs to init the system/WiFi and 45 * handle the events when necessary. 46 * 47 */ 48 49 #ifndef __ESP_WIFI_H__ 50 #define __ESP_WIFI_H__ 51 52 #include <stdint.h> 53 #include <stdbool.h> 54 #include "esp_err.h" 55 #include "esp_wifi_types.h" 56 #include "esp_event.h" 57 #include "esp_private/esp_wifi_private.h" 58 #include "esp_wifi_default.h" 59 #include "zephyr_compat.h" 60 61 #ifdef __cplusplus 62 extern "C" { 63 #endif 64 65 #define ESP_ERR_WIFI_NOT_INIT (ESP_ERR_WIFI_BASE + 1) /*!< WiFi driver was not installed by esp_wifi_init */ 66 #define ESP_ERR_WIFI_NOT_STARTED (ESP_ERR_WIFI_BASE + 2) /*!< WiFi driver was not started by esp_wifi_start */ 67 #define ESP_ERR_WIFI_NOT_STOPPED (ESP_ERR_WIFI_BASE + 3) /*!< WiFi driver was not stopped by esp_wifi_stop */ 68 #define ESP_ERR_WIFI_IF (ESP_ERR_WIFI_BASE + 4) /*!< WiFi interface error */ 69 #define ESP_ERR_WIFI_MODE (ESP_ERR_WIFI_BASE + 5) /*!< WiFi mode error */ 70 #define ESP_ERR_WIFI_STATE (ESP_ERR_WIFI_BASE + 6) /*!< WiFi internal state error */ 71 #define ESP_ERR_WIFI_CONN (ESP_ERR_WIFI_BASE + 7) /*!< WiFi internal control block of station or soft-AP error */ 72 #define ESP_ERR_WIFI_NVS (ESP_ERR_WIFI_BASE + 8) /*!< WiFi internal NVS module error */ 73 #define ESP_ERR_WIFI_MAC (ESP_ERR_WIFI_BASE + 9) /*!< MAC address is invalid */ 74 #define ESP_ERR_WIFI_SSID (ESP_ERR_WIFI_BASE + 10) /*!< SSID is invalid */ 75 #define ESP_ERR_WIFI_PASSWORD (ESP_ERR_WIFI_BASE + 11) /*!< Password is invalid */ 76 #define ESP_ERR_WIFI_TIMEOUT (ESP_ERR_WIFI_BASE + 12) /*!< Timeout error */ 77 #define ESP_ERR_WIFI_WAKE_FAIL (ESP_ERR_WIFI_BASE + 13) /*!< WiFi is in sleep state(RF closed) and wakeup fail */ 78 #define ESP_ERR_WIFI_WOULD_BLOCK (ESP_ERR_WIFI_BASE + 14) /*!< The caller would block */ 79 #define ESP_ERR_WIFI_NOT_CONNECT (ESP_ERR_WIFI_BASE + 15) /*!< Station still in disconnect status */ 80 81 #define ESP_ERR_WIFI_POST (ESP_ERR_WIFI_BASE + 18) /*!< Failed to post the event to WiFi task */ 82 #define ESP_ERR_WIFI_INIT_STATE (ESP_ERR_WIFI_BASE + 19) /*!< Invalid WiFi state when init/deinit is called */ 83 #define ESP_ERR_WIFI_STOP_STATE (ESP_ERR_WIFI_BASE + 20) /*!< Returned when WiFi is stopping */ 84 #define ESP_ERR_WIFI_NOT_ASSOC (ESP_ERR_WIFI_BASE + 21) /*!< The WiFi connection is not associated */ 85 #define ESP_ERR_WIFI_TX_DISALLOW (ESP_ERR_WIFI_BASE + 22) /*!< The WiFi TX is disallowed */ 86 87 #define ESP_ERR_WIFI_TWT_FULL (ESP_ERR_WIFI_BASE + 23) /*!< no available flow id */ 88 #define ESP_ERR_WIFI_TWT_SETUP_TIMEOUT (ESP_ERR_WIFI_BASE + 24) /*!< Timeout of receiving twt setup response frame, timeout times can be set during twt setup */ 89 #define ESP_ERR_WIFI_TWT_SETUP_TXFAIL (ESP_ERR_WIFI_BASE + 25) /*!< TWT setup frame tx failed */ 90 #define ESP_ERR_WIFI_TWT_SETUP_REJECT (ESP_ERR_WIFI_BASE + 26) /*!< The twt setup request was rejected by the AP */ 91 #define ESP_ERR_WIFI_DISCARD (ESP_ERR_WIFI_BASE + 27) /*!< Discard frame */ 92 93 /** 94 * @brief WiFi stack configuration parameters passed to esp_wifi_init call. 95 */ 96 typedef struct { 97 wifi_osi_funcs_t* osi_funcs; /**< WiFi OS functions */ 98 wpa_crypto_funcs_t wpa_crypto_funcs; /**< WiFi station crypto functions when connect */ 99 int static_rx_buf_num; /**< WiFi static RX buffer number */ 100 int dynamic_rx_buf_num; /**< WiFi dynamic RX buffer number */ 101 int tx_buf_type; /**< WiFi TX buffer type */ 102 int static_tx_buf_num; /**< WiFi static TX buffer number */ 103 int dynamic_tx_buf_num; /**< WiFi dynamic TX buffer number */ 104 int rx_mgmt_buf_type; /**< WiFi RX MGMT buffer type */ 105 int rx_mgmt_buf_num; /**< WiFi RX MGMT buffer number */ 106 int cache_tx_buf_num; /**< WiFi TX cache buffer number */ 107 int csi_enable; /**< WiFi channel state information enable flag */ 108 int ampdu_rx_enable; /**< WiFi AMPDU RX feature enable flag */ 109 int ampdu_tx_enable; /**< WiFi AMPDU TX feature enable flag */ 110 int amsdu_tx_enable; /**< WiFi AMSDU TX feature enable flag */ 111 int nvs_enable; /**< WiFi NVS flash enable flag */ 112 int nano_enable; /**< Nano option for printf/scan family enable flag */ 113 int rx_ba_win; /**< WiFi Block Ack RX window size */ 114 int wifi_task_core_id; /**< WiFi Task Core ID */ 115 int beacon_max_len; /**< WiFi softAP maximum length of the beacon */ 116 int mgmt_sbuf_num; /**< WiFi management short buffer number, the minimum value is 6, the maximum value is 32 */ 117 uint64_t feature_caps; /**< Enables additional WiFi features and capabilities */ 118 bool sta_disconnected_pm; /**< WiFi Power Management for station at disconnected status */ 119 int espnow_max_encrypt_num; /**< Maximum encrypt number of peers supported by espnow */ 120 int magic; /**< WiFi init magic number, it should be the last field */ 121 } wifi_init_config_t; 122 123 #ifdef CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM 124 #define WIFI_STATIC_TX_BUFFER_NUM CONFIG_ESP_WIFI_STATIC_TX_BUFFER_NUM 125 #else 126 #define WIFI_STATIC_TX_BUFFER_NUM 0 127 #endif 128 129 #ifdef CONFIG_ESP_WIFI_CACHE_TX_BUFFER_NUM 130 #define WIFI_CACHE_TX_BUFFER_NUM CONFIG_ESP_WIFI_CACHE_TX_BUFFER_NUM 131 #else 132 #define WIFI_CACHE_TX_BUFFER_NUM 0 133 #endif 134 135 #ifdef CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM 136 #define WIFI_DYNAMIC_TX_BUFFER_NUM CONFIG_ESP_WIFI_DYNAMIC_TX_BUFFER_NUM 137 #else 138 #define WIFI_DYNAMIC_TX_BUFFER_NUM 0 139 #endif 140 141 #ifdef CONFIG_ESP_WIFI_RX_MGMT_BUF_NUM_DEF 142 #define WIFI_RX_MGMT_BUF_NUM_DEF CONFIG_ESP_WIFI_RX_MGMT_BUF_NUM_DEF 143 #else 144 #define WIFI_RX_MGMT_BUF_NUM_DEF 0 145 #endif 146 147 #if CONFIG_ESP_WIFI_CSI_ENABLED 148 #define WIFI_CSI_ENABLED 1 149 #else 150 #define WIFI_CSI_ENABLED 0 151 #endif 152 153 #if CONFIG_ESP_WIFI_AMPDU_RX_ENABLED 154 #define WIFI_AMPDU_RX_ENABLED 1 155 #else 156 #define WIFI_AMPDU_RX_ENABLED 0 157 #endif 158 159 #if CONFIG_ESP_WIFI_AMPDU_TX_ENABLED 160 #define WIFI_AMPDU_TX_ENABLED 1 161 #else 162 #define WIFI_AMPDU_TX_ENABLED 0 163 #endif 164 165 #if CONFIG_ESP_WIFI_AMSDU_TX_ENABLED 166 #define WIFI_AMSDU_TX_ENABLED 1 167 #else 168 #define WIFI_AMSDU_TX_ENABLED 0 169 #endif 170 171 #if CONFIG_ESP_WIFI_NVS_ENABLED 172 #define WIFI_NVS_ENABLED 1 173 #else 174 #define WIFI_NVS_ENABLED 0 175 #endif 176 177 #if CONFIG_NEWLIB_NANO_FORMAT 178 #define WIFI_NANO_FORMAT_ENABLED 1 179 #else 180 #define WIFI_NANO_FORMAT_ENABLED 0 181 #endif 182 183 extern const wpa_crypto_funcs_t g_wifi_default_wpa_crypto_funcs; 184 185 #define WIFI_INIT_CONFIG_MAGIC 0x1F2F3F4F 186 187 #ifdef CONFIG_ESP_WIFI_AMPDU_RX_ENABLED 188 #define WIFI_DEFAULT_RX_BA_WIN CONFIG_ESP_WIFI_RX_BA_WIN 189 #else 190 #define WIFI_DEFAULT_RX_BA_WIN 0 /* unused if ampdu_rx_enable == false */ 191 #endif 192 193 #if CONFIG_ESP_WIFI_TASK_PINNED_TO_CORE_1 194 #define WIFI_TASK_CORE_ID 1 195 #else 196 #define WIFI_TASK_CORE_ID 0 197 #endif 198 199 #ifdef CONFIG_ESP_WIFI_SOFTAP_BEACON_MAX_LEN 200 #define WIFI_SOFTAP_BEACON_MAX_LEN CONFIG_ESP_WIFI_SOFTAP_BEACON_MAX_LEN 201 #else 202 #define WIFI_SOFTAP_BEACON_MAX_LEN 752 203 #endif 204 205 #ifdef CONFIG_ESP_WIFI_MGMT_SBUF_NUM 206 #define WIFI_MGMT_SBUF_NUM CONFIG_ESP_WIFI_MGMT_SBUF_NUM 207 #else 208 #define WIFI_MGMT_SBUF_NUM 32 209 #endif 210 211 #if CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE 212 #define WIFI_STA_DISCONNECTED_PM_ENABLED true 213 #else 214 #define WIFI_STA_DISCONNECTED_PM_ENABLED false 215 #endif 216 217 #if CONFIG_ESP_WIFI_ENABLE_WPA3_SAE 218 #define WIFI_ENABLE_WPA3_SAE (1<<0) 219 #else 220 #define WIFI_ENABLE_WPA3_SAE 0 221 #endif 222 223 #if WIFI_CACHE_TX_BUFFER_NUM > 0 224 #define WIFI_ENABLE_CACHE_TX_BUFFER (1<<1) 225 #else 226 #define WIFI_ENABLE_CACHE_TX_BUFFER 0 227 #endif 228 229 #if CONFIG_ESP_WIFI_FTM_INITIATOR_SUPPORT 230 #define WIFI_FTM_INITIATOR (1<<2) 231 #else 232 #define WIFI_FTM_INITIATOR 0 233 #endif 234 235 #if CONFIG_ESP_WIFI_FTM_RESPONDER_SUPPORT 236 #define WIFI_FTM_RESPONDER (1<<3) 237 #else 238 #define WIFI_FTM_RESPONDER 0 239 #endif 240 241 #if CONFIG_ESP_WIFI_GCMP_SUPPORT 242 #define WIFI_ENABLE_GCMP (1<<4) 243 #else 244 #define WIFI_ENABLE_GCMP 0 245 #endif 246 247 #if CONFIG_ESP_WIFI_GMAC_SUPPORT 248 #define WIFI_ENABLE_GMAC (1<<5) 249 #else 250 #define WIFI_ENABLE_GMAC 0 251 #endif 252 253 #if CONFIG_ESP_WIFI_11R_SUPPORT 254 #define WIFI_ENABLE_11R (1<<6) 255 #else 256 #define WIFI_ENABLE_11R 0 257 #endif 258 259 #if CONFIG_ESP_WIFI_ENTERPRISE_SUPPORT 260 #define WIFI_ENABLE_ENTERPRISE (1<<7) 261 #else 262 #define WIFI_ENABLE_ENTERPRISE 0 263 #endif 264 265 #define CONFIG_FEATURE_WPA3_SAE_BIT (1<<0) 266 #define CONFIG_FEATURE_CACHE_TX_BUF_BIT (1<<1) 267 #define CONFIG_FEATURE_FTM_INITIATOR_BIT (1<<2) 268 #define CONFIG_FEATURE_FTM_RESPONDER_BIT (1<<3) 269 #define CONFIG_FEATURE_GCMP_BIT (1<<4) 270 #define CONFIG_FEATURE_GMAC_BIT (1<<5) 271 #define CONFIG_FEATURE_11R_BIT (1<<6) 272 #define CONFIG_FEATURE_WIFI_ENT_BIT (1<<7) 273 274 /* Set additional WiFi features and capabilities */ 275 #define WIFI_FEATURE_CAPS (WIFI_ENABLE_WPA3_SAE | \ 276 WIFI_ENABLE_CACHE_TX_BUFFER | \ 277 WIFI_FTM_INITIATOR | \ 278 WIFI_FTM_RESPONDER | \ 279 WIFI_ENABLE_GCMP | \ 280 WIFI_ENABLE_GMAC | \ 281 WIFI_ENABLE_11R | \ 282 WIFI_ENABLE_ENTERPRISE) 283 284 #define WIFI_INIT_CONFIG_DEFAULT() { \ 285 .osi_funcs = &g_wifi_osi_funcs, \ 286 .wpa_crypto_funcs = g_wifi_default_wpa_crypto_funcs, \ 287 .static_rx_buf_num = CONFIG_ESP_WIFI_STATIC_RX_BUFFER_NUM,\ 288 .dynamic_rx_buf_num = CONFIG_ESP_WIFI_DYNAMIC_RX_BUFFER_NUM,\ 289 .tx_buf_type = CONFIG_ESP_WIFI_TX_BUFFER_TYPE,\ 290 .static_tx_buf_num = WIFI_STATIC_TX_BUFFER_NUM,\ 291 .dynamic_tx_buf_num = WIFI_DYNAMIC_TX_BUFFER_NUM,\ 292 .rx_mgmt_buf_type = CONFIG_ESP_WIFI_DYNAMIC_RX_MGMT_BUF,\ 293 .rx_mgmt_buf_num = WIFI_RX_MGMT_BUF_NUM_DEF,\ 294 .cache_tx_buf_num = WIFI_CACHE_TX_BUFFER_NUM,\ 295 .csi_enable = WIFI_CSI_ENABLED,\ 296 .ampdu_rx_enable = WIFI_AMPDU_RX_ENABLED,\ 297 .ampdu_tx_enable = WIFI_AMPDU_TX_ENABLED,\ 298 .amsdu_tx_enable = WIFI_AMSDU_TX_ENABLED,\ 299 .nvs_enable = WIFI_NVS_ENABLED,\ 300 .nano_enable = WIFI_NANO_FORMAT_ENABLED,\ 301 .rx_ba_win = WIFI_DEFAULT_RX_BA_WIN,\ 302 .wifi_task_core_id = WIFI_TASK_CORE_ID,\ 303 .beacon_max_len = WIFI_SOFTAP_BEACON_MAX_LEN, \ 304 .mgmt_sbuf_num = WIFI_MGMT_SBUF_NUM, \ 305 .feature_caps = WIFI_FEATURE_CAPS, \ 306 .sta_disconnected_pm = WIFI_STA_DISCONNECTED_PM_ENABLED, \ 307 .espnow_max_encrypt_num = 2, \ 308 .magic = WIFI_INIT_CONFIG_MAGIC\ 309 } 310 311 /** 312 * @brief Initialize WiFi 313 * Allocate resource for WiFi driver, such as WiFi control structure, RX/TX buffer, 314 * WiFi NVS structure etc. This WiFi also starts WiFi task 315 * 316 * @attention 1. This API must be called before all other WiFi API can be called 317 * @attention 2. Always use WIFI_INIT_CONFIG_DEFAULT macro to initialize the configuration to default values, this can 318 * guarantee all the fields get correct value when more fields are added into wifi_init_config_t 319 * in future release. If you want to set your own initial values, overwrite the default values 320 * which are set by WIFI_INIT_CONFIG_DEFAULT. Please be notified that the field 'magic' of 321 * wifi_init_config_t should always be WIFI_INIT_CONFIG_MAGIC! 322 * 323 * @param config pointer to WiFi initialized configuration structure; can point to a temporary variable. 324 * 325 * @return 326 * - ESP_OK: succeed 327 * - ESP_ERR_NO_MEM: out of memory 328 * - others: refer to error code esp_err.h 329 */ 330 esp_err_t esp_wifi_init(const wifi_init_config_t *config); 331 332 /** 333 * @brief Deinit WiFi 334 * Free all resource allocated in esp_wifi_init and stop WiFi task 335 * 336 * @attention 1. This API should be called if you want to remove WiFi driver from the system 337 * 338 * @return 339 * - ESP_OK: succeed 340 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 341 */ 342 esp_err_t esp_wifi_deinit(void); 343 344 /** 345 * @brief Set the WiFi operating mode 346 * 347 * Set the WiFi operating mode as station, soft-AP, station+soft-AP or NAN. 348 * The default mode is station mode. 349 * 350 * @param mode WiFi operating mode 351 * 352 * @return 353 * - ESP_OK: succeed 354 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 355 * - ESP_ERR_INVALID_ARG: invalid argument 356 * - others: refer to error code in esp_err.h 357 */ 358 esp_err_t esp_wifi_set_mode(wifi_mode_t mode); 359 360 /** 361 * @brief Get current operating mode of WiFi 362 * 363 * @param[out] mode store current WiFi mode 364 * 365 * @return 366 * - ESP_OK: succeed 367 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 368 * - ESP_ERR_INVALID_ARG: invalid argument 369 */ 370 esp_err_t esp_wifi_get_mode(wifi_mode_t *mode); 371 372 /** 373 * @brief Start WiFi according to current configuration 374 * If mode is WIFI_MODE_STA, it creates station control block and starts station 375 * If mode is WIFI_MODE_AP, it creates soft-AP control block and starts soft-AP 376 * If mode is WIFI_MODE_APSTA, it creates soft-AP and station control block and starts soft-AP and station 377 * If mode is WIFI_MODE_NAN, it creates NAN control block and starts NAN 378 * 379 * @return 380 * - ESP_OK: succeed 381 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 382 * - ESP_ERR_INVALID_ARG: It doesn't normally happen, the function called inside the API was passed invalid argument, user should check if the wifi related config is correct 383 * - ESP_ERR_NO_MEM: out of memory 384 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 385 * - ESP_FAIL: other WiFi internal errors 386 */ 387 esp_err_t esp_wifi_start(void); 388 389 /** 390 * @brief Stop WiFi 391 * If mode is WIFI_MODE_STA, it stops station and frees station control block 392 * If mode is WIFI_MODE_AP, it stops soft-AP and frees soft-AP control block 393 * If mode is WIFI_MODE_APSTA, it stops station/soft-AP and frees station/soft-AP control block 394 * If mode is WIFI_MODE_NAN, it stops NAN and frees NAN control block 395 * 396 * @return 397 * - ESP_OK: succeed 398 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 399 */ 400 esp_err_t esp_wifi_stop(void); 401 402 /** 403 * @brief Restore WiFi stack persistent settings to default values 404 * 405 * This function will reset settings made using the following APIs: 406 * - esp_wifi_set_bandwidth, 407 * - esp_wifi_set_protocol, 408 * - esp_wifi_set_config related 409 * - esp_wifi_set_mode 410 * 411 * @return 412 * - ESP_OK: succeed 413 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 414 */ 415 esp_err_t esp_wifi_restore(void); 416 417 /** 418 * @brief Connect WiFi station to the AP. 419 * 420 * @attention 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode 421 * @attention 2. If station interface is connected to an AP, call esp_wifi_disconnect to disconnect. 422 * @attention 3. The scanning triggered by esp_wifi_scan_start() will not be effective until connection between device and the AP is established. 423 * If device is scanning and connecting at the same time, it will abort scanning and return a warning message and error 424 * number ESP_ERR_WIFI_STATE. 425 * @attention 4. This API attempts to connect to an Access Point (AP) only once. To enable reconnection in case of a connection failure, please use 426 * the 'failure_retry_cnt' feature in the 'wifi_sta_config_t'. Users are suggested to implement reconnection logic in their application 427 * for scenarios where the specified AP does not exist, or reconnection is desired after the device has received a disconnect event. 428 * 429 * @return 430 * - ESP_OK: succeed 431 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 432 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 433 * - ESP_ERR_WIFI_MODE: WiFi mode error 434 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 435 * - ESP_ERR_WIFI_SSID: SSID of AP which station connects is invalid 436 */ 437 esp_err_t esp_wifi_connect(void); 438 439 /** 440 * @brief Disconnect WiFi station from the AP. 441 * 442 * @return 443 * - ESP_OK: succeed 444 * - ESP_ERR_WIFI_NOT_INIT: WiFi was not initialized by esp_wifi_init 445 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 446 * - ESP_FAIL: other WiFi internal errors 447 */ 448 esp_err_t esp_wifi_disconnect(void); 449 450 /** 451 * @brief Currently this API is just an stub API 452 * 453 454 * @return 455 * - ESP_OK: succeed 456 * - others: fail 457 */ 458 esp_err_t esp_wifi_clear_fast_connect(void); 459 460 /** 461 * @brief deauthenticate all stations or associated id equals to aid 462 * 463 * @param aid when aid is 0, deauthenticate all stations, otherwise deauthenticate station whose associated id is aid 464 * 465 * @return 466 * - ESP_OK: succeed 467 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 468 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 469 * - ESP_ERR_INVALID_ARG: invalid argument 470 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 471 */ 472 esp_err_t esp_wifi_deauth_sta(uint16_t aid); 473 474 /** 475 * @brief Scan all available APs. 476 * 477 * @attention If this API is called, the found APs are stored in WiFi driver dynamic allocated memory. And then 478 * can be freed in esp_wifi_scan_get_ap_records(), esp_wifi_scan_get_ap_record() or esp_wifi_clear_ap_list(), 479 * so call any one to free the memory once the scan is done. 480 * @attention The values of maximum active scan time and passive scan time per channel are limited to 1500 milliseconds. 481 * Values above 1500ms may cause station to disconnect from AP and are not recommended. 482 * 483 * @param config configuration settings for scanning, if set to NULL default settings will be used 484 * of which default values are show_hidden:false, scan_type:active, scan_time.active.min:0, 485 * scan_time.active.max:120 miliseconds, scan_time.passive:360 miliseconds 486 * 487 * @param block if block is true, this API will block the caller until the scan is done, otherwise 488 * it will return immediately 489 * 490 * @return 491 * - ESP_OK: succeed 492 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 493 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 494 * - ESP_ERR_WIFI_TIMEOUT: blocking scan is timeout 495 * - ESP_ERR_WIFI_STATE: wifi still connecting when invoke esp_wifi_scan_start 496 * - others: refer to error code in esp_err.h 497 */ 498 esp_err_t esp_wifi_scan_start(const wifi_scan_config_t *config, bool block); 499 500 /** 501 * @brief Stop the scan in process 502 * 503 * @return 504 * - ESP_OK: succeed 505 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 506 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 507 */ 508 esp_err_t esp_wifi_scan_stop(void); 509 510 /** 511 * @brief Get number of APs found in last scan 512 * 513 * @param[out] number store number of APs found in last scan 514 * 515 * @attention This API can only be called when the scan is completed, otherwise it may get wrong value. 516 * 517 * @return 518 * - ESP_OK: succeed 519 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 520 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 521 * - ESP_ERR_INVALID_ARG: invalid argument 522 */ 523 esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number); 524 525 /** 526 * @brief Get AP list found in last scan. 527 * 528 * @attention This API will free all memory occupied by scanned AP list. 529 * 530 * @param[inout] number As input param, it stores max AP number ap_records can hold. 531 * As output param, it receives the actual AP number this API returns. 532 * @param ap_records wifi_ap_record_t array to hold the found APs 533 * 534 * @return 535 * - ESP_OK: succeed 536 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 537 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 538 * - ESP_ERR_INVALID_ARG: invalid argument 539 * - ESP_ERR_NO_MEM: out of memory 540 */ 541 esp_err_t esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records); 542 543 /** 544 * @brief Get one AP record from the scanned AP list. 545 * 546 * @attention Different from esp_wifi_scan_get_ap_records(), this API only gets one AP record 547 * from the scanned AP list each time. This API will free the memory of one AP record, 548 * if the user doesn't get all records in the scannned AP list, then needs to call esp_wifi_clear_ap_list() 549 * to free the remaining memory. 550 * 551 * @param[out] ap_record pointer to one AP record 552 * 553 * @return 554 * - ESP_OK: succeed 555 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 556 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 557 * - ESP_ERR_INVALID_ARG: invalid argument 558 * - ESP_FAIL: scan APs is NULL, means all AP records fetched or no AP found 559 */ 560 esp_err_t esp_wifi_scan_get_ap_record(wifi_ap_record_t *ap_record); 561 562 /** 563 * @brief Clear AP list found in last scan 564 * 565 * @attention This API will free all memory occupied by scanned AP list. 566 * When the obtained AP list fails, AP records must be cleared,otherwise it may cause memory leakage. 567 * 568 * @return 569 * - ESP_OK: succeed 570 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 571 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 572 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 573 * - ESP_ERR_INVALID_ARG: It doesn't normally happen, the function called inside the API was passed invalid argument, user should check if the wifi related config is correct 574 */ 575 esp_err_t esp_wifi_clear_ap_list(void); 576 577 578 /** 579 * @brief Get information of AP to which the device is associated with 580 * 581 * @attention When the obtained country information is empty, it means that the AP does not carry country information 582 * 583 * @param ap_info the wifi_ap_record_t to hold AP information 584 * sta can get the connected ap's phy mode info through the struct member 585 * phy_11b，phy_11g，phy_11n，phy_lr in the wifi_ap_record_t struct. 586 * For example, phy_11b = 1 imply that ap support 802.11b mode 587 * 588 * @return 589 * - ESP_OK: succeed 590 * - ESP_ERR_WIFI_CONN: The station interface don't initialized 591 * - ESP_ERR_WIFI_NOT_CONNECT: The station is in disconnect status 592 */ 593 esp_err_t esp_wifi_sta_get_ap_info(wifi_ap_record_t *ap_info); 594 595 /** 596 * @brief Set current WiFi power save type 597 * 598 * @attention Default power save type is WIFI_PS_MIN_MODEM. 599 * 600 * @param type power save type 601 * 602 * @return ESP_OK: succeed 603 */ 604 esp_err_t esp_wifi_set_ps(wifi_ps_type_t type); 605 606 /** 607 * @brief Get current WiFi power save type 608 * 609 * @attention Default power save type is WIFI_PS_MIN_MODEM. 610 * 611 * @param[out] type: store current power save type 612 * 613 * @return ESP_OK: succeed 614 */ 615 esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type); 616 617 /** 618 * @brief Set protocol type of specified interface 619 * The default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N). 620 * if CONFIG_SOC_WIFI_HE_SUPPORT, the default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_11AX). 621 * 622 * @attention Support 802.11b or 802.11bg or 802.11bgn or 802.11bgnax or LR mode 623 * 624 * @param ifx interfaces 625 * @param protocol_bitmap WiFi protocol bitmap 626 * 627 * @return 628 * - ESP_OK: succeed 629 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 630 * - ESP_ERR_WIFI_IF: invalid interface 631 * - others: refer to error codes in esp_err.h 632 */ 633 esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap); 634 635 /** 636 * @brief Get the current protocol bitmap of the specified interface 637 * 638 * @param ifx interface 639 * @param[out] protocol_bitmap store current WiFi protocol bitmap of interface ifx 640 * 641 * @return 642 * - ESP_OK: succeed 643 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 644 * - ESP_ERR_WIFI_IF: invalid interface 645 * - ESP_ERR_INVALID_ARG: invalid argument 646 * - others: refer to error codes in esp_err.h 647 */ 648 esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap); 649 650 /** 651 * @brief Set the bandwidth of specified interface 652 * 653 * @attention 1. API return false if try to configure an interface that is not enabled 654 * @attention 2. WIFI_BW_HT40 is supported only when the interface support 11N 655 * 656 * @param ifx interface to be configured 657 * @param bw bandwidth 658 * 659 * @return 660 * - ESP_OK: succeed 661 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 662 * - ESP_ERR_WIFI_IF: invalid interface 663 * - ESP_ERR_INVALID_ARG: invalid argument 664 * - others: refer to error codes in esp_err.h 665 */ 666 esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw); 667 668 /** 669 * @brief Get the bandwidth of specified interface 670 * 671 * @attention 1. API return false if try to get a interface that is not enable 672 * 673 * @param ifx interface to be configured 674 * @param[out] bw store bandwidth of interface ifx 675 * 676 * @return 677 * - ESP_OK: succeed 678 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 679 * - ESP_ERR_WIFI_IF: invalid interface 680 * - ESP_ERR_INVALID_ARG: invalid argument 681 */ 682 esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw); 683 684 /** 685 * @brief Set primary/secondary channel of device 686 * 687 * @attention 1. This API should be called after esp_wifi_start() and before esp_wifi_stop() 688 * @attention 2. When device is in STA mode, this API should not be called when STA is scanning or connecting to an external AP 689 * @attention 3. When device is in softAP mode, this API should not be called when softAP has connected to external STAs 690 * @attention 4. When device is in STA+softAP mode, this API should not be called when in the scenarios described above 691 * @attention 5. The channel info set by this API will not be stored in NVS. So If you want to remeber the channel used before wifi stop, 692 * you need to call this API again after wifi start, or you can call `esp_wifi_set_config()` to store the channel info in NVS. 693 * 694 * @param primary for HT20, primary is the channel number, for HT40, primary is the primary channel 695 * @param second for HT20, second is ignored, for HT40, second is the second channel 696 * 697 * @return 698 * - ESP_OK: succeed 699 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 700 * - ESP_ERR_WIFI_IF: invalid interface 701 * - ESP_ERR_INVALID_ARG: invalid argument 702 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 703 */ 704 esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second); 705 706 /** 707 * @brief Get the primary/secondary channel of device 708 * 709 * @attention 1. API return false if try to get a interface that is not enable 710 * 711 * @param primary store current primary channel 712 * @param[out] second store current second channel 713 * 714 * @return 715 * - ESP_OK: succeed 716 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 717 * - ESP_ERR_INVALID_ARG: invalid argument 718 */ 719 esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second); 720 721 /** 722 * @brief configure country info 723 * 724 * @attention 1. It is discouraged to call this API since this doesn't validate the per-country rules, 725 * it's up to the user to fill in all fields according to local regulations. 726 * Please use esp_wifi_set_country_code instead. 727 * @attention 2. The default country is "01" (world safe mode) {.cc="01", .schan=1, .nchan=11, .policy=WIFI_COUNTRY_POLICY_AUTO}. 728 * @attention 3. The third octet of country code string is one of the following: ' ', 'O', 'I', 'X', otherwise it is considered as ' '. 729 * @attention 4. When the country policy is WIFI_COUNTRY_POLICY_AUTO, the country info of the AP to which 730 * the station is connected is used. E.g. if the configured country info is {.cc="US", .schan=1, .nchan=11} 731 * and the country info of the AP to which the station is connected is {.cc="JP", .schan=1, .nchan=14} 732 * then the country info that will be used is {.cc="JP", .schan=1, .nchan=14}. If the station disconnected 733 * from the AP the country info is set back to the country info of the station automatically, 734 * {.cc="US", .schan=1, .nchan=11} in the example. 735 * @attention 5. When the country policy is WIFI_COUNTRY_POLICY_MANUAL, then the configured country info is used always. 736 * @attention 6. When the country info is changed because of configuration or because the station connects to a different 737 * external AP, the country IE in probe response/beacon of the soft-AP is also changed. 738 * @attention 7. The country configuration is stored into flash. 739 * @attention 8. When this API is called, the PHY init data will switch to the PHY init data type corresponding to the 740 * country info. 741 * 742 * @param country the configured country info 743 * 744 * @return 745 * - ESP_OK: succeed 746 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 747 * - ESP_ERR_INVALID_ARG: invalid argument 748 */ 749 esp_err_t esp_wifi_set_country(const wifi_country_t *country); 750 751 /** 752 * @brief get the current country info 753 * 754 * @param country country info 755 * 756 * @return 757 * - ESP_OK: succeed 758 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 759 * - ESP_ERR_INVALID_ARG: invalid argument 760 */ 761 esp_err_t esp_wifi_get_country(wifi_country_t *country); 762 763 764 /** 765 * @brief Set MAC address of WiFi station, soft-AP or NAN interface. 766 * 767 * @attention 1. This API can only be called when the interface is disabled 768 * @attention 2. Above mentioned interfaces have different MAC addresses, do not set them to be the same. 769 * @attention 3. The bit 0 of the first byte of MAC address can not be 1. For example, the MAC address 770 * can set to be "1a:XX:XX:XX:XX:XX", but can not be "15:XX:XX:XX:XX:XX". 771 * 772 * @param ifx interface 773 * @param mac the MAC address 774 * 775 * @return 776 * - ESP_OK: succeed 777 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 778 * - ESP_ERR_INVALID_ARG: invalid argument 779 * - ESP_ERR_WIFI_IF: invalid interface 780 * - ESP_ERR_WIFI_MAC: invalid mac address 781 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 782 * - others: refer to error codes in esp_err.h 783 */ 784 esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, const uint8_t mac[6]); 785 786 /** 787 * @brief Get mac of specified interface 788 * 789 * @param ifx interface 790 * @param[out] mac store mac of the interface ifx 791 * 792 * @return 793 * - ESP_OK: succeed 794 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 795 * - ESP_ERR_INVALID_ARG: invalid argument 796 * - ESP_ERR_WIFI_IF: invalid interface 797 */ 798 esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6]); 799 800 /** 801 * @brief The RX callback function in the promiscuous mode. 802 * Each time a packet is received, the callback function will be called. 803 * 804 * @param buf Data received. Type of data in buffer (wifi_promiscuous_pkt_t or wifi_pkt_rx_ctrl_t) indicated by 'type' parameter. 805 * @param type promiscuous packet type. 806 * 807 */ 808 typedef void (* wifi_promiscuous_cb_t)(void *buf, wifi_promiscuous_pkt_type_t type); 809 810 /** 811 * @brief Register the RX callback function in the promiscuous mode. 812 * 813 * Each time a packet is received, the registered callback function will be called. 814 * 815 * @param cb callback 816 * 817 * @return 818 * - ESP_OK: succeed 819 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 820 */ 821 esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb); 822 823 /** 824 * @brief Enable the promiscuous mode. 825 * 826 * @param en false - disable, true - enable 827 * 828 * @return 829 * - ESP_OK: succeed 830 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 831 */ 832 esp_err_t esp_wifi_set_promiscuous(bool en); 833 834 /** 835 * @brief Get the promiscuous mode. 836 * 837 * @param[out] en store the current status of promiscuous mode 838 * 839 * @return 840 * - ESP_OK: succeed 841 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 842 * - ESP_ERR_INVALID_ARG: invalid argument 843 */ 844 esp_err_t esp_wifi_get_promiscuous(bool *en); 845 846 /** 847 * @brief Enable the promiscuous mode packet type filter. 848 * 849 * @note The default filter is to filter all packets except WIFI_PKT_MISC 850 * 851 * @param filter the packet type filtered in promiscuous mode. 852 * 853 * @return 854 * - ESP_OK: succeed 855 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 856 */ 857 esp_err_t esp_wifi_set_promiscuous_filter(const wifi_promiscuous_filter_t *filter); 858 859 /** 860 * @brief Get the promiscuous filter. 861 * 862 * @param[out] filter store the current status of promiscuous filter 863 * 864 * @return 865 * - ESP_OK: succeed 866 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 867 * - ESP_ERR_INVALID_ARG: invalid argument 868 */ 869 esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter); 870 871 /** 872 * @brief Enable subtype filter of the control packet in promiscuous mode. 873 * 874 * @note The default filter is to filter none control packet. 875 * 876 * @param filter the subtype of the control packet filtered in promiscuous mode. 877 * 878 * @return 879 * - ESP_OK: succeed 880 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 881 */ 882 esp_err_t esp_wifi_set_promiscuous_ctrl_filter(const wifi_promiscuous_filter_t *filter); 883 884 /** 885 * @brief Get the subtype filter of the control packet in promiscuous mode. 886 * 887 * @param[out] filter store the current status of subtype filter of the control packet in promiscuous mode 888 * 889 * @return 890 * - ESP_OK: succeed 891 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 892 * - ESP_ERR_INVALID_ARG: invalid argument 893 */ 894 esp_err_t esp_wifi_get_promiscuous_ctrl_filter(wifi_promiscuous_filter_t *filter); 895 896 /** 897 * @brief Set the configuration of the STA, AP or NAN 898 * 899 * @attention 1. This API can be called only when specified interface is enabled, otherwise, API fail 900 * @attention 2. For station configuration, bssid_set needs to be 0; and it needs to be 1 only when users need to check the MAC address of the AP. 901 * @attention 3. ESP devices are limited to only one channel, so when in the soft-AP+station mode, the soft-AP will adjust its channel automatically to be the same as 902 * the channel of the station. 903 * @attention 4. The configuration will be stored in NVS for station and soft-AP 904 * 905 * @param interface interface 906 * @param conf station, soft-AP or NAN configuration 907 * 908 * @return 909 * - ESP_OK: succeed 910 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 911 * - ESP_ERR_INVALID_ARG: invalid argument 912 * - ESP_ERR_WIFI_IF: invalid interface 913 * - ESP_ERR_WIFI_MODE: invalid mode 914 * - ESP_ERR_WIFI_PASSWORD: invalid password 915 * - ESP_ERR_WIFI_NVS: WiFi internal NVS error 916 * - others: refer to the error code in esp_err.h 917 */ 918 esp_err_t esp_wifi_set_config(wifi_interface_t interface, wifi_config_t *conf); 919 920 /** 921 * @brief Get configuration of specified interface 922 * 923 * @param interface interface 924 * @param[out] conf station or soft-AP configuration 925 * 926 * @return 927 * - ESP_OK: succeed 928 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 929 * - ESP_ERR_INVALID_ARG: invalid argument 930 * - ESP_ERR_WIFI_IF: invalid interface 931 */ 932 esp_err_t esp_wifi_get_config(wifi_interface_t interface, wifi_config_t *conf); 933 934 /** 935 * @brief Get STAs associated with soft-AP 936 * 937 * @attention SSC only API 938 * 939 * @param[out] sta station list 940 * ap can get the connected sta's phy mode info through the struct member 941 * phy_11b，phy_11g，phy_11n，phy_lr in the wifi_sta_info_t struct. 942 * For example, phy_11b = 1 imply that sta support 802.11b mode 943 * 944 * @return 945 * - ESP_OK: succeed 946 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 947 * - ESP_ERR_INVALID_ARG: invalid argument 948 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 949 * - ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid 950 */ 951 esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta); 952 953 /** 954 * @brief Get AID of STA connected with soft-AP 955 * 956 * @param mac STA's mac address 957 * @param[out] aid Store the AID corresponding to STA mac 958 * 959 * @return 960 * - ESP_OK: succeed 961 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 962 * - ESP_ERR_INVALID_ARG: invalid argument 963 * - ESP_ERR_NOT_FOUND: Requested resource not found 964 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 965 * - ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid 966 */ 967 esp_err_t esp_wifi_ap_get_sta_aid(const uint8_t mac[6], uint16_t *aid); 968 969 /** 970 * @brief Set the WiFi API configuration storage type 971 * 972 * @attention 1. The default value is WIFI_STORAGE_FLASH 973 * 974 * @param storage : storage type 975 * 976 * @return 977 * - ESP_OK: succeed 978 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 979 * - ESP_ERR_INVALID_ARG: invalid argument 980 */ 981 esp_err_t esp_wifi_set_storage(wifi_storage_t storage); 982 983 /** 984 * @brief Function signature for received Vendor-Specific Information Element callback. 985 * @param ctx Context argument, as passed to esp_wifi_set_vendor_ie_cb() when registering callback. 986 * @param type Information element type, based on frame type received. 987 * @param sa Source 802.11 address. 988 * @param vnd_ie Pointer to the vendor specific element data received. 989 * @param rssi Received signal strength indication. 990 */ 991 typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const vendor_ie_data_t *vnd_ie, int rssi); 992 993 /** 994 * @brief Set 802.11 Vendor-Specific Information Element 995 * 996 * @param enable If true, specified IE is enabled. If false, specified IE is removed. 997 * @param type Information Element type. Determines the frame type to associate with the IE. 998 * @param idx Index to set or clear. Each IE type can be associated with up to two elements (indices 0 & 1). 999 * @param vnd_ie Pointer to vendor specific element data. First 6 bytes should be a header with fields matching vendor_ie_data_t. 1000 * If enable is false, this argument is ignored and can be NULL. Data does not need to remain valid after the function returns. 1001 * 1002 * @return 1003 * - ESP_OK: succeed 1004 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init() 1005 * - ESP_ERR_INVALID_ARG: Invalid argument, including if first byte of vnd_ie is not WIFI_VENDOR_IE_ELEMENT_ID (0xDD) 1006 * or second byte is an invalid length. 1007 * - ESP_ERR_NO_MEM: Out of memory 1008 */ 1009 esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, const void *vnd_ie); 1010 1011 /** 1012 * @brief Register Vendor-Specific Information Element monitoring callback. 1013 * 1014 * @param cb Callback function 1015 * @param ctx Context argument, passed to callback function. 1016 * 1017 * @return 1018 * - ESP_OK: succeed 1019 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1020 */ 1021 esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx); 1022 1023 /** 1024 * @brief Set maximum transmitting power after WiFi start. 1025 * 1026 * @attention 1. Maximum power before wifi startup is limited by PHY init data bin. 1027 * @attention 2. The value set by this API will be mapped to the max_tx_power of the structure wifi_country_t variable. 1028 * @attention 3. Mapping Table {Power, max_tx_power} = {{8, 2}, {20, 5}, {28, 7}, {34, 8}, {44, 11}, 1029 * {52, 13}, {56, 14}, {60, 15}, {66, 16}, {72, 18}, {80, 20}}. 1030 * @attention 4. Param power unit is 0.25dBm, range is [8, 84] corresponding to 2dBm - 20dBm. 1031 * @attention 5. Relationship between set value and actual value. As follows: {set value range, actual value} = {{[8, 19],8}, {[20, 27],20}, {[28, 33],28}, {[34, 43],34}, {[44, 51],44}, {[52, 55],52}, {[56, 59],56}, {[60, 65],60}, {[66, 71],66}, {[72, 79],72}, {[80, 84],80}}. 1032 * 1033 * @param power Maximum WiFi transmitting power. 1034 * 1035 * @return 1036 * - ESP_OK: succeed 1037 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1038 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1039 * - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is out of range 1040 */ 1041 esp_err_t esp_wifi_set_max_tx_power(int8_t power); 1042 1043 /** 1044 * @brief Get maximum transmiting power after WiFi start 1045 * 1046 * @param power Maximum WiFi transmitting power, unit is 0.25dBm. 1047 * 1048 * @return 1049 * - ESP_OK: succeed 1050 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1051 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1052 * - ESP_ERR_INVALID_ARG: invalid argument 1053 */ 1054 esp_err_t esp_wifi_get_max_tx_power(int8_t *power); 1055 1056 /** 1057 * @brief Set mask to enable or disable some WiFi events 1058 * 1059 * @attention 1. Mask can be created by logical OR of various WIFI_EVENT_MASK_ constants. 1060 * Events which have corresponding bit set in the mask will not be delivered to the system event handler. 1061 * @attention 2. Default WiFi event mask is WIFI_EVENT_MASK_AP_PROBEREQRECVED. 1062 * @attention 3. There may be lots of stations sending probe request data around. 1063 * Don't unmask this event unless you need to receive probe request data. 1064 * 1065 * @param mask WiFi event mask. 1066 * 1067 * @return 1068 * - ESP_OK: succeed 1069 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1070 */ 1071 esp_err_t esp_wifi_set_event_mask(uint32_t mask); 1072 1073 /** 1074 * @brief Get mask of WiFi events 1075 * 1076 * @param mask WiFi event mask. 1077 * 1078 * @return 1079 * - ESP_OK: succeed 1080 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1081 * - ESP_ERR_INVALID_ARG: invalid argument 1082 */ 1083 esp_err_t esp_wifi_get_event_mask(uint32_t *mask); 1084 1085 /** 1086 * @brief Send raw ieee80211 data 1087 * 1088 * @attention Currently only support for sending beacon/probe request/probe response/action and non-QoS 1089 * data frame 1090 * 1091 * @param ifx interface if the Wi-Fi mode is Station, the ifx should be WIFI_IF_STA. If the Wi-Fi 1092 * mode is SoftAP, the ifx should be WIFI_IF_AP. If the Wi-Fi mode is Station+SoftAP, the 1093 * ifx should be WIFI_IF_STA or WIFI_IF_AP. If the ifx is wrong, the API returns ESP_ERR_WIFI_IF. 1094 * @param buffer raw ieee80211 buffer 1095 * @param len the length of raw buffer, the len must be <= 1500 Bytes and >= 24 Bytes 1096 * @param en_sys_seq indicate whether use the internal sequence number. If en_sys_seq is false, the 1097 * sequence in raw buffer is unchanged, otherwise it will be overwritten by WiFi driver with 1098 * the system sequence number. 1099 * Generally, if esp_wifi_80211_tx is called before the Wi-Fi connection has been set up, both 1100 * en_sys_seq==true and en_sys_seq==false are fine. However, if the API is called after the Wi-Fi 1101 * connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_INVALID_ARG is returned. 1102 * 1103 * @return 1104 * - ESP_OK: success 1105 * - ESP_ERR_WIFI_IF: Invalid interface 1106 * - ESP_ERR_INVALID_ARG: Invalid parameter 1107 * - ESP_ERR_WIFI_NO_MEM: out of memory 1108 */ 1109 1110 esp_err_t esp_wifi_80211_tx(wifi_interface_t ifx, const void *buffer, int len, bool en_sys_seq); 1111 1112 /** 1113 * @brief The RX callback function of Channel State Information(CSI) data. 1114 * 1115 * Each time a CSI data is received, the callback function will be called. 1116 * 1117 * @param ctx context argument, passed to esp_wifi_set_csi_rx_cb() when registering callback function. 1118 * @param data CSI data received. The memory that it points to will be deallocated after callback function returns. 1119 * 1120 */ 1121 typedef void (* wifi_csi_cb_t)(void *ctx, wifi_csi_info_t *data); 1122 1123 1124 /** 1125 * @brief Register the RX callback function of CSI data. 1126 * 1127 * Each time a CSI data is received, the callback function will be called. 1128 * 1129 * @param cb callback 1130 * @param ctx context argument, passed to callback function 1131 * 1132 * @return 1133 * - ESP_OK: succeed 1134 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1135 */ 1136 1137 esp_err_t esp_wifi_set_csi_rx_cb(wifi_csi_cb_t cb, void *ctx); 1138 1139 /** 1140 * @brief Set CSI data configuration 1141 * 1142 * @param config configuration 1143 * 1144 * return 1145 * - ESP_OK: succeed 1146 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1147 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start or promiscuous mode is not enabled 1148 * - ESP_ERR_INVALID_ARG: invalid argument 1149 */ 1150 esp_err_t esp_wifi_set_csi_config(const wifi_csi_config_t *config); 1151 1152 /** 1153 * @brief Enable or disable CSI 1154 * 1155 * @param en true - enable, false - disable 1156 * 1157 * return 1158 * - ESP_OK: succeed 1159 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1160 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start or promiscuous mode is not enabled 1161 * - ESP_ERR_INVALID_ARG: invalid argument 1162 */ 1163 esp_err_t esp_wifi_set_csi(bool en); 1164 1165 /** 1166 * @brief Set antenna GPIO configuration 1167 * 1168 * @param config Antenna GPIO configuration. 1169 * 1170 * @return 1171 * - ESP_OK: succeed 1172 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1173 * - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc 1174 */ 1175 esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config); 1176 1177 /** 1178 * @brief Get current antenna GPIO configuration 1179 * 1180 * @param config Antenna GPIO configuration. 1181 * 1182 * @return 1183 * - ESP_OK: succeed 1184 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1185 * - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL 1186 */ 1187 esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config); 1188 1189 1190 /** 1191 * @brief Set antenna configuration 1192 * 1193 * @param config Antenna configuration. 1194 * 1195 * @return 1196 * - ESP_OK: succeed 1197 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1198 * - ESP_ERR_INVALID_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number 1199 */ 1200 esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config); 1201 1202 /** 1203 * @brief Get current antenna configuration 1204 * 1205 * @param config Antenna configuration. 1206 * 1207 * @return 1208 * - ESP_OK: succeed 1209 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1210 * - ESP_ERR_INVALID_ARG: invalid argument, e.g. parameter is NULL 1211 */ 1212 esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config); 1213 1214 /** 1215 * @brief Get the TSF time 1216 * In Station mode or SoftAP+Station mode if station is not connected or station doesn't receive at least 1217 * one beacon after connected, will return 0 1218 * 1219 * @attention Enabling power save may cause the return value inaccurate, except WiFi modem sleep 1220 * 1221 * @param interface The interface whose tsf_time is to be retrieved. 1222 * 1223 * @return 0 or the TSF time 1224 */ 1225 int64_t esp_wifi_get_tsf_time(wifi_interface_t interface); 1226 1227 /** 1228 * @brief Set the inactive time of the STA or AP 1229 * 1230 * @attention 1. For Station, If the station does not receive a beacon frame from the connected SoftAP during the inactive time, 1231 * disconnect from SoftAP. Default 6s. 1232 * @attention 2. For SoftAP, If the softAP doesn't receive any data from the connected STA during inactive time, 1233 * the softAP will force deauth the STA. Default is 300s. 1234 * @attention 3. The inactive time configuration is not stored into flash 1235 * 1236 * @param ifx interface to be configured. 1237 * @param sec Inactive time. Unit seconds. 1238 * 1239 * @return 1240 * - ESP_OK: succeed 1241 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1242 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1243 * - ESP_ERR_INVALID_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is less than 10. 1244 */ 1245 esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec); 1246 1247 /** 1248 * @brief Get inactive time of specified interface 1249 * 1250 * @param ifx Interface to be configured. 1251 * @param sec Inactive time. Unit seconds. 1252 * 1253 * @return 1254 * - ESP_OK: succeed 1255 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1256 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1257 * - ESP_ERR_INVALID_ARG: invalid argument 1258 */ 1259 esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec); 1260 1261 /** 1262 * @brief Dump WiFi statistics 1263 * 1264 * @param modules statistic modules to be dumped 1265 * 1266 * @return 1267 * - ESP_OK: succeed 1268 * - others: failed 1269 */ 1270 esp_err_t esp_wifi_statis_dump(uint32_t modules); 1271 1272 /** 1273 * @brief Set RSSI threshold, if average rssi gets lower than threshold, WiFi task will post event WIFI_EVENT_STA_BSS_RSSI_LOW. 1274 * 1275 * @attention If the user wants to receive another WIFI_EVENT_STA_BSS_RSSI_LOW event after receiving one, this API needs to be 1276 * called again with an updated/same RSSI threshold. 1277 * 1278 * @param rssi threshold value in dbm between -100 to 10 1279 * Note that in some rare cases where signal strength is very strong, rssi values can be slightly positive. 1280 * 1281 * @return 1282 * - ESP_OK: succeed 1283 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1284 * - ESP_ERR_INVALID_ARG: invalid argument 1285 */ 1286 esp_err_t esp_wifi_set_rssi_threshold(int32_t rssi); 1287 1288 /** 1289 * @brief Start an FTM Initiator session by sending FTM request 1290 * If successful, event WIFI_EVENT_FTM_REPORT is generated with the result of the FTM procedure 1291 * 1292 * @attention 1. Use this API only in Station mode. 1293 * @attention 2. If FTM is initiated on a different channel than Station is connected in or internal SoftAP is started in, 1294 * FTM defaults to a single burst in ASAP mode. 1295 * 1296 * @param cfg FTM Initiator session configuration 1297 * 1298 * @return 1299 * - ESP_OK: succeed 1300 * - others: failed 1301 */ 1302 esp_err_t esp_wifi_ftm_initiate_session(wifi_ftm_initiator_cfg_t *cfg); 1303 1304 /** 1305 * @brief End the ongoing FTM Initiator session 1306 * 1307 * @attention This API works only on FTM Initiator 1308 * 1309 * @return 1310 * - ESP_OK: succeed 1311 * - others: failed 1312 */ 1313 esp_err_t esp_wifi_ftm_end_session(void); 1314 1315 /** 1316 * @brief Set offset in cm for FTM Responder. An equivalent offset is calculated in picoseconds 1317 * and added in TOD of FTM Measurement frame (T1). 1318 * 1319 * @attention Use this API only in AP mode before performing FTM as responder 1320 * 1321 * @param offset_cm T1 Offset to be added in centimeters 1322 * 1323 * @return 1324 * - ESP_OK: succeed 1325 * - others: failed 1326 */ 1327 esp_err_t esp_wifi_ftm_resp_set_offset(int16_t offset_cm); 1328 1329 /** 1330 * @brief Get FTM measurements report copied into a user provided buffer. 1331 * 1332 * @attention 1. To get the FTM report, user first needs to allocate a buffer of size 1333 * (sizeof(wifi_ftm_report_entry_t) * num_entries) where the API will fill up to num_entries 1334 * valid FTM measurements in the buffer. Total number of entries can be found in the event 1335 * WIFI_EVENT_FTM_REPORT as ftm_report_num_entries 1336 * @attention 2. The internal FTM report is freed upon use of this API which means the API can only be used 1337 * once afer every FTM session initiated 1338 * @attention 3. Passing the buffer as NULL merely frees the FTM report 1339 * 1340 * @param report Pointer to the buffer for receiving the FTM report 1341 * @param num_entries Number of FTM report entries to be filled in the report 1342 * 1343 * @return 1344 * - ESP_OK: succeed 1345 * - others: failed 1346 */ 1347 esp_err_t esp_wifi_ftm_get_report(wifi_ftm_report_entry_t *report, uint8_t num_entries); 1348 1349 /** 1350 * @brief Enable or disable 11b rate of specified interface 1351 * 1352 * @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). 1353 * @attention 2. Only when really need to disable 11b rate call this API otherwise don't call this. 1354 * 1355 * @param ifx Interface to be configured. 1356 * @param disable true means disable 11b rate while false means enable 11b rate. 1357 * 1358 * @return 1359 * - ESP_OK: succeed 1360 * - others: failed 1361 */ 1362 esp_err_t esp_wifi_config_11b_rate(wifi_interface_t ifx, bool disable); 1363 1364 #define ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE 0 1365 /** 1366 * @brief Set wake interval for connectionless modules to wake up periodically. 1367 * 1368 * @attention 1. Only one wake interval for all connectionless modules. 1369 * @attention 2. This configuration could work at connected status. 1370 * When ESP_WIFI_STA_DISCONNECTED_PM_ENABLE is enabled, this configuration could work at disconnected status. 1371 * @attention 3. Event WIFI_EVENT_CONNECTIONLESS_MODULE_WAKE_INTERVAL_START would be posted each time wake interval starts. 1372 * @attention 4. Recommend to configure interval in multiples of hundred. (e.g. 100ms) 1373 * @attention 5. Recommend to configure interval to ESP_WIFI_CONNECTIONLESS_INTERVAL_DEFAULT_MODE to get stable performance at coexistence mode. 1374 * 1375 * @param wake_interval Milliseconds after would the chip wake up, from 1 to 65535. 1376 */ 1377 esp_err_t esp_wifi_connectionless_module_set_wake_interval(uint16_t wake_interval); 1378 1379 /** 1380 * @brief Request extra reference of Wi-Fi radio. 1381 * Wi-Fi keep active state(RF opened) to be able to receive packets. 1382 * 1383 * @attention Please pair the use of `esp_wifi_force_wakeup_acquire` with `esp_wifi_force_wakeup_release`. 1384 * 1385 * @return 1386 * - ESP_OK: succeed 1387 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1388 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1389 */ 1390 esp_err_t esp_wifi_force_wakeup_acquire(void); 1391 1392 /** 1393 * @brief Release extra reference of Wi-Fi radio. 1394 * Wi-Fi go to sleep state(RF closed) if no more use of radio. 1395 * 1396 * @attention Please pair the use of `esp_wifi_force_wakeup_acquire` with `esp_wifi_force_wakeup_release`. 1397 * 1398 * @return 1399 * - ESP_OK: succeed 1400 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1401 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1402 */ 1403 esp_err_t esp_wifi_force_wakeup_release(void); 1404 1405 /** 1406 * @brief configure country 1407 * 1408 * @attention 1. When ieee80211d_enabled, the country info of the AP to which 1409 * the station is connected is used. E.g. if the configured country is US 1410 * and the country info of the AP to which the station is connected is JP 1411 * then the country info that will be used is JP. If the station disconnected 1412 * from the AP the country info is set back to the country info of the station automatically, 1413 * US in the example. 1414 * @attention 2. When ieee80211d_enabled is disabled, then the configured country info is used always. 1415 * @attention 3. When the country info is changed because of configuration or because the station connects to a different 1416 * external AP, the country IE in probe response/beacon of the soft-AP is also changed. 1417 * @attention 4. The country configuration is stored into flash. 1418 * @attention 5. When this API is called, the PHY init data will switch to the PHY init data type corresponding to the 1419 * country info. 1420 * @attention 6. Supported country codes are "01"(world safe mode) "AT","AU","BE","BG","BR", 1421 * "CA","CH","CN","CY","CZ","DE","DK","EE","ES","FI","FR","GB","GR","HK","HR","HU", 1422 * "IE","IN","IS","IT","JP","KR","LI","LT","LU","LV","MT","MX","NL","NO","NZ","PL","PT", 1423 * "RO","SE","SI","SK","TW","US" 1424 * 1425 * @attention 7. When country code "01" (world safe mode) is set, SoftAP mode won't contain country IE. 1426 * @attention 8. The default country is "01" (world safe mode) and ieee80211d_enabled is TRUE. 1427 * @attention 9. The third octet of country code string is one of the following: ' ', 'O', 'I', 'X', otherwise it is considered as ' '. 1428 * 1429 * @param country the configured country ISO code 1430 * @param ieee80211d_enabled 802.11d is enabled or not 1431 * 1432 * @return 1433 * - ESP_OK: succeed 1434 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1435 * - ESP_ERR_INVALID_ARG: invalid argument 1436 */ 1437 esp_err_t esp_wifi_set_country_code(const char *country, bool ieee80211d_enabled); 1438 1439 /** 1440 * @brief get the current country code 1441 * 1442 * @param country country code 1443 * 1444 * @return 1445 * - ESP_OK: succeed 1446 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1447 * - ESP_ERR_INVALID_ARG: invalid argument 1448 */ 1449 esp_err_t esp_wifi_get_country_code(char *country); 1450 1451 /** 1452 * @brief Config 80211 tx rate of specified interface 1453 * 1454 * @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). 1455 * @attention 2. Can not set 80211 tx rate under 11A/11AC/11AX protocol, you can use esp_wifi_config_80211_tx instead. 1456 * 1457 * @param ifx Interface to be configured. 1458 * @param rate Phy rate to be configured. 1459 * 1460 * @return 1461 * - ESP_OK: succeed 1462 * - others: failed 1463 */ 1464 esp_err_t esp_wifi_config_80211_tx_rate(wifi_interface_t ifx, wifi_phy_rate_t rate); 1465 1466 /** 1467 * @brief Config 80211 tx rate and phymode of specified interface 1468 * 1469 * @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). 1470 1471 * 1472 * @param ifx Interface to be configured. 1473 * @param config rate_config to be configured. 1474 * 1475 * @return 1476 * - ESP_OK: succeed 1477 * - others: failed 1478 */ 1479 esp_err_t esp_wifi_config_80211_tx(wifi_interface_t ifx, wifi_tx_rate_config_t *config); 1480 1481 /** 1482 * @brief Disable PMF configuration for specified interface 1483 * 1484 * @attention This API should be called after esp_wifi_set_config() and before esp_wifi_start(). 1485 * 1486 * @param ifx Interface to be configured. 1487 * 1488 * @return 1489 * - ESP_OK: succeed 1490 * - others: failed 1491 */ 1492 esp_err_t esp_wifi_disable_pmf_config(wifi_interface_t ifx); 1493 1494 /** 1495 * @brief Get the Association id assigned to STA by AP 1496 * 1497 * @param[out] aid store the aid 1498 * 1499 * @attention aid = 0 if station is not connected to AP. 1500 * 1501 * @return 1502 * - ESP_OK: succeed 1503 */ 1504 esp_err_t esp_wifi_sta_get_aid(uint16_t *aid); 1505 1506 /** 1507 * @brief Get the negotiated phymode after connection. 1508 * 1509 * @param[out] phymode store the negotiated phymode. 1510 * 1511 * @return 1512 * - ESP_OK: succeed 1513 */ 1514 esp_err_t esp_wifi_sta_get_negotiated_phymode(wifi_phy_mode_t *phymode); 1515 1516 /** 1517 * @brief Config dynamic carrier sense 1518 * 1519 * @attention This API should be called after esp_wifi_start(). 1520 * 1521 * @param enabled Dynamic carrier sense is enabled or not. 1522 * 1523 * @return 1524 * - ESP_OK: succeed 1525 * - others: failed 1526 */ 1527 esp_err_t esp_wifi_set_dynamic_cs(bool enabled); 1528 1529 /** 1530 * @brief Get the rssi information of AP to which the device is associated with 1531 * 1532 * @attention 1. This API should be called after station connected to AP. 1533 * @attention 2. Use this API only in WIFI_MODE_STA or WIFI_MODE_APSTA mode. 1534 * 1535 * @param rssi store the rssi info received from last beacon. 1536 * 1537 * @return 1538 * - ESP_OK: succeed 1539 * - ESP_ERR_INVALID_ARG: invalid argument 1540 * - ESP_FAIL: failed 1541 */ 1542 esp_err_t esp_wifi_sta_get_rssi(int *rssi); 1543 1544 #if CONFIG_ESP_COEX_POWER_MANAGEMENT 1545 /** 1546 * @brief Enable Wi-Fi coexistence power management 1547 * 1548 * @attention This API should be called after esp_wifi_init(). 1549 * 1550 * @param enabled Wi-Fi coexistence power management is enabled or not. 1551 * 1552 * @return 1553 * - ESP_OK: succeed 1554 * - others: failed 1555 */ 1556 esp_err_t esp_wifi_coex_pwr_configure(bool enabled); 1557 #endif 1558 1559 #ifdef __cplusplus 1560 } 1561 #endif 1562 1563 #endif /* __ESP_WIFI_H__ */ 1564
