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+USERRAM: Operate user’s free RAM.
AT+SYSFLASH: Query/Set User Partitions in Flash.
[ESP32 Only] 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.
[ESP32-S2 Only] AT+SYSTEMP: Read ESP32-S2 internal temperature.
AT: Test AT Startup¶
Execute Command¶
Command:
AT
Response:
OK
AT+RST: Restart a Module¶
Execute Command¶
Command:
AT+RST
Response:
OK
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+GMR
version 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¶
Set Command¶
Command:
AT+GSLP=<time>
Response:
<time>
OK
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.
For ESP32 devices:
0 means restarting right now
the maximum Deep-sleep time is about 28.8 days (2 31-1 milliseconds)
For ESP32-S2 devices:
0 means staying in Deep-sleep mode forever
the maximum Deep-sleep time is about 28.8 days (2 31-1 milliseconds)
For ESP8266 devices:
0 means staying in Deep-sleep mode forever
the maximum Deep-sleep time is about 3 hours (due to hardware limitation, more time will lead to setting failure or internal time overflow)
Notes¶
For ESP8266 devices, you must connect GPIO16 to RST pin to wake them up automatically when time is up.
For all devices, affected by external factors, the theoretical and actual time of Deep-sleep will be different.
ESP8266 devices can be waken up from Deep-sleep by directly triggering the RST pin low-level pulse.
ATE: Configure AT Commands Echoing¶
Execute Command¶
Command:
ATE0
or
ATE1
Response:
OK
Parameters¶
ATE0: Switch echo off.
ATE1: Switch echo on.
AT+RESTORE: Restore Factory Default Settings¶
Execute Command¶
Command:
AT+RESTORE
Response:
OK
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 and ESP32-S2 devices, the supported range is 80 ~ 5000000.
For ESP8266 devices, the supported rang is 80 ~ 4500000.
<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 ESP device. 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 and ESP32-S2 devices, the supported range is 80 ~ 5000000.
For ESP8266 devices, the supported rang is 80 ~ 4500000.
<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 ESP device. 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¶
Query Command¶
Command:
AT+SLEEP?
Response:
+SLEEP:<sleep mode>
OK
Set Command¶
Command:
AT+SLEEP=<sleep mode>
Response:
OK
Parameter¶
<sleep mode>:
0: Disable the sleep mode.
1: Modem-sleep DTIM mode. RF will be periodically closed according to AP DTIM.
2: Light-sleep mode. CPU will automatically sleep and RF will be periodically closed according to
listen interval
set by AT+CWJAP.3: Modem-sleep listen interval mode. RF will be periodically closed according to
listen interval
set by AT+CWJAP.
Note¶
Modem-sleep mode and Light-sleep mode can be set only in station mode.
Before setting the Light-sleep mode, it is recommended to set the wakeup source in advance through the command AT+SLEEPWKCFG, otherwise ESP devices 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, ESP devices will automatically enter the sleep mode. When the Light-sleep wakeup condition is met, ESP devices will automatically wake up from sleep mode.
The query command can return 0, 1, 3, but not 2 (Due to query is not supported by ESP-IDF). That is to say,
AT+SLEEP?
will return 3 but not 2, if setAT+SLEEP=2
.
Example¶
AT+SLEEP=0
AT+SYSRAM: Query Current Remaining Heap Size and Minimum Heap Size¶
Query Command¶
Command:
AT+SYSRAM?
Response:
+SYSRAM:<remaining RAM size>,<minimum heap size>
OK
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
Set Command¶
Function:
Configure system prompt information.
Command:
AT+SYSMSG=<state>
Response:
OK
Parameter¶
<state>:
Bit0: Prompt information when quitting Wi-Fi Passthrough Mode.
0: Print no prompt information when quitting Wi-Fi Passthrough Mode.
1: Print
+QUITT
when quitting Wi-Fi Passthrough Mode.
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
AT+USERRAM: Operate user’s free RAM¶
Query Command¶
Function:
Query the current available user’s RAM size.
Command:
AT+USERRAM?
Response:
+USERRAM:<size>
OK
Set Command¶
Function:
Operate user’s free RAM
Command:
AT+USERRAM=<operation>,<size>[,<offset>]
Response:
- ::
+USERRAM:<length>,<data> // esp-at returns this response only when the operator is
read
OK
Parameters¶
<operation>:
0: release user’s RAM
1: malloc user’s RAM
2: write user’s RAM
3: read user’s RAM
4: clear user’s RAM
<size>: the size to malloc/read/write
<offset>: the offset to read/write. Default: 0
Notes¶
Please malloc the RAM size before you perform any other operations.
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
read
and the length is bigger than 1024, ESP-AT will reply multiple times in the same format, each reply can carry up to 1024 bytes of data, and eventually end up with\r\nOK\r\n
.
Example¶
// malloc 1 KB user's RAM
AT+USERRAM=1,1024
// write 500 bytes to RAM (offset: 0)
AT+USERRAM=2,500
// read 64 bytes from RAM offset 100
AT+USERRAM=3,64,100
// free the user's RAM
AT+USERRAM=0
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 The Secondary Partitions Table.
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
write
on 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
[ESP32 Only] AT+FS: Filesystem Operations¶
Set Command¶
Command:
AT+FS=<type>,<operation>,<filename>,<offset>,<length>
Response:
OK
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 The Secondary Partitions Table.
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 and ESP32-S2 devices, the range is [40,78]:
set value
actual value
actual dBm
[34,43]
34
8.5
[44,51]
44
11
[52,55]
52
13
[56,59]
56
14
[60,65]
60
15
[66,71]
66
16.5
[72,77]
72
18
78
78
19.5
For ESP32-C3 devices, the range is [40,84]:
set value
actual value
actual dBm
[40,80]
<set value>
<set value> * 0.25
[81,84]
80
20
For ESP8266 devices, the range is [40,82]:
set value
actual value
actual dBm
[40,47]
32
8
[48,55]
48
12
[56,63]
56
14
[64,67]
64
16
[68,73]
68
17
[74,77]
74
18.5
[78,81]
78
19.5
82
82
20.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. Range: [0,7]: the parameters are the same as
<ble_adv_power>
.<ble_conn_power>: RF TX Power of Bluetooth LE connecting. Range: [0,7]: 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_power
value queried by theesp_wifi_get_max_tx_power
may differ from the value set byesp_wifi_set_max_tx_power
and is no larger than the set value.
AT+SYSROLLBACK: Roll Back to the Previous Firmware¶
Execute Command¶
Command:
AT+SYSROLLBACK
Response:
OK
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.
¶ 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¶
Set Command¶
Command:
AT+SLEEPWKCFG=<wakeup source>,<param1>[,<param2>]
Response:
OK
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.
Note¶
GPIO16 as the RTC IO can not be set as GPIO wakeup source on ESP8266 platform for light sleep.
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
Set Command¶
Command:
AT+SYSSTORE=<store_mode>
Response:
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.
Example¶
// Enable ESP32-S2 IO33 output, 0x3F40402C means base address 0x3F404000 add relative address 0x2C (GPIO_ENABLE1_REG)
AT+SYSREG=1,0x3F40402C,0x2
// ESP32-S2 IO33 output high
AT+SYSREG=1,0x3F404010,0x2
// ESP32-S2 IO33 output low
AT+SYSREG=1,0x3F404010,0x0
[ESP32-S2 Only] AT+SYSTEMP: Read ESP32-S2 Internal Temperature¶
Query Command¶
Command:
AT+SYSTEMP?
Response:
+SYSTEMP:<temperature>
OK
Parameter¶
<temperature>: the measured output value. Unit: Celsius.
Note¶
Measure range: -10℃ ~ 80℃. Error < 1℃.
Example¶
AT+SYSTEMP?
+SYSTEMP:21.59
OK