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: 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.

    • 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.

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-C3 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 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-C3 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 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 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 interval set 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 interval set 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

  • 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 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.

  • 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. At present, AT only supports Light-sleep of ESP32 to work in Modem-sleep without external 32KHz crystal oscillator.

  • For more examples, please refer to Sleep AT Examples.

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, 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 +QUITT when 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, 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

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 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

    • For ESP32-C3 devices, the range is [40,84]:

      set value

      get value

      actual value

      actual dBm

      [40,80]

      <set value>

      <set value>

      <set value> * 0.25

      [81,84]

      <set value>

      80

      20

  • <ble_adv_power>: RF TX Power of Bluetooth LE advertising. Range: [0,7].

    • For ESP32 devices

      • 0: 7 dBm

      • 1: 4 dBm

      • 2: 1 dBm

      • 3: -2 dBm

      • 4: -5 dBm

      • 5: -8 dBm

      • 6: -11 dBm

      • 7: -14 dBm

    • For ESP32C3 devices

      • 0: -27 dBm

      • 1: -24 dBm

      • 2: -21 dBm

      • 3: -18 dBm

      • 4: -15 dBm

      • 5: -12 dBm

      • 6: -9 dBm

      • 7: -6 dBm

      • 8: -3 dBm

      • 9: -0 dBm

      • 10: 3 dBm

      • 11: 6 dBm

      • 12: 9 dBm

      • 13: 12 dBm

      • 14: 15 dBm

      • 15: 18 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_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: 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.

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

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.

Provide feedback about this document