.. _WiFi-AT: Wi-Fi AT Commands ================= :link_to_translation:`zh_CN:[中文]` - :ref:`AT+CWMODE `: Set the Wi-Fi mode (Station/SoftAP/Station+SoftAP). - :ref:`AT+CWSTATE `: Query the Wi-Fi state and Wi-Fi information. - :ref:`AT+CWJAP `: Connect to an AP. - :ref:`AT+CWRECONNCFG `: Query/Set the Wi-Fi reconnecting configuration. - :ref:`AT+CWLAPOPT `: Set the configuration for the command :ref:`AT+CWLAP `. - :ref:`AT+CWLAP `: List available APs. - :ref:`AT+CWQAP `: Disconnect from an AP. - :ref:`AT+CWSAP `: Query/Set the configuration of an ESP SoftAP. - :ref:`AT+CWLIF `: Obtain IP address of the station that connects to an ESP SoftAP. - :ref:`AT+CWQIF `: Disconnect stations from an ESP SoftAP. - :ref:`AT+CWDHCP `: Enable/disable DHCP. - :ref:`AT+CWDHCPS `: Query/Set the IP addresses allocated by an ESP SoftAP DHCP server. - :ref:`AT+CWAUTOCONN `: Connect to an AP automatically when powered on. - :ref:`AT+CWAPPROTO `: Query/Set the 802.11 b/g/n protocol standard of SoftAP mode. - :ref:`AT+CWSTAPROTO `: Query/Set the 802.11 b/g/n protocol standard of station mode. - :ref:`AT+CIPSTAMAC `: Query/Set the MAC address of an ESP station. - :ref:`AT+CIPAPMAC `: Query/Set the MAC address of an ESP SoftAP. - :ref:`AT+CIPSTA `: Query/Set the IP address of an ESP station. - :ref:`AT+CIPAP `: Query/Set the IP address of an ESP SoftAP. - :ref:`AT+CWSTARTSMART `: Start SmartConfig. - :ref:`AT+CWSTOPSMART `: Stop SmartConfig. - :ref:`AT+WPS `: Enable the WPS function. - :ref:`AT+MDNS `: Configure the mDNS function. - [ESP32 Only] :ref:`AT+CWJEAP `: Connect to a WPA2 Enterprise AP. - :ref:`AT+CWHOSTNAME `: Query/Set the host name of an ESP station. - :ref:`AT+CWCOUNTRY `: Query/Set the Wi-Fi Country Code. .. _cmd-MODE: :ref:`AT+CWMODE `: Query/Set the Wi-Fi Mode (Station/SoftAP/Station+SoftAP) ------------------------------------------------------------------------------------- Query Command ^^^^^^^^^^^^^ **Function:** Query the Wi-Fi mode of ESP devices. **Command:** :: AT+CWMODE? **Response:** :: +CWMODE: OK Set Command ^^^^^^^^^^^ **Function:** Set the Wi-Fi mode of ESP devices. **Command:** :: AT+CWMODE=[,] **Response:** :: OK Parameters ^^^^^^^^^^ - ****: - 0: Null mode. Wi-Fi RF will be disabled. - 1: Station mode. - 2: SoftAP mode. - 3: SoftAP+Station mode. - ****: Enable or disable automatic connection to an AP when you change the mode of the ESP device from the SoftAP mode or null mode to the station mode or the SoftAP+Station mode. Default: 1. If you omit the parameter, the default value will be used, i.e. automatically connecting to an AP. - 0: The ESP device will not automatically connect to an AP. - 1: The ESP device will automatically connect to an AP if the configuration to connect to the AP has already been saved in flash before. Note ^^^^^ - The configuration changes will be saved in the NVS area if :ref:`AT+SYSSTORE=1 `. Example ^^^^^^^^ :: AT+CWMODE=3 .. _cmd-STATE: :ref:`AT+CWSTATE `: Query the Wi-Fi state and Wi-Fi information ------------------------------------------------------------------------ Query Command ^^^^^^^^^^^^^ **Function:** Query the Wi-Fi state and Wi-Fi information of ESP devices. **Command:** :: AT+CWSTATE? **Response:** :: +CWSTATE:,<"ssid"> OK Parameters ^^^^^^^^^^ - ****: current Wi-Fi state. - 0: ESP station has not started any Wi-Fi connection. - 1: ESP station has connected to an AP, but does not get an IPv4 address yet. - 2: ESP station has connected to an AP, and got an IPv4 address. - 3: ESP station is in Wi-Fi connecting or reconnecting state. - 4: ESP station is in Wi-Fi disconnected state. - **<"ssid">**: the SSID of the target AP. Note ^^^^^ - When ESP station is not connected to an AP, it is recommended to use this command to query Wi-Fi information; after ESP station is connected to an AP, it is recommended to use :ref:`AT+CWJAP ` to query Wi-Fi information. .. _cmd-JAP: :ref:`AT+CWJAP `: Connect to an AP ------------------------------------------------ Query Command ^^^^^^^^^^^^^ **Function:** Query the AP to which the ESP Station is already connected. **Command:** :: AT+CWJAP? **Response:** :: +CWJAP:,,,,,,,, OK Set Command ^^^^^^^^^^^ **Function:** Connect an ESP station to a targeted AP. **Command:** :: AT+CWJAP=[],[][,][,][,][,][,][,][,] **Response:** :: WIFI CONNECTED WIFI GOT IP OK [WIFI GOT IPv6 LL] [WIFI GOT IPv6 GL] or :: +CWJAP: ERROR Execute Command ^^^^^^^^^^^^^^^ **Function:** Connect an ESP station to a targeted AP with last Wi-Fi configuration. **Command:** :: AT+CWJAP **Response:** :: WIFI CONNECTED WIFI GOT IP OK [WIFI GOT IPv6 LL] [WIFI GOT IPv6 GL] or :: +CWJAP: ERROR Parameters ^^^^^^^^^^ - ****: the SSID of the target AP. - Escape character syntax is needed if SSID or password contains special characters, such ``,``, ``"``, or ``\\``. - ****: password, MAX: 64-byte ASCII. - ****: the MAC address of the target AP. It cannot be omitted when multiple APs have the same SSID. - ****: channel. - ****: signal strength. - ****: PCI Authentication. - 0: The ESP station will connect APs with all encryption methods, including OPEN and WEP. - 1: The ESP station will connect APs with all encryption methods, except OPEN and WEP. - ****: the interval between Wi-Fi reconnections. Unit: second. Default: 1. Maximum: 7200. - 0: The ESP station will not reconnect to the AP when disconnected. - [1,7200]: The ESP station will reconnect to the AP at the specified interval when disconnected. - ****: the interval of listening to the AP's beacon. Unit: AP beacon intervals. Default: 3. Range: [1,100]. - ****: - 0: fast scan. It will end after finding the targeted AP. The ESP station will connect to the first scanned AP. - 1: all-channel scan. It will end after all the channels are scanned. The device will connect to the scanned AP with the strongest signal. - ****: maximum timeout for :ref:`AT+CWJAP ` command. Unit: second. Default: 15. Range: [3,600]. - ****: Protected Management Frames. Default: 0. - 0 means disable PMF. - bit 0: PMF capable, advertizes support for protected management frame. Device will prefer to connect in PMF mode if other device also advertizes PMF capability. - bit 1: PMF required, advertizes that protected management frame is required. Device will not associate to non-PMF capable devices. - ****: (for reference only) - 1: connection timeout. - 2: wrong password. - 3: cannot find the target AP. - 4: connection failed. - others: unknown error occurred. Notes ^^^^^ - The configuration changes will be saved in the NVS area if :ref:`AT+SYSSTORE=1 `. - This command requires Station mode to be enabled. - The parameter ```` of this command is the same as ```` of the command :ref:`AT+CWRECONNCFG `. Therefore, if you omit ```` when running this command, the interval between Wi-Fi reconnections will use the default value 1. - If the ```` and ```` parameter are omitted, AT will use the last configuration. - Execute command has the same maximum timeout to setup command. The default value is 15 seconds, but you can change it by setting the parameter ````. - To get an IPv6 address, you need to set :ref:`AT+CIPV6=1 `. - Response ``OK`` means that the IPv4 network is ready, but not the IPv6 network. At present, ESP-AT is mainly based on IPv4 network, supplemented by IPv6 network. - ``WIFI GOT IPv6 LL`` represents that the linklocal IPv6 address has been obtained. This address is calculated locally through EUI-64 and does not require the participation of the AP. Because of the parallel timing, this print may be before or after ``OK``. - ``WIFI GOT IPv6 GL`` represents that the global IPv6 address has been obtained. This address is combined by the prefix issued by AP and the suffix calculated internally, which requires the participation of the AP. Because of the parallel timing, this print may be before or after ``OK``, or it may not be printed because the AP does not support IPv6. Example ^^^^^^^^ :: // If the target AP's SSID is "abc" and the password is "0123456789", the command should be: AT+CWJAP="abc","0123456789" // If the target AP's SSID is "ab\,c" and the password is "0123456789"\", the command should be: AT+CWJAP="ab\\\,c","0123456789\"\\" // If multiple APs all have the SSID of "abc", the target AP can be found by BSSID: AT+CWJAP="abc","0123456789","ca:d7:19:d8:a6:44" // If esp-at is required that connect to a AP by protected management frame, the command should be: AT+CWJAP="abc","0123456789",,,,,,,3 .. _cmd-RECONNCFG: :ref:`AT+CWRECONNCFG `: Query/Set the Wi-Fi Reconnecting Configuration ------------------------------------------------------------------------------------------- Query Command ^^^^^^^^^^^^^ **Function:** Query the configuration of Wi-Fi reconnect. **Command:** :: AT+CWRECONNCFG? **Response:** :: +CWRECONNCFG:, OK Set Command ^^^^^^^^^^^ **Function:** Set the configuration of Wi-Fi reconnect. **Command:** :: AT+CWRECONNCFG=, **Response:** :: OK Parameters ^^^^^^^^^^ - ****: the interval between Wi-Fi reconnections. Unit: second. Default: 0. Maximum: 7200. - 0: The ESP station will not reconnect to the AP when disconnected. - [1,7200]: The ESP station will reconnect to the AP at the specified interval when disconnected. - ****: the number of attempts the ESP device makes to reconnect to the AP. This parameter only works when the parameter ```` is not 0. Default: 0. Maximum: 1000. - 0: The ESP station will always try to reconnect to AP. - [1,1000]: The ESP station will attempt to reconnect to AP for the specified times. Example ^^^^^^^^ :: // The ESP station tries to reconnect to AP at the interval of one second for 100 times. AT+CWRECONNCFG=1,100 // The ESP station will not reconnect to AP when disconnected. AT+CWRECONNCFG=0,0 Notes ^^^^^ - The parameter ```` of this command is the same as the parameter ``[]`` of the command :ref:`AT+CWJAP `. - This command works for passive disconnection from APs, Wi-Fi mode switch, and Wi-Fi auto connect after power on. .. _cmd-LAPOPT: :ref:`AT+CWLAPOPT `: Set the Configuration for the Command :ref:`AT+CWLAP ` ---------------------------------------------------------------------------------------------- Set Command ^^^^^^^^^^^ **Command:** :: AT+CWLAPOPT=,[,][,] **Response:** :: OK or :: ERROR Parameters ^^^^^^^^^^ - ****: reserved item. - ****: determine whether the following parameters are shown in the result of :ref:`AT+CWLAP `. Default: 0x7FF. If you set them to 1, it means showing the corresponding parameters; if you set them as 0, it means NOT showing the corresponding parameters. - bit 0: determine whether will be shown. - bit 1: determine whether will be shown. - bit 2: determine whether will be shown. - bit 3: determine whether will be shown. - bit 4: determine whether will be shown. - bit 5: determine whether will be shown. - bit 6: determine whether will be shown. - bit 7: determine whether will be shown. - bit 8: determine whether will be shown. - bit 9: determine whether will be shown. - bit 10: determine whether will be shown. - **[]**: determine whether the result of the command :ref:`AT+CWLAP ` will be filtered according to ``rssi filter``. In other words, the result of the command will **NOT** show the APs whose signal strength is below ``rssi filter``. Unit: dBm. Default: –100. Range: [–100,40]. - **[]**: determine whether APs with the following authmodes are shown in the result of :ref:`AT+CWLAP `. Default: 0xFFFF. If you set ``bit x`` to 1, the APs with the corresponding authmode will be shown. If you set ``bit x`` to 0, the APs with the corresponding authmode will NOT be shown; - bit 0: determine whether APs with ``OPEN`` authmode will be shown. - bit 1: determine whether APs with ``WEP`` authmode will be shown. - bit 2: determine whether APs with ``WPA_PSK`` authmode will be shown. - bit 3: determine whether APs with ``WPA2_PSK`` authmode will be shown. - bit 4: determine whether APs with ``WPA_WPA2_PSK`` authmode will be shown. - bit 5: determine whether APs with ``WPA2_ENTERPRISE`` authmode will be shown. - bit 6: determine whether APs with ``WPA3_PSK`` authmode will be shown. - bit 7: determine whether AP with ``WPA2_WPA3_PSK`` authmode will be shown. - [ESP32-C3 Only] bit 8: determine whether AP with ``WAPI_PSK`` authmode will be shown. Example ^^^^^^^^ :: // The first parameter is 1, meaning that the result of the command AT+CWLAP will be ordered according to RSSI; // The second parameter is 31, namely 0x1F, meaning that the corresponding bits of are set to 1. All parameters will be shown in the result of AT+CWLAP. AT+CWLAPOPT=1,31 AT+CWLAP // Just show the AP which authmode is OPEN AT+CWLAPOPT=1,31,-100,1 AT+CWLAP .. _cmd-LAP: :ref:`AT+CWLAP `: List Available APs ------------------------------------------------------ Set Command ^^^^^^^^^^^ **Function:** Query the APs with specified parameters, such as the SSID, MAC address, or channel. **Command:** :: AT+CWLAP=[,,,,,] Execute Command ^^^^^^^^^^^^^^^ **Function:** List all available APs. **Command:** :: AT+CWLAP **Response:** :: +CWLAP:,,,,,,,,,, OK Parameters ^^^^^^^^^^ - ****: encryption method. - 0: OPEN - 1: WEP - 2: WPA_PSK - 3: WPA2_PSK - 4: WPA_WPA2_PSK - 5: WPA2_ENTERPRISE - 6: WPA3_PSK - 7: WPA2_WPA3_PSK - [ESP32-C3 Only] 8: WAPI_PSK - ****: string parameter showing SSID of the AP. - ****: signal strength. - ****: string parameter showing MAC address of the AP. - ****: channel. - ****: Wi-Fi scan type: - 0: active scan - 1: passive scan - ****: the minimum active scan time per channel. Unit: millisecond. Range [0,1500]. If the scan type is passive, this parameter is invalid. - ****: the maximum active scan time per channel. Unit: millisecond. Range [0,1500]. If this parameter is 0, the firmware will use the default time: 120 ms for active scan; 360 ms for passive scan. - ****: frequency offset (reserved item). - ****: frequency calibration value (reserved item). - ****: pairwise cipher type. - 0: None - 1: WEP40 - 2: WEP104 - 3: TKIP - 4: CCMP - 5: TKIP and CCMP - 6: AES-CMAC-128 - 7: Unknown - ****: group cipher type, same enumerated value to ````. - ****: 802.11 b/g/n. If the corresponding bit is 1, the corresponding mode is enabled; if the corresponding bit is 0, the corresponding mode is disabled. - bit 0: bit to identify if 802.11b mode is enabled or not - bit 1: bit to identify if 802.11g mode is enabled or not - bit 2: bit to identify if 802.11n mode is enabled or not - ****: wps flag. - 0: WPS disabled - 1: WPS enabled Note ^^^^^ - For ESP8266 devices, **** and **** must be set to the same value. If these two parameters are omitted or both are set to 0 or the values are different, the firmware will use the default time: 120 ms for active scan; 360 ms for passive scan. Example ^^^^^^^^ :: AT+CWLAP="Wi-Fi","ca:d7:19:d8:a6:44",6,0,400,1000 // Search for APs with a designated SSID: AT+CWLAP="Wi-Fi" .. _cmd-QAP: :ref:`AT+CWQAP `: Disconnect from an AP ------------------------------------------------------ Execute Command ^^^^^^^^^^^^^^^ **Command:** :: AT+CWQAP **Response:** :: OK .. _cmd-SAP: :ref:`AT+CWSAP `: Query/Set the configuration of an ESP SoftAP ------------------------------------------------------------------------ Query Command ^^^^^^^^^^^^^ **Function:** Query the configuration parameters of an ESP SoftAP. **Command:** :: AT+CWSAP? **Response:** :: +CWSAP:,,,,,