1 /* 2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 8 /* Notes about WiFi Programming 9 * 10 * The esp32 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 SYSTEM_EVENT_STA_CONNECTED, it will call tcpip_adapter_start() 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 60 #ifdef __cplusplus 61 extern "C" { 62 #endif 63 64 #define ESP_ERR_WIFI_NOT_INIT (ESP_ERR_WIFI_BASE + 1) /*!< WiFi driver was not installed by esp_wifi_init */ 65 #define ESP_ERR_WIFI_NOT_STARTED (ESP_ERR_WIFI_BASE + 2) /*!< WiFi driver was not started by esp_wifi_start */ 66 #define ESP_ERR_WIFI_NOT_STOPPED (ESP_ERR_WIFI_BASE + 3) /*!< WiFi driver was not stopped by esp_wifi_stop */ 67 #define ESP_ERR_WIFI_IF (ESP_ERR_WIFI_BASE + 4) /*!< WiFi interface error */ 68 #define ESP_ERR_WIFI_MODE (ESP_ERR_WIFI_BASE + 5) /*!< WiFi mode error */ 69 #define ESP_ERR_WIFI_STATE (ESP_ERR_WIFI_BASE + 6) /*!< WiFi internal state error */ 70 #define ESP_ERR_WIFI_CONN (ESP_ERR_WIFI_BASE + 7) /*!< WiFi internal control block of station or soft-AP error */ 71 #define ESP_ERR_WIFI_NVS (ESP_ERR_WIFI_BASE + 8) /*!< WiFi internal NVS module error */ 72 #define ESP_ERR_WIFI_MAC (ESP_ERR_WIFI_BASE + 9) /*!< MAC address is invalid */ 73 #define ESP_ERR_WIFI_SSID (ESP_ERR_WIFI_BASE + 10) /*!< SSID is invalid */ 74 #define ESP_ERR_WIFI_PASSWORD (ESP_ERR_WIFI_BASE + 11) /*!< Password is invalid */ 75 #define ESP_ERR_WIFI_TIMEOUT (ESP_ERR_WIFI_BASE + 12) /*!< Timeout error */ 76 #define ESP_ERR_WIFI_WAKE_FAIL (ESP_ERR_WIFI_BASE + 13) /*!< WiFi is in sleep state(RF closed) and wakeup fail */ 77 #define ESP_ERR_WIFI_WOULD_BLOCK (ESP_ERR_WIFI_BASE + 14) /*!< The caller would block */ 78 #define ESP_ERR_WIFI_NOT_CONNECT (ESP_ERR_WIFI_BASE + 15) /*!< Station still in disconnect status */ 79 80 #define ESP_ERR_WIFI_POST (ESP_ERR_WIFI_BASE + 18) /*!< Failed to post the event to WiFi task */ 81 #define ESP_ERR_WIFI_INIT_STATE (ESP_ERR_WIFI_BASE + 19) /*!< Invalid WiFi state when init/deinit is called */ 82 #define ESP_ERR_WIFI_STOP_STATE (ESP_ERR_WIFI_BASE + 20) /*!< Returned when WiFi is stopping */ 83 #define ESP_ERR_WIFI_NOT_ASSOC (ESP_ERR_WIFI_BASE + 21) /*!< The WiFi connection is not associated */ 84 #define ESP_ERR_WIFI_TX_DISALLOW (ESP_ERR_WIFI_BASE + 22) /*!< The WiFi TX is disallowed */ 85 86 /** 87 * @brief WiFi stack configuration parameters passed to esp_wifi_init call. 88 */ 89 typedef struct { 90 system_event_handler_t event_handler; /**< WiFi event handler */ 91 wifi_osi_funcs_t* osi_funcs; /**< WiFi OS functions */ 92 wpa_crypto_funcs_t wpa_crypto_funcs; /**< WiFi station crypto functions when connect */ 93 int static_rx_buf_num; /**< WiFi static RX buffer number */ 94 int dynamic_rx_buf_num; /**< WiFi dynamic RX buffer number */ 95 int tx_buf_type; /**< WiFi TX buffer type */ 96 int static_tx_buf_num; /**< WiFi static TX buffer number */ 97 int dynamic_tx_buf_num; /**< WiFi dynamic TX buffer number */ 98 int cache_tx_buf_num; /**< WiFi TX cache buffer number */ 99 int csi_enable; /**< WiFi channel state information enable flag */ 100 int ampdu_rx_enable; /**< WiFi AMPDU RX feature enable flag */ 101 int ampdu_tx_enable; /**< WiFi AMPDU TX feature enable flag */ 102 int amsdu_tx_enable; /**< WiFi AMSDU TX feature enable flag */ 103 int nvs_enable; /**< WiFi NVS flash enable flag */ 104 int nano_enable; /**< Nano option for printf/scan family enable flag */ 105 int rx_ba_win; /**< WiFi Block Ack RX window size */ 106 int wifi_task_core_id; /**< WiFi Task Core ID */ 107 int beacon_max_len; /**< WiFi softAP maximum length of the beacon */ 108 int mgmt_sbuf_num; /**< WiFi management short buffer number, the minimum value is 6, the maximum value is 32 */ 109 uint64_t feature_caps; /**< Enables additional WiFi features and capabilities */ 110 bool sta_disconnected_pm; /**< WiFi Power Management for station at disconnected status */ 111 int magic; /**< WiFi init magic number, it should be the last field */ 112 } wifi_init_config_t; 113 114 #ifdef CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM 115 #define WIFI_STATIC_TX_BUFFER_NUM CONFIG_ESP32_WIFI_STATIC_TX_BUFFER_NUM 116 #else 117 #define WIFI_STATIC_TX_BUFFER_NUM 0 118 #endif 119 120 #if (CONFIG_ESP32_SPIRAM_SUPPORT || CONFIG_ESP32S2_SPIRAM_SUPPORT || CONFIG_ESP32S3_SPIRAM_SUPPORT) 121 #define WIFI_CACHE_TX_BUFFER_NUM CONFIG_ESP32_WIFI_CACHE_TX_BUFFER_NUM 122 #else 123 #define WIFI_CACHE_TX_BUFFER_NUM 0 124 #endif 125 126 #ifdef CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM 127 #define WIFI_DYNAMIC_TX_BUFFER_NUM CONFIG_ESP32_WIFI_DYNAMIC_TX_BUFFER_NUM 128 #else 129 #define WIFI_DYNAMIC_TX_BUFFER_NUM 0 130 #endif 131 132 #if CONFIG_ESP32_WIFI_CSI_ENABLED 133 #define WIFI_CSI_ENABLED 1 134 #else 135 #define WIFI_CSI_ENABLED 0 136 #endif 137 138 #if CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED 139 #define WIFI_AMPDU_RX_ENABLED 1 140 #else 141 #define WIFI_AMPDU_RX_ENABLED 0 142 #endif 143 144 #if CONFIG_ESP32_WIFI_AMPDU_TX_ENABLED 145 #define WIFI_AMPDU_TX_ENABLED 1 146 #else 147 #define WIFI_AMPDU_TX_ENABLED 0 148 #endif 149 150 #if CONFIG_ESP32_WIFI_AMSDU_TX_ENABLED 151 #define WIFI_AMSDU_TX_ENABLED 1 152 #else 153 #define WIFI_AMSDU_TX_ENABLED 0 154 #endif 155 156 #if CONFIG_ESP32_WIFI_NVS_ENABLED 157 #define WIFI_NVS_ENABLED 1 158 #else 159 #define WIFI_NVS_ENABLED 0 160 #endif 161 162 #if CONFIG_NEWLIB_NANO_FORMAT 163 #define WIFI_NANO_FORMAT_ENABLED 1 164 #else 165 #define WIFI_NANO_FORMAT_ENABLED 0 166 #endif 167 168 extern const wpa_crypto_funcs_t g_wifi_default_wpa_crypto_funcs; 169 extern uint64_t g_wifi_feature_caps; 170 171 #define WIFI_INIT_CONFIG_MAGIC 0x1F2F3F4F 172 173 #ifdef CONFIG_ESP32_WIFI_AMPDU_RX_ENABLED 174 #define WIFI_DEFAULT_RX_BA_WIN CONFIG_ESP32_WIFI_RX_BA_WIN 175 #else 176 #define WIFI_DEFAULT_RX_BA_WIN 0 /* unused if ampdu_rx_enable == false */ 177 #endif 178 179 #if CONFIG_ESP32_WIFI_TASK_PINNED_TO_CORE_1 180 #define WIFI_TASK_CORE_ID 1 181 #else 182 #define WIFI_TASK_CORE_ID 0 183 #endif 184 185 #ifdef CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN 186 #define WIFI_SOFTAP_BEACON_MAX_LEN CONFIG_ESP32_WIFI_SOFTAP_BEACON_MAX_LEN 187 #else 188 #define WIFI_SOFTAP_BEACON_MAX_LEN 752 189 #endif 190 191 #ifdef CONFIG_ESP32_WIFI_MGMT_SBUF_NUM 192 #define WIFI_MGMT_SBUF_NUM CONFIG_ESP32_WIFI_MGMT_SBUF_NUM 193 #else 194 #define WIFI_MGMT_SBUF_NUM 32 195 #endif 196 197 #if CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE 198 #define WIFI_STA_DISCONNECTED_PM_ENABLED true 199 #else 200 #define WIFI_STA_DISCONNECTED_PM_ENABLED false 201 #endif 202 203 #define CONFIG_FEATURE_WPA3_SAE_BIT (1<<0) 204 #define CONFIG_FEATURE_CACHE_TX_BUF_BIT (1<<1) 205 #define CONFIG_FEATURE_FTM_INITIATOR_BIT (1<<2) 206 #define CONFIG_FEATURE_FTM_RESPONDER_BIT (1<<3) 207 208 #define WIFI_INIT_CONFIG_DEFAULT() { \ 209 .event_handler = &esp_event_send_internal, \ 210 .osi_funcs = &g_wifi_osi_funcs, \ 211 .wpa_crypto_funcs = g_wifi_default_wpa_crypto_funcs, \ 212 .static_rx_buf_num = CONFIG_ESP32_WIFI_STATIC_RX_BUFFER_NUM,\ 213 .dynamic_rx_buf_num = CONFIG_ESP32_WIFI_DYNAMIC_RX_BUFFER_NUM,\ 214 .tx_buf_type = CONFIG_ESP32_WIFI_TX_BUFFER_TYPE,\ 215 .static_tx_buf_num = WIFI_STATIC_TX_BUFFER_NUM,\ 216 .dynamic_tx_buf_num = WIFI_DYNAMIC_TX_BUFFER_NUM,\ 217 .cache_tx_buf_num = WIFI_CACHE_TX_BUFFER_NUM,\ 218 .csi_enable = WIFI_CSI_ENABLED,\ 219 .ampdu_rx_enable = WIFI_AMPDU_RX_ENABLED,\ 220 .ampdu_tx_enable = WIFI_AMPDU_TX_ENABLED,\ 221 .amsdu_tx_enable = WIFI_AMSDU_TX_ENABLED,\ 222 .nvs_enable = WIFI_NVS_ENABLED,\ 223 .nano_enable = WIFI_NANO_FORMAT_ENABLED,\ 224 .rx_ba_win = WIFI_DEFAULT_RX_BA_WIN,\ 225 .wifi_task_core_id = WIFI_TASK_CORE_ID,\ 226 .beacon_max_len = WIFI_SOFTAP_BEACON_MAX_LEN, \ 227 .mgmt_sbuf_num = WIFI_MGMT_SBUF_NUM, \ 228 .feature_caps = g_wifi_feature_caps, \ 229 .sta_disconnected_pm = WIFI_STA_DISCONNECTED_PM_ENABLED, \ 230 .magic = WIFI_INIT_CONFIG_MAGIC\ 231 } 232 233 /** 234 * @brief Initialize WiFi 235 * Allocate resource for WiFi driver, such as WiFi control structure, RX/TX buffer, 236 * WiFi NVS structure etc. This WiFi also starts WiFi task 237 * 238 * @attention 1. This API must be called before all other WiFi API can be called 239 * @attention 2. Always use WIFI_INIT_CONFIG_DEFAULT macro to initialize the configuration to default values, this can 240 * guarantee all the fields get correct value when more fields are added into wifi_init_config_t 241 * in future release. If you want to set your own initial values, overwrite the default values 242 * which are set by WIFI_INIT_CONFIG_DEFAULT. Please be notified that the field 'magic' of 243 * wifi_init_config_t should always be WIFI_INIT_CONFIG_MAGIC! 244 * 245 * @param config pointer to WiFi initialized configuration structure; can point to a temporary variable. 246 * 247 * @return 248 * - ESP_OK: succeed 249 * - ESP_ERR_NO_MEM: out of memory 250 * - others: refer to error code esp_err.h 251 */ 252 esp_err_t esp_wifi_init(const wifi_init_config_t *config); 253 254 /** 255 * @brief Deinit WiFi 256 * Free all resource allocated in esp_wifi_init and stop WiFi task 257 * 258 * @attention 1. This API should be called if you want to remove WiFi driver from the system 259 * 260 * @return 261 * - ESP_OK: succeed 262 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 263 */ 264 esp_err_t esp_wifi_deinit(void); 265 266 /** 267 * @brief Set the WiFi operating mode 268 * 269 * Set the WiFi operating mode as station, soft-AP or station+soft-AP, 270 * The default mode is station mode. 271 * 272 * @param mode WiFi operating mode 273 * 274 * @return 275 * - ESP_OK: succeed 276 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 277 * - ESP_ERR_INVALID_ARG: invalid argument 278 * - others: refer to error code in esp_err.h 279 */ 280 esp_err_t esp_wifi_set_mode(wifi_mode_t mode); 281 282 /** 283 * @brief Get current operating mode of WiFi 284 * 285 * @param[out] mode store current WiFi mode 286 * 287 * @return 288 * - ESP_OK: succeed 289 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 290 * - ESP_ERR_INVALID_ARG: invalid argument 291 */ 292 esp_err_t esp_wifi_get_mode(wifi_mode_t *mode); 293 294 /** 295 * @brief Start WiFi according to current configuration 296 * If mode is WIFI_MODE_STA, it create station control block and start station 297 * If mode is WIFI_MODE_AP, it create soft-AP control block and start soft-AP 298 * If mode is WIFI_MODE_APSTA, it create soft-AP and station control block and start soft-AP and station 299 * 300 * @return 301 * - ESP_OK: succeed 302 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 303 * - ESP_ERR_INVALID_ARG: invalid argument 304 * - ESP_ERR_NO_MEM: out of memory 305 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 306 * - ESP_FAIL: other WiFi internal errors 307 */ 308 esp_err_t esp_wifi_start(void); 309 310 /** 311 * @brief Stop WiFi 312 * If mode is WIFI_MODE_STA, it stop station and free station control block 313 * If mode is WIFI_MODE_AP, it stop soft-AP and free soft-AP control block 314 * If mode is WIFI_MODE_APSTA, it stop station/soft-AP and free station/soft-AP control block 315 * 316 * @return 317 * - ESP_OK: succeed 318 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 319 */ 320 esp_err_t esp_wifi_stop(void); 321 322 /** 323 * @brief Restore WiFi stack persistent settings to default values 324 * 325 * This function will reset settings made using the following APIs: 326 * - esp_wifi_set_bandwidth, 327 * - esp_wifi_set_protocol, 328 * - esp_wifi_set_config related 329 * - esp_wifi_set_mode 330 * 331 * @return 332 * - ESP_OK: succeed 333 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 334 */ 335 esp_err_t esp_wifi_restore(void); 336 337 /** 338 * @brief Connect the ESP32 WiFi station to the AP. 339 * 340 * @attention 1. This API only impact WIFI_MODE_STA or WIFI_MODE_APSTA mode 341 * @attention 2. If the ESP32 is connected to an AP, call esp_wifi_disconnect to disconnect. 342 * @attention 3. The scanning triggered by esp_wifi_start_scan() will not be effective until connection between ESP32 and the AP is established. 343 * If ESP32 is scanning and connecting at the same time, ESP32 will abort scanning and return a warning message and error 344 * number ESP_ERR_WIFI_STATE. 345 * If you want to do reconnection after ESP32 received disconnect event, remember to add the maximum retry time, otherwise the called 346 * scan will not work. This is especially true when the AP doesn't exist, and you still try reconnection after ESP32 received disconnect 347 * event with the reason code WIFI_REASON_NO_AP_FOUND. 348 * 349 * @return 350 * - ESP_OK: succeed 351 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 352 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 353 * - ESP_ERR_WIFI_CONN: WiFi internal error, station or soft-AP control block wrong 354 * - ESP_ERR_WIFI_SSID: SSID of AP which station connects is invalid 355 */ 356 esp_err_t esp_wifi_connect(void); 357 358 /** 359 * @brief Disconnect the ESP32 WiFi station from the AP. 360 * 361 * @return 362 * - ESP_OK: succeed 363 * - ESP_ERR_WIFI_NOT_INIT: WiFi was not initialized by esp_wifi_init 364 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 365 * - ESP_FAIL: other WiFi internal errors 366 */ 367 esp_err_t esp_wifi_disconnect(void); 368 369 /** 370 * @brief Currently this API is just an stub API 371 * 372 373 * @return 374 * - ESP_OK: succeed 375 * - others: fail 376 */ 377 esp_err_t esp_wifi_clear_fast_connect(void); 378 379 /** 380 * @brief deauthenticate all stations or associated id equals to aid 381 * 382 * @param aid when aid is 0, deauthenticate all stations, otherwise deauthenticate station whose associated id is aid 383 * 384 * @return 385 * - ESP_OK: succeed 386 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 387 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 388 * - ESP_ERR_INVALID_ARG: invalid argument 389 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 390 */ 391 esp_err_t esp_wifi_deauth_sta(uint16_t aid); 392 393 /** 394 * @brief Scan all available APs. 395 * 396 * @attention If this API is called, the found APs are stored in WiFi driver dynamic allocated memory and the 397 * will be freed in esp_wifi_scan_get_ap_records, so generally, call esp_wifi_scan_get_ap_records to cause 398 * the memory to be freed once the scan is done 399 * @attention The values of maximum active scan time and passive scan time per channel are limited to 1500 milliseconds. 400 * Values above 1500ms may cause station to disconnect from AP and are not recommended. 401 * 402 * @param config configuration of scanning 403 * @param block if block is true, this API will block the caller until the scan is done, otherwise 404 * it will return immediately 405 * 406 * @return 407 * - ESP_OK: succeed 408 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 409 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 410 * - ESP_ERR_WIFI_TIMEOUT: blocking scan is timeout 411 * - ESP_ERR_WIFI_STATE: wifi still connecting when invoke esp_wifi_scan_start 412 * - others: refer to error code in esp_err.h 413 */ 414 esp_err_t esp_wifi_scan_start(const wifi_scan_config_t *config, bool block); 415 416 /** 417 * @brief Stop the scan in process 418 * 419 * @return 420 * - ESP_OK: succeed 421 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 422 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 423 */ 424 esp_err_t esp_wifi_scan_stop(void); 425 426 /** 427 * @brief Get number of APs found in last scan 428 * 429 * @param[out] number store number of APIs found in last scan 430 * 431 * @attention This API can only be called when the scan is completed, otherwise it may get wrong value. 432 * 433 * @return 434 * - ESP_OK: succeed 435 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 436 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 437 * - ESP_ERR_INVALID_ARG: invalid argument 438 */ 439 esp_err_t esp_wifi_scan_get_ap_num(uint16_t *number); 440 441 /** 442 * @brief Get AP list found in last scan 443 * 444 * @param[inout] number As input param, it stores max AP number ap_records can hold. 445 * As output param, it receives the actual AP number this API returns. 446 * @param ap_records wifi_ap_record_t array to hold the found APs 447 * 448 * @return 449 * - ESP_OK: succeed 450 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 451 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 452 * - ESP_ERR_INVALID_ARG: invalid argument 453 * - ESP_ERR_NO_MEM: out of memory 454 */ 455 esp_err_t esp_wifi_scan_get_ap_records(uint16_t *number, wifi_ap_record_t *ap_records); 456 457 458 /** 459 * @brief Get information of AP which the ESP32 station is associated with 460 * 461 * @attention When the obtained country information is empty, it means that the AP does not carry country information 462 * 463 * @param ap_info the wifi_ap_record_t to hold AP information 464 * sta can get the connected ap's phy mode info through the struct member 465 * phy_11b，phy_11g，phy_11n，phy_lr in the wifi_ap_record_t struct. 466 * For example, phy_11b = 1 imply that ap support 802.11b mode 467 * 468 * @return 469 * - ESP_OK: succeed 470 * - ESP_ERR_WIFI_CONN: The station interface don't initialized 471 * - ESP_ERR_WIFI_NOT_CONNECT: The station is in disconnect status 472 */ 473 esp_err_t esp_wifi_sta_get_ap_info(wifi_ap_record_t *ap_info); 474 475 /** 476 * @brief Set current WiFi power save type 477 * 478 * @attention Default power save type is WIFI_PS_MIN_MODEM. 479 * 480 * @param type power save type 481 * 482 * @return ESP_OK: succeed 483 */ 484 esp_err_t esp_wifi_set_ps(wifi_ps_type_t type); 485 486 /** 487 * @brief Get current WiFi power save type 488 * 489 * @attention Default power save type is WIFI_PS_MIN_MODEM. 490 * 491 * @param[out] type: store current power save type 492 * 493 * @return ESP_OK: succeed 494 */ 495 esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type); 496 497 /** 498 * @brief Set protocol type of specified interface 499 * The default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 500 * 501 * @attention Currently we only support 802.11b or 802.11bg or 802.11bgn mode 502 * 503 * @param ifx interfaces 504 * @param protocol_bitmap WiFi protocol bitmap 505 * 506 * @return 507 * - ESP_OK: succeed 508 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 509 * - ESP_ERR_WIFI_IF: invalid interface 510 * - others: refer to error codes in esp_err.h 511 */ 512 esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap); 513 514 /** 515 * @brief Get the current protocol bitmap of the specified interface 516 * 517 * @param ifx interface 518 * @param[out] protocol_bitmap store current WiFi protocol bitmap of interface ifx 519 * 520 * @return 521 * - ESP_OK: succeed 522 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 523 * - ESP_ERR_WIFI_IF: invalid interface 524 * - ESP_ERR_INVALID_ARG: invalid argument 525 * - others: refer to error codes in esp_err.h 526 */ 527 esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap); 528 529 /** 530 * @brief Set the bandwidth of ESP32 specified interface 531 * 532 * @attention 1. API return false if try to configure an interface that is not enabled 533 * @attention 2. WIFI_BW_HT40 is supported only when the interface support 11N 534 * 535 * @param ifx interface to be configured 536 * @param bw bandwidth 537 * 538 * @return 539 * - ESP_OK: succeed 540 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 541 * - ESP_ERR_WIFI_IF: invalid interface 542 * - ESP_ERR_INVALID_ARG: invalid argument 543 * - others: refer to error codes in esp_err.h 544 */ 545 esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw); 546 547 /** 548 * @brief Get the bandwidth of ESP32 specified interface 549 * 550 * @attention 1. API return false if try to get a interface that is not enable 551 * 552 * @param ifx interface to be configured 553 * @param[out] bw store bandwidth of interface ifx 554 * 555 * @return 556 * - ESP_OK: succeed 557 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 558 * - ESP_ERR_WIFI_IF: invalid interface 559 * - ESP_ERR_INVALID_ARG: invalid argument 560 */ 561 esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw); 562 563 /** 564 * @brief Set primary/secondary channel of ESP32 565 * 566 * @attention 1. This API should be called after esp_wifi_start() 567 * @attention 2. When ESP32 is in STA mode, this API should not be called when STA is scanning or connecting to an external AP 568 * @attention 3. When ESP32 is in softAP mode, this API should not be called when softAP has connected to external STAs 569 * @attention 4. When ESP32 is in STA+softAP mode, this API should not be called when in the scenarios described above 570 * 571 * @param primary for HT20, primary is the channel number, for HT40, primary is the primary channel 572 * @param second for HT20, second is ignored, for HT40, second is the second channel 573 * 574 * @return 575 * - ESP_OK: succeed 576 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 577 * - ESP_ERR_WIFI_IF: invalid interface 578 * - ESP_ERR_INVALID_ARG: invalid argument 579 */ 580 esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second); 581 582 /** 583 * @brief Get the primary/secondary channel of ESP32 584 * 585 * @attention 1. API return false if try to get a interface that is not enable 586 * 587 * @param primary store current primary channel 588 * @param[out] second store current second channel 589 * 590 * @return 591 * - ESP_OK: succeed 592 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 593 * - ESP_ERR_INVALID_ARG: invalid argument 594 */ 595 esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second); 596 597 /** 598 * @brief configure country info 599 * 600 * @attention 1. It is discouraged to call this API since this doesn't validate the per-country rules, 601 * it's up to the user to fill in all fields according to local regulations. 602 * Please use esp_wifi_set_country_code instead. 603 * @attention 2. The default country is CHINA {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO} 604 * @attention 3. When the country policy is WIFI_COUNTRY_POLICY_AUTO, the country info of the AP to which 605 * the station is connected is used. E.g. if the configured country info is {.cc="USA", .schan=1, .nchan=11} 606 * and the country info of the AP to which the station is connected is {.cc="JP", .schan=1, .nchan=14} 607 * then the country info that will be used is {.cc="JP", .schan=1, .nchan=14}. If the station disconnected 608 * from the AP the country info is set back to the country info of the station automatically, 609 * {.cc="US", .schan=1, .nchan=11} in the example. 610 * @attention 4. When the country policy is WIFI_COUNTRY_POLICY_MANUAL, then the configured country info is used always. 611 * @attention 5. When the country info is changed because of configuration or because the station connects to a different 612 * external AP, the country IE in probe response/beacon of the soft-AP is also changed. 613 * @attention 6. The country configuration is stored into flash. 614 * @attention 7. When this API is called, the PHY init data will switch to the PHY init data type corresponding to the 615 * country info. 616 * 617 * @param country the configured country info 618 * 619 * @return 620 * - ESP_OK: succeed 621 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 622 * - ESP_ERR_INVALID_ARG: invalid argument 623 */ 624 esp_err_t esp_wifi_set_country(const wifi_country_t *country); 625 626 /** 627 * @brief get the current country info 628 * 629 * @param country country info 630 * 631 * @return 632 * - ESP_OK: succeed 633 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 634 * - ESP_ERR_INVALID_ARG: invalid argument 635 */ 636 esp_err_t esp_wifi_get_country(wifi_country_t *country); 637 638 639 /** 640 * @brief Set MAC address of the ESP32 WiFi station or the soft-AP interface. 641 * 642 * @attention 1. This API can only be called when the interface is disabled 643 * @attention 2. ESP32 soft-AP and station have different MAC addresses, do not set them to be the same. 644 * @attention 3. The bit 0 of the first byte of ESP32 MAC address can not be 1. For example, the MAC address 645 * can set to be "1a:XX:XX:XX:XX:XX", but can not be "15:XX:XX:XX:XX:XX". 646 * 647 * @param ifx interface 648 * @param mac the MAC address 649 * 650 * @return 651 * - ESP_OK: succeed 652 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 653 * - ESP_ERR_INVALID_ARG: invalid argument 654 * - ESP_ERR_WIFI_IF: invalid interface 655 * - ESP_ERR_WIFI_MAC: invalid mac address 656 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 657 * - others: refer to error codes in esp_err.h 658 */ 659 esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, const uint8_t mac[6]); 660 661 /** 662 * @brief Get mac of specified interface 663 * 664 * @param ifx interface 665 * @param[out] mac store mac of the interface ifx 666 * 667 * @return 668 * - ESP_OK: succeed 669 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 670 * - ESP_ERR_INVALID_ARG: invalid argument 671 * - ESP_ERR_WIFI_IF: invalid interface 672 */ 673 esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6]); 674 675 /** 676 * @brief The RX callback function in the promiscuous mode. 677 * Each time a packet is received, the callback function will be called. 678 * 679 * @param buf Data received. Type of data in buffer (wifi_promiscuous_pkt_t or wifi_pkt_rx_ctrl_t) indicated by 'type' parameter. 680 * @param type promiscuous packet type. 681 * 682 */ 683 typedef void (* wifi_promiscuous_cb_t)(void *buf, wifi_promiscuous_pkt_type_t type); 684 685 /** 686 * @brief Register the RX callback function in the promiscuous mode. 687 * 688 * Each time a packet is received, the registered callback function will be called. 689 * 690 * @param cb callback 691 * 692 * @return 693 * - ESP_OK: succeed 694 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 695 */ 696 esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb); 697 698 /** 699 * @brief Enable the promiscuous mode. 700 * 701 * @param en false - disable, true - enable 702 * 703 * @return 704 * - ESP_OK: succeed 705 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 706 */ 707 esp_err_t esp_wifi_set_promiscuous(bool en); 708 709 /** 710 * @brief Get the promiscuous mode. 711 * 712 * @param[out] en store the current status of promiscuous mode 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_promiscuous(bool *en); 720 721 /** 722 * @brief Enable the promiscuous mode packet type filter. 723 * 724 * @note The default filter is to filter all packets except WIFI_PKT_MISC 725 * 726 * @param filter the packet type filtered in promiscuous mode. 727 * 728 * @return 729 * - ESP_OK: succeed 730 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 731 */ 732 esp_err_t esp_wifi_set_promiscuous_filter(const wifi_promiscuous_filter_t *filter); 733 734 /** 735 * @brief Get the promiscuous filter. 736 * 737 * @param[out] filter store the current status of promiscuous filter 738 * 739 * @return 740 * - ESP_OK: succeed 741 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 742 * - ESP_ERR_INVALID_ARG: invalid argument 743 */ 744 esp_err_t esp_wifi_get_promiscuous_filter(wifi_promiscuous_filter_t *filter); 745 746 /** 747 * @brief Enable subtype filter of the control packet in promiscuous mode. 748 * 749 * @note The default filter is to filter none control packet. 750 * 751 * @param filter the subtype of the control packet filtered in promiscuous mode. 752 * 753 * @return 754 * - ESP_OK: succeed 755 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 756 */ 757 esp_err_t esp_wifi_set_promiscuous_ctrl_filter(const wifi_promiscuous_filter_t *filter); 758 759 /** 760 * @brief Get the subtype filter of the control packet in promiscuous mode. 761 * 762 * @param[out] filter store the current status of subtype filter of the control packet in promiscuous mode 763 * 764 * @return 765 * - ESP_OK: succeed 766 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 767 * - ESP_ERR_WIFI_ARG: invalid argument 768 */ 769 esp_err_t esp_wifi_get_promiscuous_ctrl_filter(wifi_promiscuous_filter_t *filter); 770 771 /** 772 * @brief Set the configuration of the ESP32 STA or AP 773 * 774 * @attention 1. This API can be called only when specified interface is enabled, otherwise, API fail 775 * @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. 776 * @attention 3. ESP32 is 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 777 * the channel of the ESP32 station. 778 * 779 * @param interface interface 780 * @param conf station or soft-AP configuration 781 * 782 * @return 783 * - ESP_OK: succeed 784 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 785 * - ESP_ERR_INVALID_ARG: invalid argument 786 * - ESP_ERR_WIFI_IF: invalid interface 787 * - ESP_ERR_WIFI_MODE: invalid mode 788 * - ESP_ERR_WIFI_PASSWORD: invalid password 789 * - ESP_ERR_WIFI_NVS: WiFi internal NVS error 790 * - others: refer to the erro code in esp_err.h 791 */ 792 esp_err_t esp_wifi_set_config(wifi_interface_t interface, wifi_config_t *conf); 793 794 /** 795 * @brief Get configuration of specified interface 796 * 797 * @param interface interface 798 * @param[out] conf station or soft-AP configuration 799 * 800 * @return 801 * - ESP_OK: succeed 802 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 803 * - ESP_ERR_INVALID_ARG: invalid argument 804 * - ESP_ERR_WIFI_IF: invalid interface 805 */ 806 esp_err_t esp_wifi_get_config(wifi_interface_t interface, wifi_config_t *conf); 807 808 /** 809 * @brief Get STAs associated with soft-AP 810 * 811 * @attention SSC only API 812 * 813 * @param[out] sta station list 814 * ap can get the connected sta's phy mode info through the struct member 815 * phy_11b，phy_11g，phy_11n，phy_lr in the wifi_sta_info_t struct. 816 * For example, phy_11b = 1 imply that sta support 802.11b mode 817 * 818 * @return 819 * - ESP_OK: succeed 820 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 821 * - ESP_ERR_INVALID_ARG: invalid argument 822 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 823 * - ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid 824 */ 825 esp_err_t esp_wifi_ap_get_sta_list(wifi_sta_list_t *sta); 826 827 /** 828 * @brief Get AID of STA connected with soft-AP 829 * 830 * @param mac STA's mac address 831 * @param[out] aid Store the AID corresponding to STA mac 832 * 833 * @return 834 * - ESP_OK: succeed 835 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 836 * - ESP_ERR_INVALID_ARG: invalid argument 837 * - ESP_ERR_NOT_FOUND: Requested resource not found 838 * - ESP_ERR_WIFI_MODE: WiFi mode is wrong 839 * - ESP_ERR_WIFI_CONN: WiFi internal error, the station/soft-AP control block is invalid 840 */ 841 esp_err_t esp_wifi_ap_get_sta_aid(const uint8_t mac[6], uint16_t *aid); 842 843 /** 844 * @brief Set the WiFi API configuration storage type 845 * 846 * @attention 1. The default value is WIFI_STORAGE_FLASH 847 * 848 * @param storage : storage type 849 * 850 * @return 851 * - ESP_OK: succeed 852 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 853 * - ESP_ERR_INVALID_ARG: invalid argument 854 */ 855 esp_err_t esp_wifi_set_storage(wifi_storage_t storage); 856 857 /** 858 * @brief Function signature for received Vendor-Specific Information Element callback. 859 * @param ctx Context argument, as passed to esp_wifi_set_vendor_ie_cb() when registering callback. 860 * @param type Information element type, based on frame type received. 861 * @param sa Source 802.11 address. 862 * @param vnd_ie Pointer to the vendor specific element data received. 863 * @param rssi Received signal strength indication. 864 */ 865 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); 866 867 /** 868 * @brief Set 802.11 Vendor-Specific Information Element 869 * 870 * @param enable If true, specified IE is enabled. If false, specified IE is removed. 871 * @param type Information Element type. Determines the frame type to associate with the IE. 872 * @param idx Index to set or clear. Each IE type can be associated with up to two elements (indices 0 & 1). 873 * @param vnd_ie Pointer to vendor specific element data. First 6 bytes should be a header with fields matching vendor_ie_data_t. 874 * If enable is false, this argument is ignored and can be NULL. Data does not need to remain valid after the function returns. 875 * 876 * @return 877 * - ESP_OK: succeed 878 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init() 879 * - ESP_ERR_INVALID_ARG: Invalid argument, including if first byte of vnd_ie is not WIFI_VENDOR_IE_ELEMENT_ID (0xDD) 880 * or second byte is an invalid length. 881 * - ESP_ERR_NO_MEM: Out of memory 882 */ 883 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); 884 885 /** 886 * @brief Register Vendor-Specific Information Element monitoring callback. 887 * 888 * @param cb Callback function 889 * @param ctx Context argument, passed to callback function. 890 * 891 * @return 892 * - ESP_OK: succeed 893 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 894 */ 895 esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx); 896 897 /** 898 * @brief Set maximum transmitting power after WiFi start. 899 * 900 * @attention 1. Maximum power before wifi startup is limited by PHY init data bin. 901 * @attention 2. The value set by this API will be mapped to the max_tx_power of the structure wifi_country_t variable. 902 * @attention 3. Mapping Table {Power, max_tx_power} = {{8, 2}, {20, 5}, {28, 7}, {34, 8}, {44, 11}, 903 * {52, 13}, {56, 14}, {60, 15}, {66, 16}, {72, 18}, {80, 20}}. 904 * @attention 4. Param power unit is 0.25dBm, range is [8, 84] corresponding to 2dBm - 20dBm. 905 * @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}}. 906 * 907 * @param power Maximum WiFi transmitting power. 908 * 909 * @return 910 * - ESP_OK: succeed 911 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 912 * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start 913 * - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is out of range 914 */ 915 esp_err_t esp_wifi_set_max_tx_power(int8_t power); 916 917 /** 918 * @brief Get maximum transmiting power after WiFi start 919 * 920 * @param power Maximum WiFi transmitting power, unit is 0.25dBm. 921 * 922 * @return 923 * - ESP_OK: succeed 924 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 925 * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start 926 * - ESP_ERR_WIFI_ARG: invalid argument 927 */ 928 esp_err_t esp_wifi_get_max_tx_power(int8_t *power); 929 930 /** 931 * @brief Set mask to enable or disable some WiFi events 932 * 933 * @attention 1. Mask can be created by logical OR of various WIFI_EVENT_MASK_ constants. 934 * Events which have corresponding bit set in the mask will not be delivered to the system event handler. 935 * @attention 2. Default WiFi event mask is WIFI_EVENT_MASK_AP_PROBEREQRECVED. 936 * @attention 3. There may be lots of stations sending probe request data around. 937 * Don't unmask this event unless you need to receive probe request data. 938 * 939 * @param mask WiFi event mask. 940 * 941 * @return 942 * - ESP_OK: succeed 943 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 944 */ 945 esp_err_t esp_wifi_set_event_mask(uint32_t mask); 946 947 /** 948 * @brief Get mask of WiFi events 949 * 950 * @param mask WiFi event mask. 951 * 952 * @return 953 * - ESP_OK: succeed 954 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 955 * - ESP_ERR_WIFI_ARG: invalid argument 956 */ 957 esp_err_t esp_wifi_get_event_mask(uint32_t *mask); 958 959 /** 960 * @brief Send raw ieee80211 data 961 * 962 * @attention Currently only support for sending beacon/probe request/probe response/action and non-QoS 963 * data frame 964 * 965 * @param ifx interface if the Wi-Fi mode is Station, the ifx should be WIFI_IF_STA. If the Wi-Fi 966 * mode is SoftAP, the ifx should be WIFI_IF_AP. If the Wi-Fi mode is Station+SoftAP, the 967 * ifx should be WIFI_IF_STA or WIFI_IF_AP. If the ifx is wrong, the API returns ESP_ERR_WIFI_IF. 968 * @param buffer raw ieee80211 buffer 969 * @param len the length of raw buffer, the len must be <= 1500 Bytes and >= 24 Bytes 970 * @param en_sys_seq indicate whether use the internal sequence number. If en_sys_seq is false, the 971 * sequence in raw buffer is unchanged, otherwise it will be overwritten by WiFi driver with 972 * the system sequence number. 973 * Generally, if esp_wifi_80211_tx is called before the Wi-Fi connection has been set up, both 974 * en_sys_seq==true and en_sys_seq==false are fine. However, if the API is called after the Wi-Fi 975 * connection has been set up, en_sys_seq must be true, otherwise ESP_ERR_WIFI_ARG is returned. 976 * 977 * @return 978 * - ESP_OK: success 979 * - ESP_ERR_WIFI_IF: Invalid interface 980 * - ESP_ERR_INVALID_ARG: Invalid parameter 981 * - ESP_ERR_WIFI_NO_MEM: out of memory 982 */ 983 984 esp_err_t esp_wifi_80211_tx(wifi_interface_t ifx, const void *buffer, int len, bool en_sys_seq); 985 986 /** 987 * @brief The RX callback function of Channel State Information(CSI) data. 988 * 989 * Each time a CSI data is received, the callback function will be called. 990 * 991 * @param ctx context argument, passed to esp_wifi_set_csi_rx_cb() when registering callback function. 992 * @param data CSI data received. The memory that it points to will be deallocated after callback function returns. 993 * 994 */ 995 typedef void (* wifi_csi_cb_t)(void *ctx, wifi_csi_info_t *data); 996 997 998 /** 999 * @brief Register the RX callback function of CSI data. 1000 * 1001 * Each time a CSI data is received, the callback function will be called. 1002 * 1003 * @param cb callback 1004 * @param ctx context argument, passed to callback function 1005 * 1006 * @return 1007 * - ESP_OK: succeed 1008 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1009 */ 1010 1011 esp_err_t esp_wifi_set_csi_rx_cb(wifi_csi_cb_t cb, void *ctx); 1012 1013 /** 1014 * @brief Set CSI data configuration 1015 * 1016 * @param config configuration 1017 * 1018 * return 1019 * - ESP_OK: succeed 1020 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1021 * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not enabled 1022 * - ESP_ERR_INVALID_ARG: invalid argument 1023 */ 1024 esp_err_t esp_wifi_set_csi_config(const wifi_csi_config_t *config); 1025 1026 /** 1027 * @brief Enable or disable CSI 1028 * 1029 * @param en true - enable, false - disable 1030 * 1031 * return 1032 * - ESP_OK: succeed 1033 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1034 * - ESP_ERR_WIFI_NOT_START: WiFi is not started by esp_wifi_start or promiscuous mode is not enabled 1035 * - ESP_ERR_INVALID_ARG: invalid argument 1036 */ 1037 esp_err_t esp_wifi_set_csi(bool en); 1038 1039 /** 1040 * @brief Set antenna GPIO configuration 1041 * 1042 * @param config Antenna GPIO configuration. 1043 * 1044 * @return 1045 * - ESP_OK: succeed 1046 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1047 * - ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid GPIO number etc 1048 */ 1049 esp_err_t esp_wifi_set_ant_gpio(const wifi_ant_gpio_config_t *config); 1050 1051 /** 1052 * @brief Get current antenna GPIO configuration 1053 * 1054 * @param config Antenna GPIO configuration. 1055 * 1056 * @return 1057 * - ESP_OK: succeed 1058 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1059 * - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL 1060 */ 1061 esp_err_t esp_wifi_get_ant_gpio(wifi_ant_gpio_config_t *config); 1062 1063 1064 /** 1065 * @brief Set antenna configuration 1066 * 1067 * @param config Antenna configuration. 1068 * 1069 * @return 1070 * - ESP_OK: succeed 1071 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1072 * - ESP_ERR_WIFI_ARG: Invalid argument, e.g. parameter is NULL, invalid antenna mode or invalid GPIO number 1073 */ 1074 esp_err_t esp_wifi_set_ant(const wifi_ant_config_t *config); 1075 1076 /** 1077 * @brief Get current antenna configuration 1078 * 1079 * @param config Antenna configuration. 1080 * 1081 * @return 1082 * - ESP_OK: succeed 1083 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1084 * - ESP_ERR_WIFI_ARG: invalid argument, e.g. parameter is NULL 1085 */ 1086 esp_err_t esp_wifi_get_ant(wifi_ant_config_t *config); 1087 1088 /** 1089 * @brief Get the TSF time 1090 * In Station mode or SoftAP+Station mode if station is not connected or station doesn't receive at least 1091 * one beacon after connected, will return 0 1092 * 1093 * @attention Enabling power save may cause the return value inaccurate, except WiFi modem sleep 1094 * 1095 * @param interface The interface whose tsf_time is to be retrieved. 1096 * 1097 * @return 0 or the TSF time 1098 */ 1099 int64_t esp_wifi_get_tsf_time(wifi_interface_t interface); 1100 1101 /** 1102 * @brief Set the inactive time of the ESP32 STA or AP 1103 * 1104 * @attention 1. For Station, If the station does not receive a beacon frame from the connected SoftAP during the inactive time, 1105 * disconnect from SoftAP. Default 6s. 1106 * @attention 2. For SoftAP, If the softAP doesn't receive any data from the connected STA during inactive time, 1107 * the softAP will force deauth the STA. Default is 300s. 1108 * @attention 3. The inactive time configuration is not stored into flash 1109 * 1110 * @param ifx interface to be configured. 1111 * @param sec Inactive time. Unit seconds. 1112 * 1113 * @return 1114 * - ESP_OK: succeed 1115 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1116 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 1117 * - ESP_ERR_WIFI_ARG: invalid argument, For Station, if sec is less than 3. For SoftAP, if sec is less than 10. 1118 */ 1119 esp_err_t esp_wifi_set_inactive_time(wifi_interface_t ifx, uint16_t sec); 1120 1121 /** 1122 * @brief Get inactive time of specified interface 1123 * 1124 * @param ifx Interface to be configured. 1125 * @param sec Inactive time. Unit seconds. 1126 * 1127 * @return 1128 * - ESP_OK: succeed 1129 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1130 * - ESP_ERR_WIFI_ARG: invalid argument 1131 */ 1132 esp_err_t esp_wifi_get_inactive_time(wifi_interface_t ifx, uint16_t *sec); 1133 1134 /** 1135 * @brief Dump WiFi statistics 1136 * 1137 * @param modules statistic modules to be dumped 1138 * 1139 * @return 1140 * - ESP_OK: succeed 1141 * - others: failed 1142 */ 1143 esp_err_t esp_wifi_statis_dump(uint32_t modules); 1144 1145 /** 1146 * @brief Set RSSI threshold below which APP will get an event 1147 * 1148 * @attention This API needs to be called every time after WIFI_EVENT_STA_BSS_RSSI_LOW event is received. 1149 * 1150 * @param rssi threshold value in dbm between -100 to 0 1151 * 1152 * @return 1153 * - ESP_OK: succeed 1154 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1155 * - ESP_ERR_WIFI_ARG: invalid argument 1156 */ 1157 esp_err_t esp_wifi_set_rssi_threshold(int32_t rssi); 1158 1159 /** 1160 * @brief Start an FTM Initiator session by sending FTM request 1161 * If successful, event WIFI_EVENT_FTM_REPORT is generated with the result of the FTM procedure 1162 * 1163 * @attention Use this API only in Station mode 1164 * 1165 * @param cfg FTM Initiator session configuration 1166 * 1167 * @return 1168 * - ESP_OK: succeed 1169 * - others: failed 1170 */ 1171 esp_err_t esp_wifi_ftm_initiate_session(wifi_ftm_initiator_cfg_t *cfg); 1172 1173 /** 1174 * @brief End the ongoing FTM Initiator session 1175 * 1176 * @attention This API works only on FTM Initiator 1177 * 1178 * @return 1179 * - ESP_OK: succeed 1180 * - others: failed 1181 */ 1182 esp_err_t esp_wifi_ftm_end_session(void); 1183 1184 /** 1185 * @brief Set offset in cm for FTM Responder. An equivalent offset is calculated in picoseconds 1186 * and added in TOD of FTM Measurement frame (T1). 1187 * 1188 * @attention Use this API only in AP mode before performing FTM as responder 1189 * 1190 * @param offset_cm T1 Offset to be added in centimeters 1191 * 1192 * @return 1193 * - ESP_OK: succeed 1194 * - others: failed 1195 */ 1196 esp_err_t esp_wifi_ftm_resp_set_offset(int16_t offset_cm); 1197 1198 /** 1199 * @brief Enable or disable 11b rate of specified interface 1200 * 1201 * @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). 1202 * @attention 2. Only when really need to disable 11b rate call this API otherwise don't call this. 1203 * 1204 * @param ifx Interface to be configured. 1205 * @param disable true means disable 11b rate while false means enable 11b rate. 1206 * 1207 * @return 1208 * - ESP_OK: succeed 1209 * - others: failed 1210 */ 1211 esp_err_t esp_wifi_config_11b_rate(wifi_interface_t ifx, bool disable); 1212 1213 /** 1214 * @brief Config ESPNOW rate of specified interface 1215 * 1216 * @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). 1217 * 1218 * @param ifx Interface to be configured. 1219 * @param rate Phy rate to be configured. 1220 * 1221 * @return 1222 * - ESP_OK: succeed 1223 * - others: failed 1224 */ 1225 esp_err_t esp_wifi_config_espnow_rate(wifi_interface_t ifx, wifi_phy_rate_t rate); 1226 1227 /** 1228 * @brief Set interval for station to wake up periodically at disconnected. 1229 * 1230 * @attention 1. Only when ESP_WIFI_STA_DISCONNECTED_PM_ENABLE is enabled, this configuration could work 1231 * @attention 2. This configuration only work for station mode and disconnected status 1232 * @attention 3. This configuration would influence nothing until some module configure wake_window 1233 * @attention 4. A sensible interval which is not too small is recommended (e.g. 100ms) 1234 * 1235 * @param interval how much micriosecond would the chip wake up, from 1 to 65535. 1236 */ 1237 esp_err_t esp_wifi_set_connectionless_wake_interval(uint16_t interval); 1238 1239 /** 1240 * @brief configure country 1241 * 1242 * @attention 1. When ieee80211d_enabled, the country info of the AP to which 1243 * the station is connected is used. E.g. if the configured country is US 1244 * and the country info of the AP to which the station is connected is JP 1245 * then the country info that will be used is JP. If the station disconnected 1246 * from the AP the country info is set back to the country info of the station automatically, 1247 * US in the example. 1248 * @attention 2. When ieee80211d_enabled is disabled, then the configured country info is used always. 1249 * @attention 3. When the country info is changed because of configuration or because the station connects to a different 1250 * external AP, the country IE in probe response/beacon of the soft-AP is also changed. 1251 * @attention 4. The country configuration is stored into flash. 1252 * @attention 5. When this API is called, the PHY init data will switch to the PHY init data type corresponding to the 1253 * country info. 1254 * @attention 6. Supported country codes are "01"(world safe mode) "AT","AU","BE","BG","BR", 1255 * "CA","CH","CN","CY","CZ","DE","DK","EE","ES","FI","FR","GB","GR","HK","HR","HU", 1256 * "IE","IN","IS","IT","JP","KR","LI","LT","LU","LV","MT","MX","NL","NO","NZ","PL","PT", 1257 * "RO","SE","SI","SK","TW","US" 1258 * 1259 * @attention 7. When country code "01" (world safe mode) is set, SoftAP mode won't contain country IE. 1260 * @attention 8. The default country is "CN" and ieee80211d_enabled is TRUE. 1261 * 1262 * @param country the configured country ISO code 1263 * @param ieee80211d_enabled 802.11d is enabled or not 1264 * 1265 * @return 1266 * - ESP_OK: succeed 1267 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1268 * - ESP_ERR_INVALID_ARG: invalid argument 1269 */ 1270 esp_err_t esp_wifi_set_country_code(const char *country, bool ieee80211d_enabled); 1271 1272 /** 1273 * @brief get the current country code 1274 * 1275 * @param country country code 1276 * 1277 * @return 1278 * - ESP_OK: succeed 1279 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 1280 * - ESP_ERR_INVALID_ARG: invalid argument 1281 */ 1282 esp_err_t esp_wifi_get_country_code(char *country); 1283 1284 /** 1285 * @brief Config 80211 tx rate of specified interface 1286 * 1287 * @attention 1. This API should be called after esp_wifi_init() and before esp_wifi_start(). 1288 * 1289 * @param ifx Interface to be configured. 1290 * @param rate Phy rate to be configured. 1291 * 1292 * @return 1293 * - ESP_OK: succeed 1294 * - others: failed 1295 */ 1296 esp_err_t esp_wifi_config_80211_tx_rate(wifi_interface_t ifx, wifi_phy_rate_t rate); 1297 1298 #ifdef __cplusplus 1299 } 1300 #endif 1301 1302 #endif /* __ESP_WIFI_H__ */ 1303
