Skip to content

Commit 6186fef

Browse files
thelastoutpostworkshopthelastoutpostworkshop
committed
expand README user guide
1 parent ee9ac95 commit 6186fef

1 file changed

Lines changed: 94 additions & 13 deletions

File tree

‎README.md‎

Lines changed: 94 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,118 @@
11
# ESP32 Partition Builder Web Application
22

3-
The web application is [here](https://thelastoutpostworkshop.github.io/ESP32PartitionBuilder/).
3+
ESP32 Partition Builder is a browser-based tool for designing ESP32 partition table CSV files.
4+
5+
The web application is available here: [ESP32 Partition Builder](https://thelastoutpostworkshop.github.io/ESP32PartitionBuilder/).
6+
7+
## YouTube Tutorial
48

5-
## Youtube Tutorial
69
[<img src="https://github.com/thelastoutpostworkshop/images/blob/main/Custom%20Partitions.png" width="300">](https://youtu.be/EuHxodrye6E)
710

811
<a href="https://www.buymeacoffee.com/thelastoutpostworkshop" target="_blank">
912
<img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee">
1013
</a>
1114

15+
## Features
16+
17+
- Build partition tables from guided presets or individual partition rows.
18+
- Import, paste, copy, and download ESP-IDF partition CSV files.
19+
- Visualize used and unused flash memory.
20+
- Configure flash size and partition table offset.
21+
- Preserve fixed offsets when importing CSV layouts.
22+
- Add custom partition rows with editable type, subtype, offset, size, and flags.
23+
- Use the built-in ESP-IDF Zigbee preset with `zb_storage` and `zb_fct` partitions.
24+
- Check OTA support and NVS requirements.
25+
- View target chip flashing hints for common ESP32-family chips.
26+
- Open related Maker Tools from the Resources section.
27+
28+
## Quick Workflow
29+
30+
1. Select the correct flash size for your board.
31+
2. Choose a built-in partition preset or add partitions manually.
32+
3. Leave offsets blank when you want the table to auto-align partitions.
33+
4. Use the visualizer and available flash memory indicator to check the layout.
34+
5. Copy or download the generated `partitions.csv`.
35+
6. Use the CSV in your ESP-IDF, Arduino, PlatformIO, or related ESP32 build flow.
36+
37+
## CSV And Custom Partitions
38+
39+
The app supports the ESP-IDF partition CSV format:
40+
41+
```csv
42+
# Name, Type, SubType, Offset, Size, Flags
43+
nvs,data,nvs,0x9000,0x5000,
44+
factory,app,factory,0x10000,0x100000,
45+
```
46+
47+
Offsets can be fixed or left blank. Blank offsets are recalculated using the selected partition table offset and ESP-IDF alignment rules.
48+
49+
Custom rows are useful for framework-specific layouts such as Zigbee, Matter, manufacturing data, certificates, or other vendor-defined partitions. Custom rows support editable names, numeric or named types, subtypes, sizes, offsets, and flags such as `encrypted` or `readonly`.
50+
51+
## Zigbee Partitions
52+
53+
Use the `Zigbee ESP-IDF` built-in preset for ESP-IDF Zigbee projects. It includes the required Zigbee storage partitions:
54+
55+
```csv
56+
zb_storage,data,nvs,,16K,
57+
zb_fct,data,fat,,1K,
58+
```
59+
60+
For Arduino or PlatformIO Zigbee projects, confirm the partition requirements for the framework version you are using. Some older Arduino-based examples use `zb_storage` as `fat`, while newer ESP-IDF Zigbee guidance uses `nvs`.
61+
62+
## Flashing
63+
64+
The app creates the CSV partition table. It does not flash the board.
65+
66+
For ESP-IDF projects, configure your project to use the generated custom partition CSV and let the build system generate the binary partition table.
67+
68+
For manual flashing, convert the CSV to a binary partition table first:
69+
70+
```sh
71+
python gen_esp32part.py partitions.csv partition-table.bin
72+
```
73+
74+
The target chip selector shows the expected `esptool` command shape for the selected ESP32-family chip. Make sure the bootloader, partition table, and app image offsets match your project configuration.
75+
1276
## Troubleshooting
1377

1478
> Do not forget to set the flash size correctly in the board options in the Arduino IDE or Arduino Workshop Extension for Visual Studio Code.
1579
16-
> If you use Wi-Fi, BLE, or Preferences API an NVS partition is mandatory
80+
> If you use Wi-Fi, BLE, or Preferences API an NVS partition is mandatory.
1781
18-
If for some reason the flash size is not available in the board options you may need to adjust the maximum upload size in your boards definition.
19-
The IDE has no way to read the custom partition, see this [issue](https://github.com/espressif/arduino-esp32/issues/9831).
82+
If the flash size is not available in the board options, you may need to adjust the maximum upload size in your board definition. The IDE has no way to read the custom partition, see this [issue](https://github.com/espressif/arduino-esp32/issues/9831).
2083

21-
By default many of the custom partitions in boards definition have a 16MB max upload size, so if your board has less than 16MB flash memory, for example 4MB is typical, the compiler will report a wrong space occupied by your sketch.
84+
By default many custom partitions in board definitions have a 16 MB max upload size. If your board has less than 16 MB flash memory, for example 4 MB, the compiler can report the wrong space occupied by your sketch.
2285

23-
To fix this, you have to edit the Espressif boards.txt file, which is normally located in <br>`[your drive]\[your name]\AppData\Local\Arduino15\packages\esp32\hardware\esp32\[esp32 core version]`
86+
To fix this, edit the Espressif `boards.txt` file, which is normally located in:
2487

25-
This is a very large file and you need to search for your specific board and change the line (here for the ESP32S3 Dev Module) :<br>`esp32s3.menu.PartitionScheme.custom.upload.maximum_size=16777216`<br>
26-
to<br>`esp32s3.menu.PartitionScheme.custom.upload.maximum_size=4194304`<br>
27-
for a microcontroller with 4MB flash memory.
88+
```text
89+
[your drive]\[your name]\AppData\Local\Arduino15\packages\esp32\hardware\esp32\[esp32 core version]
90+
```
2891

29-
> When boards are updated by the IDE or you uninstall and reinstall it, you will have to redo your changes.
92+
Search for your specific board and change the line, for example for the ESP32S3 Dev Module:
3093

31-
### Partition table offset / large bootloaders
94+
```text
95+
esp32s3.menu.PartitionScheme.custom.upload.maximum_size=16777216
96+
```
3297

33-
Use the “Partition Table Offset” control in the sidebar (0x8000 by default; 0x18000 for larger bootloaders). The app will realign partitions automatically—leave offsets blank in CSV files to have them adapt. Remember to build both bootloader and app with the same `PARTITION_TABLE_OFFSET` in `sdkconfig`, and keep the value a multiple of 0x1000.
98+
to:
99+
100+
```text
101+
esp32s3.menu.PartitionScheme.custom.upload.maximum_size=4194304
102+
```
103+
104+
for a microcontroller with 4 MB flash memory.
105+
106+
> When boards are updated by the IDE, or you uninstall and reinstall it, you will have to redo your changes.
107+
108+
### Partition Table Offset / Large Bootloaders
109+
110+
Use the `Partition Table Offset` control in the sidebar (0x8000 by default; 0x18000 for larger bootloaders). The app will realign partitions automatically when offsets are blank. Remember to build both bootloader and app with the same `PARTITION_TABLE_OFFSET` in `sdkconfig`, and keep the value a multiple of 0x1000.
34111

35112
## Contributing
36113

37114
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, tests, and release notes expectations.
115+
116+
## License
117+
118+
This project is licensed under the terms in [LICENSE](LICENSE).

0 commit comments

Comments
 (0)