Chapter 4. API Guides
You can call other esp_wifi_set_xxx APIs to configure more settings, such as the protocol mode, country code,
bandwidth, etc. Refer to ESP32-S2 Wi-Fi Configuration.
Generally, we configure the Wi-Fi driver before setting up the Wi-Fi connection, but this is NOT mandatory, which
means that you can configure the Wi-Fi connection anytime, provided that the Wi-Fi driver is initialized successfully.
However, if the configuration does not need to change after the Wi-Fi connection is set up, you should configure the
Wi-Fi driver at this stage, because the configuration APIs (such as esp_wifi_set_protocol()) will cause the
Wi-Fi to reconnect, which may not be desirable.
If the Wi-Fi NVS flash is enabled by menuconfig, all Wi-Fi configuration in this phase, or later phases, will be stored
into flash. When the board powers on/reboots, you do not need to configure the Wi-Fi driver from scratch. You only
need to call esp_wifi_get_xxx APIs to fetch the configuration stored in flash previously. You can also configure the
Wi-Fi driver if the previous configuration is not what you want.
3. Wi-Fi Start Phase
• s3.1: Call esp_wifi_start() to start the Wi-Fi driver.
• s3.2: The Wi-Fi driver posts WIFI_EVENT_STA_START to the event task; then, the event task will do some
common things and will call the application event callback function.
• s3.3: The application event callback function relays the WIFI_EVENT_STA_START to the application task. We
recommend that you call esp_wifi_connect(). However, you can also call esp_wifi_connect()
in other phrases after the WIFI_EVENT_STA_START arises.
4. Wi-Fi Connect Phase
• s4.1: Once esp_wifi_connect() is called, the Wi-Fi driver will start the internal scan/connection pro-
cess.
• s4.2: If the internal scan/connection process is successful, the WIFI_EVENT_STA_CONNECTED will be gen-
erated. In the event task, it starts the DHCP client, which will finally trigger the DHCP process.
• s4.3: In the above-mentioned scenario, the application event callback will relay the event to the application
task. Generally, the application needs to do nothing, and you can do whatever you want, e.g., print a log, etc.
In step 4.2, the Wi-Fi connection may fail because, for example, the password is wrong, the AP is not found, etc. In
a case like this, WIFI_EVENT_STA_DISCONNECTED will arise and the reason for such a failure will be provided.
For handling events that disrupt Wi-Fi connection, please refer to phase 6.
5. Wi-Fi ‘Got IP’Phase
• s5.1: Once the DHCP client is initialized in step 4.2, the got IP phase will begin.
• s5.2: If the IP address is successfully received from the DHCP server, then IP_EVENT_STA_GOT_IP will arise
and the event task will perform common handling.
• s5.3: In the application event callback, IP_EVENT_STA_GOT_IP is relayed to the application task. For LwIP-
based applications, this event is very special and means that everything is ready for the application to begin
its tasks, e.g. creating the TCP/UDP socket, etc. A very common mistake is to initialize the socket before
IP_EVENT_STA_GOT_IP is received. DO NOT start the socket-related work before the IP is received.
6. Wi-Fi Disconnect Phase
• s6.1: When the Wi-Fi connection is disrupted, e.g. because the AP is powered off, the RSSI is poor, etc.,
WIFI_EVENT_STA_DISCONNECTED will arise. This event may also arise in phase 3. Here, the event task
will notify the LwIP task to clear/remove all UDP/TCP connections. Then, all application sockets will be in a
wrong status. In other words, no socket can work properly when this event happens.
• s6.2: In the scenario described above, the application event callback function re-
lays WIFI_EVENT_STA_DISCONNECTED to the application task. We recommend that
esp_wifi_connect() be called to reconnect the Wi-Fi, close all sockets and re-create them if
necessary. Refer to WIFI_EVENT_STA_DISCONNECTED.
Espressif Systems 1520
Submit Document Feedback
Release v4.4
To Next Page
Loading...