Web Server AT Example
This document mainly introduces the use of AT web server, mainly involving the following applications:
Note
The default firmware does not support web server AT commands, please refer to Web Server AT Commands to enable the web server.
Wi-Fi Provisioning Using a Browser
Introduction
With the web server, mobile phone or PC is able to control ESP32’s Wi-Fi provisioning service. You can use a mobile phone or computer to connect to the SoftAP of the ESP32, open the web pages via browser, start provisioning service, and then the ESP32 can connect to the target router as you set.
Introduction to Operation Steps
The whole process can be divided into the following three steps:
Use STA Device to Connect to ESP32 Device
Firstly, ESP32 needs to be configured to softAP + STA mode, and creates a web server to wait for Wi-Fi provisioning messages. In this case, a mobile phone or a PC can connect to the ESP32 softAP as a station. The corresponding AT commands are as follows:
Clear the previous Wi-Fi provisioning information.
Command
AT+RESTORE
Set the Wi-Fi mode to Station+SoftAP.
Command
AT+CWMODE=3
Set the configuration of an ESP32 SoftAP. (For example, set the default connection ssid to “pos_softap”, Wi-Fi without password.)
Command
AT+CWSAP="pos_softap","",11,0,3
Enable multiple connections.
Command
AT+CIPMUX=1
Create a web server, port: 80, connection timeout: 25 s (default maximum is 60 s).
Command
AT+WEBSERVER=1,80,25
After starting the web sever according to the above commands, you can turn on the Wi-Fi connection function on your STA device, and connect it to the softAP of the ESP32:
Connection to the ESP32 AP
Use the Browser to Send Wi-Fi Connection Information
After your STA device connected to the ESP32 softAP, it can send Wi-Fi connection information to ESP32 in an HTTP request. Please note that if your target AP is the hotspot of the device which opens the web pages, you may not receive the Wi-Fi connection result. You can enter the default IP address of the web server in the browser (the default IP is 192.168.4.1, or you can query the current SoftAP IP address by command AT+CIPAP?), open the Wi-Fi provisioning interface, and enter the ssid and password of the router to be connected, click “Connect” to let ESP32 start connecting to the router:
Opening the Wi-Fi Provisioning Interface
Or you can click the drop-down box of SSID to list all APs nearby, select the target AP and enter the password, and then click “Connect” to let the ESP32 start connecting to the router:
Schematic Diagram Of Browser Obtaining Wi-Fi AP List
Get the Result of Wi-Fi Connection
After the Wi-Fi connection is established successfully, the web page will be displayed as follows:
Wi-Fi Connection Established Successfully
Note 1: After the Wi-Fi connection is established successfully, the webpage will be closed automatically. If you want to continue to access the webpage, please re-enter the IP address of the ESP32 and reopen the webpage.
At the same time, the following messages will be returned from the ESP-AT command port:
+WEBSERVERRSP:1 // meaning that ESP32 has received Wi-Fi connection information
WIFI CONNECTED // meaning that ESP32 is connecting
WIFI GOT IP // meaning that ESP32 connect successfully to the destination router
+WEBSERVERRSP:2 // meaning that STA device has received Wi-Fi connection result, and web resources can be released
If the ESP32 fails to connect to the router, the web page will display:
Failed Connection to the Router
At the same time, the following messages will be returned from the ESP-AT command port:
+WEBSERVERRSP:1 // meaning that ESP32 has received Wi-Fi connection information, but failed to connect to the router.
Troubleshooting
Note 1: The network configuration page received a prompt “Connection failed”. Please check whether the Wi-Fi AP of the ESP32 module is correctly turned on, and the relevant configuration of the AP, and confirm that the correct AT command has been entered to successfully enable the web server.
OTA Firmware Upgrade Using a Browser
Introduction
After the browser opens the web page of the web server, you can choose to enter the OTA upgrade page to upgrade the firmware in the app partitions or the certificate binaries in other partitions (please refer to How to Update PKI Configuration for more about certificate information).
Introduction to Operation Steps
Open the OTA Configuration Page
As shown in the figure, click on the “OTA” option in the lower right corner of the web page, and after opening the OTA configuration page, you can view the current firmware version and AT Core version:
OTA Configuration Page
Note 1: The configuration interface can only be opened when the STA device is connected to the AP of the ESP32, or the STA device accessing the OTA configuration page is connected to the ESP32 in the same subnet.
Note 2: The “current app version” displayed on the webpage is the version number of the application. You can change the version number through ./build.py menuconfig –> Component config –> AT –> AT firmware version (see Compile ESP-AT Project Locally). In this case, you can manage your application firmware version.
Selecting the Partition to Upgrade
As shown in the figure, click the drop-down box of “Partition” to obtain all partitions that can be upgraded:
Obtaining All Partitions That Can Be Upgraded
Send the New Firmware
As shown in the figure, click the “Browse” button on the page and select the new firmware to be sent:
Selecting the New Firmware to Be Sent
Then you can click “OTA upgrade” button to send the firmware.
Note 1: For the ota partition, the web page will check the selected firmware. The suffix of the firmware name must be .bin. Please make sure that the firmware size does not exceed the size of the ota partition defined in the partitions_at.csv file. For more information on this file, please refer to How to Add Support for a Module.
Note 2: For other partitions, the web page will check the selected firmware. The suffix of the firmware name must be .bin. Please make sure that the firmware size does not exceed the size defined in the at_customize.csv file. For more information on this file, please refer to How to Customize Partitions.
Get the Result of OTA
As shown in the figure, if the ESP32 OTA successfully, it will prompt “OTA Succeeded”:
The New Firmware Sent Successfully
At the same time, the following messages will be returned from the ESP-AT command port:
+WEBSERVERRSP:3 // meaning that ESP32 begin to receive OTA data
+WEBSERVERRSP:4 // meaning that ESP32 has received all firmware data
If the ESP32 OTA failed, it will prompt “OTA Failed”:
Failed Sending of the New Firmware
At the same time, the following message will be received on the serial port:
+WEBSERVERRSP:3 // meaning that ESP32 begin to receive OTA data
+WEBSERVERRSP:5 // meaning a failure of receiving OTA data failed. You can choose to reopen the OTA configuration interface and follow the above steps to restart the firmware upgrade
Note 1: For the ota partition, you need to execute AT+RST to restart the ESP32 to apply the new firmware.
Note 2: ESP32 will only verify the received ota firmware content. The firmware data received by other partitions will not be verified, so please make sure its content is correct.
Wi-Fi Provisioning Using a WeChat Applet
Introduction
The WeChat applet can automatically connect to the WiFi AP of the ESP32, and then send the ssid and password required by the ESP32 to connect to the network.
Important
The ESP-AT WeChat applet will be discontinued on December 31, 2024. During this period, please make arrangements for the transition of its functionalities. If you still have related needs after this date, please contact Espressif’s business team. We will be dedicated to providing you with support and solutions. Thank you for your understanding and support.
Introduction to Operation Steps
The whole process can be divided into the following four steps:
Configure ESP32 Device Parameters
Firstly, ESP32 needs to be configured to softAP + STA mode, and creates a web server to wait for Wi-Fi provisioning messages. In this case, a mobile phone or a PC can connect to the ESP32 softAP as a station. The corresponding AT commands are as follows:
Clear the previous Wi-Fi provisioning information.
Command
AT+RESTORE
Set the Wi-Fi mode to Station+SoftAP.
Command
AT+CWMODE=3
Set the configuration of an ESP32 SoftAP. (For example, set the default connection ssid to “pos_softap”, and password to “espressif”.)
Command
AT+CWSAP="pos_softap","espressif",11,3,3
Note
By default, the WeChat applet initiates a connection to the SoftAP whose ssid is pos_softap and password is espressif. Please make sure to set the parameters of the ESP32 according to the above configuration.
Enable multiple connections.
Command
AT+CIPMUX=1
Create a web server, port: 80, connection timeout: 40 s (default maximum is 60 s).
Command
AT+WEBSERVER=1,80,40
Load WeChat Applet
Open the mobile phone WeChat, scan the following QR code:
Getting the QR Code of the Applet
Open the WeChat applet and enter the Wi-Fi provisioning interface:
Wi-Fi Provisioning Interface
Target AP Selection
After loading the WeChat applet, there are two situations according to different target AP:
Situation 1. If your target AP is the hotspot of the mobile phone which running the WeChat applet, please select the “Local phone hotspot” option box on the WeChat applet page.
Situation 2. If your target AP is just another AP, not as the special situation one as above, then please do not select the “Local phone hotspot” option box.
Use the WeChat Applet to Send Wi-Fi Connection Information
The target AP to be accessed is not the hotspot provided by the mobile phone which loading the WeChat applet.
Here, take connecting to a router as an example, the process of Wi-Fi Connection configuration is introduced:
1.Turn on the mobile Wi-Fi and connect to the router:
Connection to the Router
2.Open the WeChat applet, you can see that the applet page has automatically displayed the ssid of the current router as “FAST_FWR310_02”.
Getting Router Information
Note: If the ssid of the connected router is not displayed on the current page, please click “Re-enter applet” in the following figure to refresh the current page:
Re-entering the Applet
3.After entering the password of the router, click “Connect”.
Connection to the Router via the Applet
4.After the Wi-Fi connection is established successfully, the web page will be displayed as follows:
Successfully connection to the Router via the Applet
At the same time, the following messages will be returned from the ESP-AT command port:
+WEBSERVERRSP:1 // meaning that ESP32 has received Wi-Fi connection information
WIFI CONNECTED // meaning that ESP32 is connecting
WIFI GOT IP // meaning that ESP32 connect successfully to the destination router
+WEBSERVERRSP:2 // meaning that STA device has received Wi-Fi connection result, and web resources can be released
5.If the ESP32 fails to connect to the router, the page will display:
Failed Connection to the Router via the Applet
At the same time, the following messages will be returned from the ESP-AT command port:
+WEBSERVERRSP:1 // meaning that ESP32 has received Wi-Fi connection information, but failed to connect to the router.
The target AP to be accessed is the hotspot provided by the mobile phone which loading the WeChat applet.
If the target AP to be accessed is the hotspot provided by the mobile phone which loading the WeChat applet, it is not necessary to enter the ssid, but only needs to enter the password of the AP, and turn on the mobile AP in time according to the prompts.
Note
To use this function, keep at least the first five bytes of the phone’s Personal Hotspot MAC address the same as those of the WLAN MAC address.
1.Select the “Local phone hotspot” option box on the WeChat applet page, enter the password of the local hotspot, and click “Connect”.
Entering the Password of the AP
2.After receiving the prompt “Connecting to the mobile phone hotspot”, please check that the local mobile phone hotspot is turned on. At this time, the ESP32 will automatically scan the surrounding hotspots and initiate a connection.
Starting Connection to the AP
3.The display of the WiFi connection results on the applet page and the data output from the serial port are the same as the above-mentioned “The target AP to be accessed is not the hotspot provided by the mobile phone which loading the WeChat applet.”, please refer to the above.
Troubleshooting
Note 1: The Wi-Fi provisioning page received a prompt “Data transmission failed”. Please check whether the Wi-Fi AP of the ESP32 is correctly turned on, and the relevant configuration of the AP, and confirm that the correct AT command has been entered to successfully enable the web server.
Note 2: The Wi-Fi provisioning page receives a prompt “Failed to connect to the AP”. Please check whether the Wi-Fi connection function of the mobile phone is turned on, check whether the Wi-Fi AP of the ESP32 is correctly turned on, and whether the ssid and password of the AP are configured according to the above steps.
Note 3: The Wi-Fi provisioning page receives a prompt “The Wi-Fi provisioning saved by the system expired”. Please manually connect the ESP32 AP with a mobile phone, and confirm that the ssid and password of the ESP32 module have been configured according to the above steps.
OTA Firmware Upgrade Using a WeChat Applet
The WeChat applet support online firmware upgrade , please refer to the above-described Configure ESP32 Device Parameters specific steps performed ESP32 configuration (if the configuration has been completed, do not repeat configuration). Once configured, the device performs OTA firmware upgrade processes is similar as OTA Firmware Upgrade Using a Browser .
ESP32 Using Captive Portal
Introduction
Captive Portal is commonly used to present a specified page to newly connected devices of a Wi-Fi or wired network. For more information about Captive Portal, please refer to Captive Portal Wiki .
Note
The default firmware does not support web server Captive Portal, you may enable it by ./build.py menuconfig > Component config > AT > AT WEB Server command support > AT WEB captive portal support and build the project (see Compile ESP-AT Project Locally). In addition, enabling this feature may cause page skipping when using wechat applet for Wi-Fi provisioning or OTA firmware upgrade. It is recommended that this feature be enabled only when accessing at web using browser.
Introduction to Operation Steps
After Enable Captive Portal support, please refer to Use STA Device to Connect to ESP32 Device to complete the configuration of the ESP32, and then connect to the AP of the ESP32:
Connection to the AP with Captive Portal Enabled
As shown in the figure above, after the Station device is connected to the AP of the ESP32 with the Captive Portal function enabled, it will prompt “requires login/authentication”, and then the browser will automatically open and jump to the main interface of AT Web. If it cannot be redirected automatically, please follow the instructions of the Station device, click “Authentication” or click the name of the “pos_softap” hotspot in the figure above to manually trigger the Captive Portal to automatically open the browser and enter the main interface of AT Web.
Troubleshooting
Note 1: Both Station device and AP device support the Captive Portal function to ensure the normal use of this function. Therefore, if the device is connected to the AP of the ESP32, but it does not prompt “Login/Authentication”, it may be that the Station device does not support this function. In this case, please refer to the specific steps of Use the Browser to Send Wi-Fi Connection Information above to open the main interface of AT Web.