ESP32-IDF
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
esp_wifi.h
Go to the documentation of this file.
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 "freertos/FreeRTOS.h"
63 #include "freertos/queue.h"
64 #include "esp_err.h"
65 #include "rom/queue.h"
66 
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
71 typedef enum {
77 } wifi_mode_t;
78 
79 typedef enum {
84 
85 typedef enum {
92 
93 typedef enum {
101 
102 enum {
126 
132 };
133 
134 typedef enum {
139 
140 
141 typedef struct {
148 
149 
150 #define WIFI_INIT_CONFIG_DEFAULT(event_queue_) { \
151  .event_queue = event_queue_, \
152  .rx_ba_win = 0, \
153  .tx_ba_win = 0, \
154  .rx_buf_cnt = 0, \
155  .tx_buf_cnt = 0 \
156 };
157 
176 
187 
200 
210 
223 
236 
249 
259 
269 
279 
280 typedef struct {
281  char *ssid;
284  bool show_hidden;
286 
302 
311 
323 
324 typedef struct {
325  uint8_t bssid[6];
326  uint8_t ssid[32];
332 
344 
345 typedef enum {
351 
361 
371 
372 #define WIFI_PROTOCOL_11B 1
373 #define WIFI_PROTOCOL_11G 2
374 #define WIFI_PROTOCOL_11N 4
375 
389 
400 
401 typedef enum {
402  WIFI_BW_HT20 = 0, /* Bandwidth is HT20 */
403  WIFI_BW_HT40, /* Bandwidth is HT40 */
405 
419 
432 
445 
458 
469 
479 
495 
505 
517 typedef void (* wifi_promiscuous_cb_t)(void *buf, uint16_t len);
518 
530 
540 
550 
551 typedef struct {
552  char ssid[32];
553  char password[64];
561 
562 typedef struct {
563  char ssid[32];
564  char password[64];
565  bool bssid_set;
566  uint8_t bssid[6];
568 
569 typedef union {
572 } wifi_config_t;
573 
589 
600 
601 struct station_info {
604 };
605 
617 
619 
620 typedef enum {
624 
636 
643 typedef esp_err_t (*wifi_rxcb_t)(void *buffer, uint16_t len, void *eb);
644 
657 
670 
680 
685 typedef enum {
692 
697 typedef enum {
701 
719 
732 typedef void (*esp_vendor_ie_cb_t) (void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const uint8_t *vnd_ie, int rssi);
733 
744 
745 #ifdef __cplusplus
746 }
747 #endif
748 
749 #endif /* __ESP_WIFI_H__ */
const XML_Char int len
Definition: expat.h:262
Definition: esp_wifi.h:108
esp_err_t esp_wifi_set_auto_connect(bool en)
Set auto connect The default value is true.
esp_err_t esp_wifi_scan_stop(void)
Stop the scan in process.
Definition: esp_wifi.h:122
Definition: esp_wifi.h:128
esp_err_t esp_wifi_get_protocol(wifi_interface_t ifx, uint8_t *protocol_bitmap)
Get the current protocol bitmap of specified ifx.
Definition: esp_wifi.h:686
esp_err_t esp_wifi_set_config(wifi_interface_t ifx, wifi_config_t *conf)
Set the configuration of the ESP32 STA or AP.
Definition: esp_wifi.h:115
Definition: esp_wifi.h:105
Definition: esp_wifi.h:127
wifi_auth_mode_t
Definition: esp_wifi.h:93
Definition: esp_wifi.h:698
Definition: esp_wifi.h:562
uint8_t * bssid
Definition: esp_wifi.h:282
Definition: esp_wifi.h:135
esp_err_t esp_wifi_connect(void)
Connect the ESP32 WiFi station to the AP.
Definition: esp_wifi.h:349
Definition: esp_wifi.h:551
QueueHandle_t event_queue
Definition: esp_wifi.h:142
wifi_vendor_ie_id_t
Vendor IE index.
Definition: esp_wifi.h:697
esp_err_t esp_wifi_start(void)
Start WiFi according to current configuration If mode is WIFI_MODE_STA, it create station control blo...
esp_err_t esp_wifi_free_station_list(void)
wifi_vendor_ie_type_t
Vendor IE type.
Definition: esp_wifi.h:685
uint8_t channel
Definition: esp_wifi.h:283
Definition: esp_wifi.h:117
Definition: esp_wifi.h:130
esp_err_t esp_wifi_get_promiscuous(uint8_t *enable)
Get the promiscuous mode.
esp_err_t esp_wifi_init(wifi_init_config_t *config)
Init WiFi Alloc resource for WiFi driver, such as WiFi control structure, RX/TX buffer, WiFi NVS structure etc, this WiFi also start WiFi task.
Definition: esp_wifi.h:569
esp_err_t esp_wifi_set_promiscuous(uint8_t enable)
Enable the promiscuous mode.
Definition: esp_wifi.h:129
Definition: esp_wifi.h:141
Definition: esp_wifi.h:90
Definition: esp_wifi.h:324
esp_err_t esp_wifi_get_ap_list(uint16_t *number, wifi_ap_list_t *ap_list)
Get AP list found in last scan.
esp_err_t esp_wifi_set_protocol(wifi_interface_t ifx, uint8_t protocol_bitmap)
Set protocol type of specified interface The default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G...
__int8_t int8_t
Definition: stdint.h:20
Definition: esp_wifi.h:104
uint8_t rx_buf_cnt
Definition: esp_wifi.h:145
esp_err_t esp_wifi_set_storage(wifi_storage_t storage)
Set the WiFi API configuration storage type.
Definition: esp_wifi.h:106
__uint16_t uint16_t
Definition: stdint.h:33
Definition: esp_wifi.h:123
Definition: esp_wifi.h:109
STAILQ_ENTRY(station_info) next
Definition: esp_wifi.h:72
Definition: esp_wifi.h:94
void * QueueHandle_t
Definition: queue.h:88
Definition: esp_wifi.h:124
Definition: esp_wifi.h:97
Definition: esp_wifi.h:73
esp_err_t esp_wifi_set_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t bw)
Set the bandwidth of ESP32 specified interface.
uint8_t primary
Definition: esp_wifi.h:327
Definition: esp_wifi.h:107
esp_err_t esp_wifi_set_channel(uint8_t primary, wifi_second_chan_t second)
Set primary/second channel of ESP32.
void(* wifi_promiscuous_cb_t)(void *buf, uint16_t len)
The RX callback function in the promiscuous mode.
Definition: esp_wifi.h:517
wifi_second_chan_t second
Definition: esp_wifi.h:328
Definition: esp_wifi.h:622
bool bssid_set
Definition: esp_wifi.h:565
Definition: esp_wifi.h:120
int8_t rssi
Definition: esp_wifi.h:329
wifi_ap_config_t ap
Definition: esp_wifi.h:570
wifi_auth_mode_t authmode
Definition: esp_wifi.h:330
uint8_t channel
Definition: esp_wifi.h:555
esp_err_t esp_wifi_scan_start(wifi_scan_config_t *conf, bool block)
Scan all available APs.
char * ssid
Definition: esp_wifi.h:281
Definition: esp_wifi.h:136
esp_err_t esp_wifi_get_mac(wifi_interface_t ifx, uint8_t mac[6])
Get mac of specified interface.
Definition: esp_wifi.h:80
esp_err_t esp_wifi_get_config(wifi_interface_t ifx, wifi_config_t *conf)
Get configuration of specified interface.
esp_err_t esp_wifi_get_auto_connect(bool *en)
Get the auto connect flag.
Definition: esp_wifi.h:76
Definition: esp_wifi.h:131
esp_err_t esp_wifi_get_bandwidth(wifi_interface_t ifx, wifi_bandwidth_t *bw)
Get the bandwidth of ESP32 specified interface.
Definition: esp_wifi.h:89
esp_err_t esp_wifi_clear_fast_connect(void)
Currently this API is just an stub API.
Definition: esp_wifi.h:86
wifi_ps_type_t
Definition: esp_wifi.h:345
uint16_t beacon_interval
Definition: esp_wifi.h:559
esp_err_t esp_wifi_disconnect(void)
Disconnect the ESP32 WiFi station from the AP.
Definition: esp_wifi.h:111
Definition: esp_wifi.h:116
Definition: esp_wifi.h:280
uint8_t ssid_hidden
Definition: esp_wifi.h:557
Definition: esp_wifi.h:82
Definition: esp_wifi.h:114
esp_err_t esp_wifi_set_promiscuous_rx_cb(wifi_promiscuous_cb_t cb)
Register the RX callback function in the promiscuous mode.
Definition: esp_wifi.h:103
#define buffer
Definition: xmlparse.c:629
wifi_country_t
Definition: esp_wifi.h:85
wifi_sta_config_t sta
Definition: esp_wifi.h:571
Definition: esp_wifi.h:95
Definition: esp_wifi.h:98
Definition: esp_wifi.h:689
Definition: xmlparse.c:224
Definition: esp_wifi.h:112
esp_err_t esp_wifi_get_mode(wifi_mode_t *mode)
Get current operating mode of WiFi.
Definition: esp_wifi.h:699
Definition: esp_wifi.h:690
wifi_auth_mode_t authmode
Definition: esp_wifi.h:556
Definition: esp_wifi.h:113
esp_err_t esp_wifi_set_ps(wifi_ps_type_t type)
Set current power save type.
Definition: esp_wifi.h:110
esp_err_t esp_wifi_get_ap_num(uint16_t *number)
Get number of APs found in last scan.
esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type)
Get current power save type.
void(* esp_vendor_ie_cb_t)(void *ctx, wifi_vendor_ie_type_t type, const uint8_t sa[6], const uint8_t *vnd_ie, int rssi)
Define function pointer for vendor specific element callback.
Definition: esp_wifi.h:732
esp_err_t esp_wifi_set_vendor_ie_cb(esp_vendor_ie_cb_t cb, void *ctx)
Set vendor specific element callback.
Definition: esp_wifi.h:621
Definition: esp_wifi.h:137
esp_err_t(* wifi_rxcb_t)(void *buffer, uint16_t len, void *eb)
The WiFi RX callback function.
Definition: esp_wifi.h:643
uint8_t tx_buf_cnt
Definition: esp_wifi.h:146
uint8_t bssid[6]
Definition: esp_wifi.h:603
wifi_mode_t
Definition: esp_wifi.h:71
Definition: esp_wifi.h:87
Definition: esp_wifi.h:403
Definition: esp_wifi.h:347
esp_err_t esp_wifi_kick_station(uint16_t aid)
Kick the all station or associated id equals to aid.
wifi_bandwidth_t
Definition: esp_wifi.h:401
wifi_interface_t
Definition: esp_wifi.h:79
wifi_storage_t
Definition: esp_wifi.h:620
Definition: esp_wifi.h:687
Definition: esp_wifi.h:125
esp_err_t esp_wifi_set_country(wifi_country_t country)
Set country code The default value is WIFI_COUNTRY_CN.
esp_err_t esp_wifi_deinit(void)
Deinit WiFi Free all resource allocated in esp_wifi_init and stop WiFi task.
uint8_t max_connection
Definition: esp_wifi.h:558
esp_err_t esp_wifi_set_mode(wifi_mode_t mode)
Set the WiFi operating mode.
uint8_t ssid_len
Definition: esp_wifi.h:554
uint8_t rx_ba_win
Definition: esp_wifi.h:143
int32_t esp_err_t
Definition: esp_err.h:24
Definition: esp_wifi.h:88
esp_err_t esp_wifi_stop(void)
Stop WiFi If mode is WIFI_MODE_STA, it stop station and free station control block If mode is WIFI_MO...
esp_err_t esp_wifi_get_country(wifi_country_t *country)
Get country code.
Definition: esp_wifi.h:346
esp_err_t esp_wifi_set_mac(wifi_interface_t ifx, uint8_t mac[6])
Set MAC address of the ESP32 WiFi station or the soft-AP interface.
Definition: esp_wifi.h:74
Definition: esp_wifi.h:75
Definition: esp_wifi.h:119
typedef void(XMLCALL *XML_ElementDeclHandler)(void *userData
Definition: esp_wifi.h:121
Definition: esp_wifi.h:601
Definition: esp_wifi.h:348
__uint8_t uint8_t
Definition: stdint.h:21
Definition: esp_wifi.h:96
esp_err_t esp_wifi_get_station_list(struct station_info **station)
Get STAs associated with soft-AP.
Definition: esp_wifi.h:99
wifi_second_chan_t
Definition: esp_wifi.h:134
uint8_t tx_ba_win
Definition: esp_wifi.h:144
esp_err_t esp_wifi_get_channel(uint8_t *primary, wifi_second_chan_t *second)
Get the primary/second channel of ESP32.
esp_err_t esp_wifi_reg_rxcb(wifi_interface_t ifx, wifi_rxcb_t fn)
Set the WiFi RX callback.
Definition: esp_wifi.h:81
esp_err_t esp_wifi_set_vendor_ie(bool enable, wifi_vendor_ie_type_t type, wifi_vendor_ie_id_t idx, uint8_t *vnd_ie)
Set vendor specific element.
Definition: esp_wifi.h:688
Definition: esp_wifi.h:118
Definition: esp_wifi.h:402
bool show_hidden
Definition: esp_wifi.h:284