How to Customize Partitions

[中文]

This document describes how to customize the partitions in your ESP32-S2 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-S2, 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.

at_customize.csv paths

Platform

Module

Path

ESP32-S2

MINI (all ESP32-S2 series with 4 MB flash)

module_config/module_esp32s2_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-S2 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-S2 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-S2

MINI

0x20000

0xE0000

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

Example

The section demonstrates how to add a 4 KB partition named test into the ESP32-S2-MINI module.

Firstly, find the at_customize.csv table for ESP32-S2-MINI 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_esp32s2_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.

Provide feedback about this document