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