User AT Commands

AT+USERRAM: Operate user’s free RAM.
AT+USEROTA: Upgrade the firmware according to the specified URL.
AT+USERDOCS: Query the ESP-AT user guide for current firmware.

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+USEROTA: Upgrade the Firmware According to the Specified URL

ESP-AT upgrades firmware at runtime by downloading the new firmware from a specific URL.

Set Command

Function:

Upgrade to the firmware version specified by the URL.

Command:

AT+USEROTA=<url len>

Response:

OK

>

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:

OK

If the parameter is wrong or firmware upgrades fails, the system returns:

ERROR

Parameters

<url len>: URL length. Maximum: 8192 bytes.

Note

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.
AT+USEROTA supports HTTP and HTTPS.
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+USEROTA command. Please refer to How to Generate PKI Files for PKI files. For AT+USEROTA command, ESP-AT project provides an example of USEROTA.
Please refer to How to Implement OTA Upgrade for more OTA commands.

Example

AT+USEROTA=36

OK

>
Recv 36 bytes

OK

AT+USERDOCS: Query the ESP-AT User Guide for Current Firmware

Query Command

Function:

Query the ESP-AT English and Chinese user guide for current running firmware.

Command:

AT+USERDOCS?

Response:

+USERDOCS:<"en url">
+USERDOCS:<"cn url">

OK

Parameters

<”en url”>: the URL for English document
<”cn url”>: the URL for Chinese document

Example

AT+USERDOCS?
+USERDOCS:"https://docs.espressif.com/projects/esp-at/en/latest/esp32c3/index.html"
+USERDOCS:"https://docs.espressif.com/projects/esp-at/zh_CN/latest/esp32c3/index.html"

OK

Provide feedback about this document