Basic AT Commands
AT: Test AT startup.
AT+RST: Restart a module.
AT+GMR: Check version information.
AT+CMD: List all AT commands and types supported in current firmware.
AT+GSLP: Enter Deep-sleep mode.
ATE: Configure AT commands echoing.
AT+RESTORE: Restore factory default settings of the module.
AT+UART_CUR: Current UART configuration, not saved in flash.
AT+UART_DEF: Default UART configuration, saved in flash.
AT+SLEEP: Set the sleep mode.
AT+SYSRAM: Query current remaining heap size and minimum heap size.
AT+SYSMSG: Query/Set System Prompt Information.
AT+SYSFLASH: Query/Set User Partitions in Flash.
AT+FS: Filesystem Operations.
AT+RFPOWER: Query/Set RF TX Power.
AT+SYSROLLBACK: Roll back to the previous firmware.
AT+SYSTIMESTAMP: Query/Set local time stamp.
AT+SYSLOG: Enable or disable the AT error code prompt.
AT+SLEEPWKCFG: Query/Set the light-sleep wakeup source and awake GPIO.
AT+SYSSTORE: Query/Set parameter store mode.
AT+SYSREG: Read/write the register.
AT+GMR: Check Version Information
Execute Command
Command:
AT+GMR
Response:
<AT version info>
<SDK version info>
<compile time>
<Bin version>
OK
Parameters
<AT version info>: information about the esp-at core library version, which is under the directory:
esp-at/components/at/lib/. Code is closed source, no plan to open.<SDK version info>: information about the esp-at platform sdk version, which is defined in file:
esp-at/module_config/module_{platform}_default/IDF_VERSION<compile time>: the time to compile the firmware.
<Bin version>: esp-at firmware version. Version information can be modified in menuconfig.
Note
If you have any issues on esp-at firmware, please provide
AT+GMRversion information firstly.
Example
AT+GMR
AT version:2.2.0.0-dev(ca41ec4 - ESP32 - Sep 16 2020 11:28:17)
SDK version:v4.0.1-193-ge7ac221b4
compile time(98b95fc):Oct 29 2020 11:23:25
Bin version:2.1.0(MINI-1)
OK
AT+CMD: List all AT commands and types supported in current firmware
Query Command
Command:
AT+CMD?
Response:
+CMD:<index>,<AT command name>,<support test command>,<support query command>,<support set command>,<support execute command>
OK
Parameters
<index>: AT command sequence number.
<AT command name>: AT command name.
<support test command>: 0 means not supported, 1 means supported.
<support query command>: 0 means not supported, 1 means supported.
<support set command>: 0 means not supported, 1 means supported.
<support execute command>: 0 means not supported, 1 means supported.
AT+GSLP: Enter Deep-sleep Mode
Parameter
<time>: the duration when the device stays in Deep-sleep. Unit: millisecond. When the time is up, the device automatically wakes up, calls Deep-sleep wake stub, and then proceeds to load the application.
0 means restarting right now
the maximum Deep-sleep time is about 28.8 days (2 31-1 milliseconds)
Notes
The theoretical and actual time of Deep-sleep may be different due to external factors.
AT+RESTORE: Restore Factory Default Settings
Notes
The execution of this command will restore all parameters saved in flash to factory default settings of the module.
The device will be restarted when this command is executed.
AT+UART_CUR: Current UART Configuration, Not Saved in Flash
Query Command
Command:
AT+UART_CUR?
Response:
+UART_CUR:<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
OK
Set Command
Command:
AT+UART_CUR=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
Response:
OK
Parameters
<baudrate>: UART baud rate
For ESP32 devices, the supported range is 80 ~ 5000000.
<databits>: data bits
5: 5-bit data
6: 6-bit data
7: 7-bit data
8: 8-bit data
<stopbits>: stop bits
1: 1-bit stop bit
2: 1.5-bit stop bit
3: 2-bit stop bit
<parity>: parity bit
0: None
1: Odd
2: Even
<flow control>: flow control
0: flow control is not enabled
1: enable RTS
2: enable CTS
3: enable both RTS and CTS
Notes
The Query Command will return actual values of UART configuration parameters, which may have minor differences from the set value because of the clock division.
The configuration changes will NOT be saved in flash.
To use hardware flow control, you need to connect CTS/RTS pins of your ESP32. For more details, please refer to Hardware Connection or
components/customized_partitions/raw_data/factory_param/factory_param_data.csv.
Example
AT+UART_CUR=115200,8,1,0,3
AT+UART_DEF: Default UART Configuration, Saved in Flash
Query Command
Command:
AT+UART_DEF?
Response:
+UART_DEF:<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
OK
Set Command
Command:
AT+UART_DEF=<baudrate>,<databits>,<stopbits>,<parity>,<flow control>
Response:
OK
Parameters
<baudrate>: UART baud rate
For ESP32 devices, the supported range is 80 ~ 5000000.
<databits>: data bits
5: 5-bit data
6: 6-bit data
7: 7-bit data
8: 8-bit data
<stopbits>: stop bits
1: 1-bit stop bit
2: 1.5-bit stop bit
3: 2-bit stop bit
<parity>: parity bit
0: None
1: Odd
2: Even
<flow control>: flow control
0: flow control is not enabled
1: enable RTS
2: enable CTS
3: enable both RTS and CTS
Notes
The configuration changes will be saved in the NVS area, and will still be valid when the chip is powered on again.
To use hardware flow control, you need to connect CTS/RTS pins of your ESP32. For more details, please refer to Hardware Connection or
components/customized_partitions/raw_data/factory_param/factory_param_data.csv.
Example
AT+UART_DEF=115200,8,1,0,3
AT+SLEEP: Set the Sleep Mode
Parameter
<sleep mode>:
0: Disable the sleep mode.
1: Modem-sleep mode.
Only Wi-Fi mode.
RF will be periodically closed according to AP
DTIM.
Only BLE mode.
RF will be periodically closed according to advertising interval ( BLE state in advertising ).
RF will be periodically closed according to connection interval ( BLE state in connection ).
2: Light-sleep mode.
Only Wi-Fi mode.
CPU will automatically sleep and RF will be periodically closed according to
listen intervalset by AT+CWJAP.
Only BLE mode.
CPU will automatically sleep and RF will be periodically closed according to advertising interval ( BLE state in advertising ).
CPU will automatically sleep and RF will be periodically closed according to connection interval ( BLE state in connection ).
3: Modem-sleep listen interval mode.
Only Wi-Fi mode.
RF will be periodically closed according to
listen intervalset by AT+CWJAP.
Only BLE mode.
RF will be periodically closed according to advertising interval ( BLE state in advertising ).
RF will be periodically closed according to connection interval ( BLE state in connection ).
Note
When sleep mode is disabled, you cannot initialize Bluetooth LE. When Bluetooth LE is initialized, you cannot disable sleep mode.
Modem-sleep mode and Light-sleep mode can be set under Wi-Fi mode or BLE mode, but in Wi-Fi mode, these two modes can only be set in
stationmode.Before setting the Light-sleep mode, it is recommended to set the wakeup source in advance through the command AT+SLEEPWKCFG, otherwise ESP32 can’t wake up and will always be in sleep mode.
After setting the Light-sleep mode, if the Light-sleep wakeup condition is not met, ESP32 will automatically enter the sleep mode. When the Light-sleep wakeup condition is met, ESP32 will automatically wake up from sleep mode.
For Light-sleep mode in BLE mode, users must ensure external 32KHz crystal oscillator, otherwise the Light-sleep mode will work in Modem-sleep mode.
For more examples, please refer to Sleep AT Examples.
Example
AT+SLEEP=0
AT+SYSRAM: Query Current Remaining Heap Size and Minimum Heap Size
Parameters
<remaining RAM size>: current remaining heap size. Unit: byte.
<minimum heap size>: minimum heap size that has ever been available. Unit: byte.
Example
AT+SYSRAM?
+SYSRAM:148408,84044
OK
AT+SYSMSG: Query/Set System Prompt Information
Query Command
Function:
Query the current system prompt information state.
Command:
AT+SYSMSG?
Response:
+SYSMSG:<state>
OK
Parameter
<state>:
Bit0: Prompt information when quitting Wi-Fi Passthrough Mode, Bluetooth LE SPP and Bluetooth SPP.
0: Print no prompt information when quitting Wi-Fi Passthrough Mode, Bluetooth LE SPP and Bluetooth SPP.
1: Print
+QUITTwhen quitting Wi-Fi Passthrough Mode, Bluetooth LE SPP and Bluetooth SPP.
Bit1: Connection prompt information type.
0: Use simple prompt information, such as
XX,CONNECT.1: Use detailed prompt information, such as
+LINK_CONN:status_type,link_id,ip_type,terminal_type,remote_ip,remote_port,local_port.
Bit2: Connection status prompt information for Wi-Fi Passthrough Mode, Bluetooth LE SPP and Bluetooth SPP.
0: Print no prompt information.
1: Print one of the following prompt information when Wi-Fi, socket, Bluetooth LE or Bluetooth status is changed:
- "CONNECT\r\n" or the message prefixed with "+LINK_CONN:" - "CLOSED\r\n" - "WIFI CONNECTED\r\n" - "WIFI GOT IP\r\n" - "WIFI GOT IPv6 LL\r\n" - "WIFI GOT IPv6 GL\r\n" - "WIFI DISCONNECT\r\n" - "+ETH_CONNECTED\r\n" - "+ETH_DISCONNECTED\r\n" - the message prefixed with "+ETH_GOT_IP:" - the message prefixed with "+STA_CONNECTED:" - the message prefixed with "+STA_DISCONNECTED:" - the message prefixed with "+DIST_STA_IP:" - the message prefixed with "+BLECONN:" - the message prefixed with "+BLEDISCONN:"
Notes
The configuration changes will be saved in the NVS area if
AT+SYSSTORE=1.If you set Bit0 to 1, it will prompt “+QUITT” when you quit Wi-Fi Passthrough Mode.
If you set Bit1 to 1, it will impact the information of command AT+CIPSTART and AT+CIPSERVER. It will supply “+LINK_CONN:status_type,link_id,ip_type,terminal_type,remote_ip,remote_port,local_port” instead of “XX,CONNECT”.
Example
// print no promt info when quitting Wi-Fi passthrough mode
// print detailed connection prompt info
// print no prompt info when the connection status is changed
AT+SYSMSG=2
or
// In the transparent transmission mode, a prompt message will be printed when the Wi-Fi, socket, Bluetooth LE or Bluetooth status changes
AT+SYSMSG=4
AT+SYSFLASH: Query/Set User Partitions in Flash
Query Command
Function:
Query user partitions in flash.
Command:
AT+SYSFLASH?
Response:
+SYSFLASH:<partition>,<type>,<subtype>,<addr>,<size>
OK
Set Command
Function:
Read/write the user partitions in flash.
Command:
AT+SYSFLASH=<operation>,<partition>,<offset>,<length>
Response:
+SYSFLASH:<length>,<data>
OK
Parameters
<operation>:
0: erase sector
1: write data into the user partition
2: read data from the user partition
<partition>: name of user partition
<offset>: offset of user partition
<length>: data length
<type>: type of user partition
<subtype>: subtype of user partition
<addr>: address of user partition
<size>: size of user partition
Notes
Please make sure that you have downloaded at_customize.bin before using this command. For more details, please refer to How to Customize Partitions.
Before downloading the secondary user partition, please refer How to Generate PKI Files to generate the binary user partition file.
When erasing the targeted user partition in its entirety, you can omit the parameters
<offset>and<length>. For example, commandAT+SYSFLASH=0,"ble_data"can erase the entire “ble_data” user partition. But if you want to keep the two parameters, they have to be 4KB-aligned.The introduction to partitions is in ESP-IDF Partition Tables.
If the operator is
write, wrap return>after the write command, then you can send the data that you want to write. The length should be parameter<length>.If the operator is
write, please make sure that you have already erased this partition.If the operator is
writeon a PKI bin, the<length>should be 4 bytes aligned.
Example
// read 100 bytes from the "ble_data" partition offset 0.
AT+SYSFLASH=2,"ble_data",0,100
// write 10 bytes to the "ble_data" partition offset 100.
AT+SYSFLASH=1,"ble_data",100,10
// erase 8192 bytes from the "ble_data" partition offset 4096.
AT+SYSFLASH=0,"ble_data",4096,8192
AT+FS: Filesystem Operations
Parameters
<type>: only FATFS is currently supported.
0: FATFS
<operation>:
0: delete file.
1: write file.
2: read file.
3: query the size of the file.
4: list files in a specific directory. Only root directory is currently supported.
<offset>: apply to writing and reading operations only.
<length>: data length, applying to writing and reading operations only.
Notes
Please make sure that you have downloaded at_customize.bin before using this command. For more details, refer to ESP-IDF Partition Tables and How to Customize Partitions.
If the length of the read data is greater than the actual file length, only the actual data length of the file will be returned.
If the operator is
write, wrap return>after the write command, then you can send the data that you want to write. The length should be parameter<length>.
Example
// delete a file.
AT+FS=0,0,"filename"
// write 10 bytes to offset 100 of a file.
AT+FS=0,1,"filename",100,10
// read 100 bytes from offset 0 of a file.
AT+FS=0,2,"filename",0,100
// list all files in the root directory.
AT+FS=0,4,"."
AT+RFPOWER: Query/Set RF TX Power
Query Command
Function:
Query the RF TX Power.
Command:
AT+RFPOWER?
Response:
+RFPOWER:<wifi_power>,<ble_adv_power>,<ble_scan_power>,<ble_conn_power>
OK
Set Command
Command:
AT+RFPOWER=<wifi_power>[,<ble_adv_power>,<ble_scan_power>,<ble_conn_power>]
Response:
OK
Parameters
<wifi_power>: the unit is 0.25 dBm. For example, if you set the value to 78, the actual maximum RF Power value is 78 * 0.25 dBm = 19.5 dBm. After you configure it, please confirm the actual value by entering the command
AT+RFPOWER?.For ESP32 devices, the range is [40,84]:
set value
get value
actual value
actual dBm
[40,43]
34
34
8.5
[44,51]
44
44
11
[52,55]
52
52
13
[56,59]
56
56
14
[60,65]
60
60
15
[66,71]
66
66
16.5
[72,77]
72
72
18
[78,84]
78
78
19.5
<ble_adv_power>: RF TX Power of Bluetooth LE advertising. Range: [0,7].
0: 7 dBm
1: 4 dBm
2: 1 dBm
3: -2 dBm
4: -5 dBm
5: -8 dBm
6: -11 dBm
7: -14 dBm
<ble_scan_power>: RF TX Power of Bluetooth LE scanning. The parameters are the same as
<ble_adv_power>.<ble_conn_power>: RF TX Power of Bluetooth LE connecting. The same as
<ble_adv_power>.
Note
Since the RF TX Power is actually divided into several levels, and each level has its own value range, the
wifi_powervalue queried by theesp_wifi_get_max_tx_powermay differ from the value set byesp_wifi_set_max_tx_powerand is no larger than the set value.
AT+SYSROLLBACK: Roll Back to the Previous Firmware
Note
This command will not upgrade via OTA. It only rolls back to the firmware which is in the other OTA partition.
AT+SYSTIMESTAMP: Query/Set Local Time Stamp
Query Command
Function:
Query the time stamp.
Command:
AT+SYSTIMESTAMP?
Response:
+SYSTIMESTAMP:<Unix_timestamp>
OK
Set Command
Function:
Set local time stamp. It will be the same as SNTP time when the SNTP time is updated.
Command:
AT+SYSTIMESTAMP=<Unix_timestamp>
Response:
OK
Parameter
<Unix-timestamp>: Unix timestamp. Unit: second.
Example
AT+SYSTIMESTAMP=1565853509 //2019-08-15 15:18:29
AT+SYSLOG: Enable or Disable the AT Error Code Prompt
Query Command
Function:
Query whether the AT error code prompt is enabled or not.
Command:
AT+SYSLOG?
Response:
+SYSLOG:<status>
OK
Set Command
Function:
Enable or disable the AT error code prompt.
Command:
AT+SYSLOG=<status>
Response:
OK
Parameter
<status>: enable or disable
0: disable
1: enable
Example
// enable AT error code prompt
AT+SYSLOG=1
OK
AT+FAKE
ERR CODE:0x01090000
ERROR
// disable AT error code prompt
AT+SYSLOG=0
OK
AT+FAKE
// No `ERR CODE:0x01090000`
ERROR
The error code is a 32-bit hexadecimal value and defined as follows:
category |
subcategory |
extension |
|---|---|---|
bit32 ~ bit24 |
bit23 ~ bit16 |
bit15 ~ bit0 |
category: stationary value 0x01.
subcategory: error type.
Subcategory of Error Code Error Type
Error Code
Description
ESP_AT_SUB_OK
0x00
OK
ESP_AT_SUB_COMMON_ERROR
0x01
reserved
ESP_AT_SUB_NO_TERMINATOR
0x02
terminator character not found (“rn” expected)
ESP_AT_SUB_NO_AT
0x03
Starting AT not found (or at, At or aT entered)
ESP_AT_SUB_PARA_LENGTH_MISMATCH
0x04
parameter length mismatch
ESP_AT_SUB_PARA_TYPE_MISMATCH
0x05
parameter type mismatch
ESP_AT_SUB_PARA_NUM_MISMATCH
0x06
parameter number mismatch
ESP_AT_SUB_PARA_INVALID
0x07
the parameter is invalid
ESP_AT_SUB_PARA_PARSE_FAIL
0x08
parse parameter fail
ESP_AT_SUB_UNSUPPORT_CMD
0x09
the command is not supported
ESP_AT_SUB_CMD_EXEC_FAIL
0x0A
the command execution failed
ESP_AT_SUB_CMD_PROCESSING
0x0B
processing of previous command is in progress
ESP_AT_SUB_CMD_OP_ERROR
0x0C
the command operation type is error
extension: error extension information. There are different extensions for different subcategory. For more information, please see the
components/at/include/esp_at.h.
For example, the error code ERR CODE:0x01090000 means the command is not supported.
AT+SLEEPWKCFG: Set the Light-sleep Wakeup Source and Awake GPIO
Parameters
<wakeup source>:
0: reserved, not supported now.
1: reserved, not supported now.
2: wakeup by GPIO.
<param1>:
If the wakeup source is a timer, it means the time before wakeup. Unit: millisecond.
If the wakeup source is GPIO, it means the GPIO number.
<param2>:
If the wakeup source is GPIO, it means the wakeup level:
0: low level.
1: high level.
Example
// GPIO12 wakeup, low level
AT+SLEEPWKCFG=2,12,0
AT+SYSSTORE: Query/Set Parameter Store Mode
Query Command
Function:
Query the AT parameter store mode.
Command:
AT+SYSSTORE?
Response:
+SYSSTORE:<store_mode>
OK
Parameter
<store_mode>:
0: command configuration is not stored into flash.
1: command configuration is stored into flash. (Default)
Note
This command affects set commands only. Query commands are always fetched from RAM.
Affected commands:
Examples
AT+SYSSTORE=0
AT+CWMODE=1 // Not stored into flash
AT+CWJAP="test","1234567890" // Not stored into flash
AT+SYSSTORE=1
AT+CWMODE=3 // Stored into flash
AT+CWJAP="test","1234567890" // Stored into flash
AT+SYSREG: Read/Write the Register
Set Command
Command:
AT+SYSREG=<direct>,<address>[,<write value>]
Response:
+SYSREG:<read value> // Only in read mode
OK
Parameters
<direct>: read or write register.
0: read register.
1: write register.
<address>: (uint32) register address. You can refer to Technical Reference Manuals.
<write value>: (uint32) write value (only in write mode).
Note
AT does not check address. Make sure that the registers you are operating on are valid.