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 set AT+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.

    • 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, command AT+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 the esp_wifi_get_max_tx_power may differ from the value set by esp_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.

    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

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

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