docs(storage): clarify example READMEs and when to use each

Update storage example docs so FATFS getting_started and wear_levelling
are clearly distinct, refresh the storage index paths, and add
"When to use this example" sections across storage examples.
This commit is contained in:
sonika.rathi
2026-08-19 14:54:49 +02:00
parent 76a34b3f85
commit b38461a0a8
28 changed files with 221 additions and 51 deletions
@@ -1,32 +1,49 @@
| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
# FATFS minimal example
# FATFS getting started (minimal) example
(See the README.md file in the upper level 'examples' directory for more information about examples.)
This example demonstrates the minimal setup required to store persistent data on SPI Flash using the FAT filesystem.
Beware that the minimal required size of the flash is 4 MB.
## Purpose
Minimal FAT filesystem example for beginners: mount a FAT volume on internal SPI flash, write one file, read it back, then unmount.
Wear levelling is enabled by the mount API used here (`esp_vfs_fat_spiflash_mount_rw_wl`), which is required for safe read-write FAT on SPI flash.
## When to use this example
- You want the shortest path to store files with FATFS on internal SPI flash.
- You are learning the basic mount / write / read / unmount flow.
## What this example demonstrates
- Mount FAT on the `storage` partition with `esp_vfs_fat_spiflash_mount_rw_wl`
- Create and write a file with `fopen` / `fprintf`
- Read the file back with `fopen` / `fgets`
- Unmount with `esp_vfs_fat_spiflash_unmount_rw_wl`
Source: [main/fatfs_getting_started_main.c](./main/fatfs_getting_started_main.c)
## Requirements
- Internal SPI flash large enough for the example partition table (typically at least 4 MB modules)
- Partition label: `storage` (see [partitions_example.csv](./partitions_example.csv))
## How to use example
### Build and flash
To run the example, type the following command:
```CMake
# CMake
```
idf.py -p PORT flash monitor
```
(To exit the serial monitor, type ``Ctrl-]``.)
(Replace `PORT` with the serial port name. Exit the serial monitor with ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example output
Here is the example's console output:
```
...
I (321) example: Mounting FAT filesystem
@@ -39,6 +56,3 @@ I (741) example: Unmounting FAT filesystem
I (851) example: Done
...
```
The logic of the example is contained in a [single source file](./main/fatfs_getting_started_main.c),
and it should be relatively simple to match points in its execution with the log outputs above.