How to Customize Partitions¶
This document describes how to customize the partitions in your ESP device by modifying the at_customize.csv table provided by ESP-AT. There are two partition tables: the primary partition and the secondary partition table.
The primary partition table partitions_at.csv is for system usage, based on which the partitions_at.bin file is generated. If the primary partition table goes wrong, the system will fail to startup. Therefore, it is not recommended to modify the partitions_at.csv.
ESP-AT provides a secondary partition table at_customize.csv that you can customize to store self-defined blocks of data. It is based on the primary partition table.
To modify the partition in your ESP device, please follow the first three steps. The fourth section illustrates the three steps with an example.
Modify at_customize.csv¶
Find the at_customize.csv for your module with reference to the following table.
Platform |
Module |
Paths |
---|---|---|
ESP32 |
|
|
ESP32 |
WROVER-32 |
|
ESP32 |
ESP32-D2WD |
|
ESP32 |
ESP32_QCLOUD |
|
ESP32-C3 |
MINI-1 |
|
ESP32-C3 |
ESP32C3_QCLOUD |
Then, follow the rules below when modifying at_customize.csv.
Do not change the
Name
andType
of the user partitions that have already been defined in it, whileSubType
,Offset
, andSize
can be changed.If you need to add a new user partition, please check if it has already been defined in the ESP-IDF (
esp_partition.h
) first.If yes, you should keep the
Type
value the same as that of ESP-IDF.If no, please set the
Type
to0x40
.
A user partition’s
Name
should not be longer than16
bytes.The default size of the entire
at_customize
partition is defined in the partitions_at.csv table. Please do not exceed the range when adding new user partitions.
Generate at_customize.bin¶
After having modified the at_customize.csv, you can either recompile the ESP-AT project to generate the at_customize.bin file, or use the python script gen_esp32part.py
.
If you use the script, execute the following command under the root directory of ESP-AT project and replace INPUT
and OUTPUT
:
python esp-idf/components/partition_table/gen_esp32part.py <INPUT> [OUTPUT]
Replace
INPUT
with the path to at_customize.csv or the binary file to parse.Replace
OUTPUT
with the path to output converted binary or CSV file. Stdout will be used if omitted.
Flash at_customize.bin into ESP Device¶
Download the at_customize.bin into flash. Please refer to Flash AT Firmware into Your Device for how to flash bin files into ESP and the following table for the download address for your module.
Platform |
Module |
Address |
Size |
---|---|---|---|
ESP32 |
|
0x20000 |
0xE0000 |
ESP32-C3 |
MINI-1 |
0x1E000 |
0x42000 |
ESP32-C3 |
ESP32C3_QCLOUD |
0x20000 |
0xE0000 |
There are cases where at_customize.bin must be downloaded to flash in order to use certain AT commands:
SSL
server relevant commandsBLE
server relevant commands
Example¶
The section demonstrates how to add a 4 KB partition named test
into the ESP32-WROOM-32 module.
Firstly, find the at_customize.csv table for ESP32-WROOM-32 and set the Name
, Type
, Subtype
, Offset
, and Size
of the new partition:
# Name,Type,SubType,Offset,Size
... ...
test,0x40,15,0x3D000,4K
fatfs,data,fat,0x70000,576K
Secondly, recompile the ESP-AT project, or execute the python script in the ESP-AT root directory to generate at_customize.bin.
python esp-idf/components/partition_table/gen_esp32part.py -q ./module_config/module_esp32_default/at_customize.csv at_customize.bin
Then, the at_customize.bin will be generated in the ESP-AT root directory.
Thirdly, download the at_customize.bin to flash.
Execute the following command under the root directory of ESP-AT project and replace PORT
and BAUD
.
python esp-idf/components/esptool_py/esptool/esptool.py -p PORT -b BAUD --before default_reset --after hard_reset --chip auto write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x20000 ./at_customize.bin
Replace
PORT
with your port name.Replace
BAUD
with the baud rate.