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+FSMOUNT: Mount/Unmount Filesystem.

• 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-C2 - 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 ³¹-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-C2 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 ESP32-C2. 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-C2 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 ESP32-C2. 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

• When sleep mode is disabled, you cannot initialize Bluetooth LE. When Bluetooth LE is initialized, you cannot disable sleep mode.

• 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 ESP32-C2 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, ESP32-C2 will automatically enter the sleep mode. When the Light-sleep wakeup condition is met, ESP32-C2 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.

• 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 available heap size in the runtime. Unit: byte. When the parameter’s value is less than or close to 10 KB, the Wi-Fi and BLE functions of ESP32-C2 may be affected.

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

• This command will automatically mount the filesystem. After the AT+FS filesystem operation is all done, it is strongly recommended to use the AT+FSMOUNT=0 command to unmount the filesystem to free a large amount of RAM space.

• 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+FSMOUNT: Mount/Unmount Filesystem

Set Command

Command:

AT+FSMOUNT=<mount>

Response:

OK

Parameters

• <mount>:

  • 0: Unmount filesystem

  • 1: Mount filesystem

Notes

• After the AT+FS filesystem operation is all done, it is strongly recommended to use the AT+FSMOUNT=0 command to unmount the filesystem to free a large amount of RAM space.

Example

// unmount the filesystem manually
AT+FSMOUNT=0

// mount the filesystem manually
AT+FSMOUNT=1

AT+RFPOWER: Query/Set RF TX Power

Query Command

Function:

Query the RF TX Power.

Command:

AT+RFPOWER?

Response:

+RFPOWER:<wifi_power>
OK

Set Command

Command:

AT+RFPOWER=<wifi_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-C2 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

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

• ESP32C2-4MB AT firmware supports this command, but ESP32C2-2MB AT firmware does not due to the compressed OTA firmware.

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

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:

• 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

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