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