How to Customize Partitions

[中文]

This document describes how to customize the partitions in your ESP32-C2 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 ESP32-C2, please follow the first three steps. The fourth section illustrates the three steps with an example.

Modify at_customize.csv
Generate at_customize.bin
Flash at_customize.bin into ESP32-C2 Device
Example

Modify at_customize.csv

Find the at_customize.csv for your module with reference to the following table.

at_customize.csv paths
Platform	Module	Path
ESP32-C2	ESP32C2-2MB (all ESP32-C2 (ESP8684) series with 2 MB flash)	module_config/module_esp32c2-2mb/at_customize.csv
ESP32-C2	ESP32C2-4MB (all ESP32-C2 (ESP8684) series with 4 MB flash)	module_config/module_esp32c2_default/at_customize.csv

Then, follow the rules below when modifying at_customize.csv.

Do not change the Name and Type of the user partitions that have already been defined in it, while SubType, Offset, and Size 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 to 0x40.
A user partition’s Name should not be longer than 16 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 ESP32-C2 Device

Download the at_customize.bin into flash. Please refer to Flash AT Firmware into Your Device for how to flash bin files into ESP32-C2 device and the following table for the download address for your module.

Download Address of at_customize.bin in Modules
Platform	Module	Address	Size
ESP32-C2	ESP32C2-2MB (all ESP32-C2 (ESP8684) series with 2 MB flash)	0x1A000	0x26000
ESP32-C2	ESP32C2-4MB (all ESP32-C2 (ESP8684) series with 4 MB flash)	0x1E000	0x42000

There are cases where at_customize.bin must be downloaded to flash in order to use certain AT commands:

AT+SYSFLASH: Query/Set User Partitions in Flash
AT+FS: Filesystem Operations
SSL server relevant commands
BLE server relevant commands

Example

The section demonstrates how to add a 4 KB partition named test into the ESP8684-MINI-1 4MB module.

Firstly, find the at_customize.csv table for ESP8684-MINI-1 4MB and set the Name, Type, Subtype, Offset, and Size of the new partition:

# Name,Type,SubType,Offset,Size
... ...
test,0x40,15,0x3E000,4K
fatfs,data,fat,0x47000,100K

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_esp32c2_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 0x1E000 ./at_customize.bin

Replace PORT with your port name.
Replace BAUD with the baud rate.

Provide feedback about this document