User AT Commands
AT+USERRAM: Operate user’s free RAM.
AT+USEROTA: Upgrade the firmware according to the specified URL.
AT+USERWKMCUCFG: Configure how AT wakes up MCU.
AT+USERMCUSLEEP: MCU indicates its sleep state.
AT+USERDOCS: Query the ESP-AT user guide for current firmware.
The default AT firmware supports all the AT commands mentioned on this page. If you don’t need ESP32 to support user commands, you can compile the ESP-AT project by following the steps in Compile ESP-AT Project Locally documentation. In the project configuration during the fifth step, make the following selections:
AT user command support
AT+USERRAM: Operate user’s free RAM
Query the current available user’s RAM size.
Operate user’s free RAM
+USERRAM:<length>,<data> // esp-at returns this response only when the operator is ``read`` OK
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
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
If the operator is
readand 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
// 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+USEROTA: Upgrade the Firmware According to the Specified URL
ESP-AT upgrades firmware at runtime by downloading the new firmware from a specific URL.
Upgrade to the firmware version specified by the URL.
This response indicates that AT is ready for receiving URL. You should enter the URL, and when the URL length reaches the
<url len> value, the system returns:
Recv <url len> bytes
After AT outputs the above information, the upgrade process starts. If the upgrade process is complete, the system return:
If the parameter is wrong or firmware upgrades fails, the system returns:
<url len>: URL length. Maximum: 8192 bytes.
OTA firmware is
The speed of the upgrade depends on the network status.
If the upgrade fails due to unfavorable network conditions, AT will return
ERROR. Please wait for some time before retrying.
After you upgrade the AT firmware, you are suggested to call the command AT+RESTORE to restore the factory default settings.
After AT outputs the
>character, the special characters in the URL does not need to be escaped through the escape character, and it does not need to end with a new line(CR-LF).
When the URL is
HTTPS, SSL verification is not recommended. If SSL verification is required, you need to generate your own PKI files and download them into the corresponding partition, and then load the certificates in the code implemented by the
AT+USEROTAcommand. Please refer to How to Update PKI Configuration for PKI files. For
AT+USEROTAcommand, ESP-AT project provides an example of USEROTA.
Please refer to How to Implement OTA Upgrade for more OTA commands.
AT+USEROTA=36 OK > Recv 36 bytes OK
AT+USERWKMCUCFG: Configure How AT Wakes Up MCU
This command configures how AT checks whether MCU is in awake state and how to wake it up.
If MCU is in awake state, AT will directly send the data to it without waking it up.
If MCU is in sleep state and AT is ready to actively send the data to MCU (the data sent actively is same to ESP-AT Message Reports), AT will send wake signals to wake it up first and then send the data to it. Wake signals will be cleared after MCU is waked up or timeout.
AT+USERWKMCUCFG=<enable>,<wake mode>,<wake number>,<wake signal>,<delay time>[,<check mcu awake method>]
<enable>: Enable or disable wake-up configuration.
0: Disable wake-up configuration
1: Enable wake-up configuration
<wake mode>: wake mode.
1: GPIO wake-up
2: UART wake-up
<wake number>: It means differently depending on the parameter
<wake mode>is 1,
<wake number>represents GPIO number for wake-up. You need to ensure that the configured GPIO wake-up pin is not used for other purposes. Otherwise, you need to perform compatibility processing.
<wake mode>is 2,
<wake number>represents UART number. Currently, only 1 is supported for
<wake number>, which means only UART1 can wake up MCU.
<wake signal>: It means differently depending on the parameter
<wake mode>is 1,
<wake signal>represents wake-up level.
0: low level
1: high level
<wake mode>is 2,
<wake signal>represents wake-up byte. Range: [0,255].
<delay time>: Maximum waiting time. Unit: milliseconds. Range: [0,60000]. It means differently depending on the parameter
<wake mode>is 1, the
<wake signal>level will be held on during the
<delay time>. After the
<delay time>is reached, the
<wake signal>level is reversed.
<wake mode>is 2, AT will send
<wake signal>byte immediately and wait until timeout.
<check mcu awake method>: AT checks whether MCU is in awake state.
Bit 0: Whether to enable AT+USERMCUSLEEP command linkage. Enabled by default. That is, when receiving AT+USERMCUSLEEP=0 command from MCU, AT knows that MCU is in awake state; when receiving AT+USERMCUSLEEP=1 command, AT knows that MCU is in sleep.
Bit 1: Whether to enable AT+SLEEP=0/1/2/3 command linkage. Disabled by default. That is, when receiving AT+SLEEP=0 command, AT knows that MCU is in awake state; when receiving AT+SLEEP=1/2/3 command, AT knows that MCU is in sleep.
Bit 2: Whether to enable the function of indicating MCU state after
<delay time>timeout. Disabled by default. That is, when disabled, it indicates that MCU is in sleep after
<delay time>; when enabled, it indicates that MCU is in awake state after
Bit 3 (not implemented yet): Whether to enable the function of indicating MCU state via GPIO. Unsupported by default.
This command needs to be configured only once.
Each time before the AT actively sends data to MCU, it will send a wake-up signal first and then enter the waiting time. When
<delay time>is reached, it will directly send data. This wait timeout will reduce the transmission efficiency with MCU.
If AT receives any wake-up event in
<check mcu wake method>before
<delay time>, it will immediately clear the wake-up state; otherwise, the wake-up state will be cleared automatically after the
// Enable wake-up MCU configuration. Before each time the AT sends data to the MCU, it will first use the GPIO18 pin of the Wi-Fi module to wake up the MCU at a high level and hold on the high level for 10 seconds. AT+USERWKMCUCFG=1,1,18,1,10000,3 // Enable wake-up configuration AT+USERWKMCUCFG=0
AT+USERMCUSLEEP: MCU Indicates Its Sleep State
This command can only be taken effect when the
<check mcu wake method> Bit 0 of the AT+USERWKMCUCFG command is configured. It used to inform AT that the current MCU sleep state.
0: Indicates that MCU is in awake state.
1: Indicates that MCU is in sleep state.
// MCU tells AT that the current MCU is in awake state AT+USERMCUSLEEP=0
AT+USERDOCS: Query the ESP-AT User Guide for Current Firmware
Query the ESP-AT English and Chinese user guide for current running firmware.
+USERDOCS:<"en url"> +USERDOCS:<"cn url"> OK
<”en url”>: the URL for English document
<”cn url”>: the URL for Chinese document
AT+USERDOCS? +USERDOCS:"https://docs.espressif.com/projects/esp-at/en/latest/esp32/index.html" +USERDOCS:"https://docs.espressif.com/projects/esp-at/zh_CN/latest/esp32/index.html" OK