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

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.

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

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)

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