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+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¶
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)
- For ESP32 devices:
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.
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 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¶
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.
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.
- 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
.
- 0: Use simple prompt information, such as
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¶
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¶
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¶
Parameters¶
<wakeup source>:
- 0: wakeup by a timer.
- 1: reserved.
- 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¶
// Timer wakeup
AT+SLEEPWKCFG=0,1000
// 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:
- AT+SYSMSG
- AT+CWMODE
- AT+CIPV6
- AT+CWJAP
- AT+CWSAP
- AT+CWRECONNCFG
- AT+CIPAP
- AT+CIPSTA
- AT+CIPAPMAC
- AT+CIPSTAMAC
- AT+CIPDNS
- AT+CIPSSLCCONF
- AT+CIPRECONNINTV
- AT+CIPTCPOPT
- AT+CWDHCPS
- AT+CWDHCP
- AT+CWSTAPROTO
- AT+CWAPPROTO
- AT+CWJEAP
- AT+CIPETH
- AT+CIPETHMAC
- AT+BLENAME
- AT+BTNAME
- AT+BLEADVPARAM
- AT+BLEADVDATA
- AT+BLEADVDATAEX
- AT+BLESCANRSPDATA
- AT+BLESCANPARAM
- AT+BTSCANMODE
- AT+BLECONNPARAM
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