From 8eade5a911e013871c77accbdb3541b2a17c40b9 Mon Sep 17 00:00:00 2001 From: "sonika.rathi" Date: Tue, 18 Aug 2026 10:41:03 +0200 Subject: [PATCH] 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. --- examples/storage/README.md | 44 ++++++------ .../storage/custom_flash_driver/README.md | 4 ++ examples/storage/emmc/README.md | 3 + examples/storage/fatfs/bdl_wl/README.md | 5 ++ examples/storage/fatfs/ext_flash/README.md | 5 ++ examples/storage/fatfs/fatfsgen/README.md | 5 ++ .../storage/fatfs/fs_operations/README.md | 5 ++ .../storage/fatfs/getting_started/README.md | 40 +++++++---- examples/storage/littlefs/README.md | 5 ++ examples/storage/nvs/nvs_bootloader/README.md | 5 ++ examples/storage/nvs/nvs_console/README.md | 5 ++ examples/storage/nvs/nvs_iteration/README.md | 7 +- examples/storage/nvs/nvs_rw_blob/README.md | 5 ++ examples/storage/nvs/nvs_rw_value/README.md | 5 ++ .../storage/nvs/nvs_rw_value_cxx/README.md | 4 ++ examples/storage/nvs/nvs_statistics/README.md | 5 ++ examples/storage/nvs/nvsgen/README.md | 5 ++ .../partition_api/partition_find/README.md | 4 ++ .../partition_api/partition_mmap/README.md | 4 ++ .../partition_api/partition_ops/README.md | 4 ++ examples/storage/parttool/README.md | 4 ++ examples/storage/perf_benchmark/README.md | 5 ++ examples/storage/sd_card/sdmmc/README.md | 5 ++ examples/storage/sd_card/sdspi/README.md | 5 ++ examples/storage/semihost_vfs/README.md | 4 ++ examples/storage/spiffs/README.md | 6 ++ examples/storage/spiffsgen/README.md | 4 ++ examples/storage/wear_levelling/README.md | 70 ++++++++++++++----- 28 files changed, 221 insertions(+), 51 deletions(-) diff --git a/examples/storage/README.md b/examples/storage/README.md index 6a29811042f..17c3dcc1f0d 100644 --- a/examples/storage/README.md +++ b/examples/storage/README.md @@ -7,26 +7,30 @@ This directory contains a range of examples ESP-IDF projects. These are intended The examples are grouped into sub-directories by category. Each category directory contains one or more example projects: -* `fatfs_basic` minimal example of FatFS usage on SPI FLASH -* `fatfs_advanced` example demonstrates how to use advanced features for working with FatFS such as automatic partition generation -* `custom_flash_driver` example demonstrates how to implement your own flash chip driver by overriding the default driver. -* `emmc` example demonstrates how to use an eMMC chip with an ESP device. -* `ext_flash_fatfs` example demonstrates how to use FATFS partition with external SPI FLASH chip. -* `fatfsgen` example demonstrates how to use FATFS partition generator -* `nvs_bootloader` example demonstrates how to read data from NVS in the bootloader code. -* `nvs_rw_blob` example demonstrates how to read and write a single integer value and a blob (binary large object) using NVS to preserve them between ESP module restarts. -* `nvs_rw_value` example demonstrates how to read and write a single integer value using NVS. -* `nvs_rw_value_cxx` example demonstrates how to read and write a single integer value using NVS (it uses the C++ NVS handle API). -* `nvs_console` example demonstrates how to use NVS through an interactive console interface. -* `nvs_statistics` example demonstrates how to obtain and interpret stats about used/available NVS storage entries in given NVS partition. -* `nvs_iteration` example demonstrates iterating over entries of specific (or any) data type in given namespace, and the info to be obtained about the entries while doing so. -* `partition_api` examples demonstrate how to use different partition APIs. -* `parttool` example demonstrates common operations the partitions tool allows the user to perform. -* `sd_card` examples demonstrate how to use an SD card with an ESP device. -* `semihost_vfs` example demonstrates how to use semihosting VFS driver with ESP device. -* `spiffs` example demonstrates how to use SPIFFS with ESP device. -* `spiffsgen` example demonstrates how to use the SPIFFS image generation tool spiffsgen.py to automatically create a SPIFFS. -* `wear_levelling` example demonstrates how to use wear levelling library and FATFS library to store files in a partition inside SPI flash. +* `fatfs/getting_started` — minimal FATFS on internal SPI flash (mount / write / read / unmount). Wear levelling is used via `esp_vfs_fat_spiflash_mount_rw_wl`. +* `fatfs/fs_operations` — broader FATFS file and directory operations. +* `fatfs/ext_flash` — FATFS on an external SPI flash chip. +* `fatfs/fatfsgen` — build-time FATFS image generation. +* `fatfs/bdl_wl` — FATFS with wear-levelling block device layer (BDL). +* `wear_levelling` — wear levelling + FATFS lifecycle (mount, write/read, format, verify, rewrite). Not a duplicate of `fatfs/getting_started`; use that for the minimal first demo. +* `littlefs` — LittleFS on flash (wear management is built into LittleFS; not the wear_levelling component). +* `custom_flash_driver` — implement a custom flash chip driver by overriding the default driver. +* `emmc` — use an eMMC chip with an ESP device. +* `nvs/nvs_bootloader` — read NVS data from bootloader code. +* `nvs/nvs_rw_blob` — read/write an integer and a blob in NVS across restarts. +* `nvs/nvs_rw_value` — read/write a single integer in NVS. +* `nvs/nvs_rw_value_cxx` — same as `nvs/nvs_rw_value` using the C++ NVS handle API. +* `nvs/nvs_console` — interactive NVS console. +* `nvs/nvs_statistics` — NVS used/available entry statistics. +* `nvs/nvs_iteration` — iterate NVS entries by type/namespace. +* `nvs/nvsgen` — NVS partition / image generation helpers. +* `partition_api` — partition API examples. +* `parttool` — common host-side partition tool operations. +* `sd_card` — SD card examples. +* `semihost_vfs` — semihosting VFS driver. +* `spiffs` — SPIFFS on flash. +* `spiffsgen` — build-time SPIFFS image generation with spiffsgen.py. +* `perf_benchmark` — storage performance benchmarking. # More diff --git a/examples/storage/custom_flash_driver/README.md b/examples/storage/custom_flash_driver/README.md index 1822aaab552..94582d5a5c7 100644 --- a/examples/storage/custom_flash_driver/README.md +++ b/examples/storage/custom_flash_driver/README.md @@ -9,6 +9,10 @@ This example shows how to override the default chip driver list provided by IDF. (See the README.md file in the upper level 'examples' directory for more information about examples.) +## When to use this example + +- You need to support a flash chip that is not covered by the default IDF chip driver list, by providing your own chip driver. + ## How to use example Follow detailed instructions provided specifically for this example. diff --git a/examples/storage/emmc/README.md b/examples/storage/emmc/README.md index 64d85be82f9..20b9771cd62 100644 --- a/examples/storage/emmc/README.md +++ b/examples/storage/emmc/README.md @@ -19,6 +19,9 @@ This example demonstrates how to use an eMMC chip with an ESP device. Example do This example supports eMMC chips. +## When to use this example + +- Your board has a soldered eMMC chip connected over the SDMMC host (ESP32-S3 / ESP32-P4) and you want FATFS on it. ## Hardware diff --git a/examples/storage/fatfs/bdl_wl/README.md b/examples/storage/fatfs/bdl_wl/README.md index 61fc05355b8..a51d3e97d06 100644 --- a/examples/storage/fatfs/bdl_wl/README.md +++ b/examples/storage/fatfs/bdl_wl/README.md @@ -26,6 +26,11 @@ The key advantage of BDL is that **the same `diskio_bdl` adapter works with any You can swap the bottom of the stack (e.g., use `sdmmc_get_blockdev()` for an SD card) without changing the FatFS integration code. +## When to use this example + +- You want the newer Block Device Layer (BDL) approach to mounting FATFS instead of the legacy `wl_handle_t` API. +- You plan to reuse the same FATFS integration across different backends (flash partition, SD card, etc.). + ## How to use example ### Build and flash diff --git a/examples/storage/fatfs/ext_flash/README.md b/examples/storage/fatfs/ext_flash/README.md index a006e5c6abc..8cebfc7ea25 100644 --- a/examples/storage/fatfs/ext_flash/README.md +++ b/examples/storage/fatfs/ext_flash/README.md @@ -17,6 +17,11 @@ The flow of the example is as follows: 4. Do some read and write operations using C standard library functions: create a file, write to it, open it for reading, print the contents to the console. +## When to use this example + +- You need to add FATFS storage on an *external* SPI flash chip (e.g. to extend a module with only 4 MB of internal flash). +- You want to see how to register an external flash chip as a partition (`esp_flash_t` / `esp_partition_t`). + ## How to use example ### Hardware required diff --git a/examples/storage/fatfs/fatfsgen/README.md b/examples/storage/fatfs/fatfsgen/README.md index 7e21d642adb..d9f74b1742d 100644 --- a/examples/storage/fatfs/fatfsgen/README.md +++ b/examples/storage/fatfs/fatfsgen/README.md @@ -67,3 +67,8 @@ I (342) example: Done The logic of the example is contained in a [single source file](./main/fatfsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. + +## When to use this example + +- You want to ship pre-created files on a FATFS partition, generated at build time from a host folder. +- You need a read-only or read-write FATFS image flashed together with the app. diff --git a/examples/storage/fatfs/fs_operations/README.md b/examples/storage/fatfs/fs_operations/README.md index ff43caada48..e4927c90ff8 100644 --- a/examples/storage/fatfs/fs_operations/README.md +++ b/examples/storage/fatfs/fs_operations/README.md @@ -8,6 +8,11 @@ This example demonstrates some of the POSIX functions available for working with the FATFS filesystem. Including basic read and write operations, as well as creating moving, and deleting files and directories. +## When to use this example + +- You already know how to mount FATFS and want to see richer file/directory operations (`fstat`, append, list, `mkdir`, rename/move, delete). +- You need a reference for POSIX calls against a FATFS volume. + ## Overview 1. Partition labeled `storage` is mounted (and formatted if necessary) as FATFS filesystem to `/spiflash` mountpoint. diff --git a/examples/storage/fatfs/getting_started/README.md b/examples/storage/fatfs/getting_started/README.md index ec540bd7657..889d399eb2a 100644 --- a/examples/storage/fatfs/getting_started/README.md +++ b/examples/storage/fatfs/getting_started/README.md @@ -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. diff --git a/examples/storage/littlefs/README.md b/examples/storage/littlefs/README.md index 8f32b9a1765..a275444ca77 100644 --- a/examples/storage/littlefs/README.md +++ b/examples/storage/littlefs/README.md @@ -35,6 +35,11 @@ This example demonstrates how to use LittleFS with ESP32. Example does the follo LittleFS partition size is set in partitions_demo_esp_littlefs.csv file. See [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/partition-tables.html) documentation for more information. +## When to use this example + +- You want a power-fail-resilient flash filesystem with wear levelling built in (no separate wear_levelling component needed). +- You are choosing a modern general-purpose filesystem for internal flash and do not mind slower access speeds. + ## How to use example ### Hardware required diff --git a/examples/storage/nvs/nvs_bootloader/README.md b/examples/storage/nvs/nvs_bootloader/README.md index 15914a84026..8d701d16654 100644 --- a/examples/storage/nvs/nvs_bootloader/README.md +++ b/examples/storage/nvs/nvs_bootloader/README.md @@ -7,6 +7,11 @@ The purpose of this example is to show how to use the simplified, read-only API A very practical application of being able to access the NVS in the bootloader build would be faster device restoration, where-in the application stores the device's current state/configurations and post a reset it would read the NVS to restore the device's last state, without waiting for application to boot-up. +## When to use this example + +- You need to read NVS data from the bootloader (before the app starts), e.g. for fast state restoration. +- You want to use the simplified, read-only NVS bootloader API. + ## Usage of this example: Simply compile it: diff --git a/examples/storage/nvs/nvs_console/README.md b/examples/storage/nvs/nvs_console/README.md index 7e35801987e..ee6edff6723 100644 --- a/examples/storage/nvs/nvs_console/README.md +++ b/examples/storage/nvs/nvs_console/README.md @@ -5,6 +5,11 @@ This example demonstrates how to use Non-Volatile Storage (NVS) through an interactive console interface. It provides a set of commands to read, write, and manage data in NVS. +## When to use this example + +- You want to inspect and modify NVS interactively at runtime (set/get/erase/list keys across namespaces). +- You are debugging stored values or exploring NVS behavior without writing custom firmware. + ## Hardware Required This example can run on any ESP32 family development board. diff --git a/examples/storage/nvs/nvs_iteration/README.md b/examples/storage/nvs/nvs_iteration/README.md index 7fef42be231..b5ee2072ac0 100644 --- a/examples/storage/nvs/nvs_iteration/README.md +++ b/examples/storage/nvs/nvs_iteration/README.md @@ -5,6 +5,11 @@ This example showcases how to iterate and obtain info about NVS entries of a specific (or any) NVS datatype. +## When to use this example + +- You need to enumerate NVS entries in code, filtered by type and/or namespace (`nvs_entry_find` / `nvs_entry_info`). +- You are building tooling that discovers keys rather than reading known keys. + Default "nvs" partition is first erased to allow for clean example run, followed by writing 2 sets of key value pairs of different types to NVS storage. After that, iteration is performed over the individual data types, as well as the generic `NVS_TYPE_ANY`, and relevant entry info gained from iteration is verbosely logged. @@ -66,4 +71,4 @@ I (825) nvs_iteration_example: Iterated over 14 entries. I (825) nvs_iteration_example: Returning from app_main(). I (835) main_task: Returned from app_main() ... -``` \ No newline at end of file +``` diff --git a/examples/storage/nvs/nvs_rw_blob/README.md b/examples/storage/nvs/nvs_rw_blob/README.md index 433ef0ff106..1b35bbae2a1 100644 --- a/examples/storage/nvs/nvs_rw_blob/README.md +++ b/examples/storage/nvs/nvs_rw_blob/README.md @@ -16,6 +16,11 @@ Detailed functional description of NVS and API is provided in [documentation](ht If not done already, consider checking simpler example *storage/nvs/nvs_rw_value*, that has been used as a starting point for preparing this one. +## When to use this example + +- You need to store variable-length binary data (a blob), such as a table or struct, in NVS. +- You want to see blob read-modify-write across reboots, including a button-triggered update. + ## How to use example ### Hardware required diff --git a/examples/storage/nvs/nvs_rw_value/README.md b/examples/storage/nvs/nvs_rw_value/README.md index a01bf3db903..b41140c6be0 100644 --- a/examples/storage/nvs/nvs_rw_value/README.md +++ b/examples/storage/nvs/nvs_rw_value/README.md @@ -15,6 +15,11 @@ Detailed functional description of NVS and API is provided in [documentation](ht Check another example *storage/nvs/nvs_rw_blob*, which shows how to read and write variable length binary data (blob). +## When to use this example + +- You are new to NVS and want the simplest read/write of a single integer that survives reboots. +- You need a starting template for storing small configuration/counter values. + ## How to use example ### Hardware required diff --git a/examples/storage/nvs/nvs_rw_value_cxx/README.md b/examples/storage/nvs/nvs_rw_value_cxx/README.md index abd16b35de0..4faba8378e4 100644 --- a/examples/storage/nvs/nvs_rw_value_cxx/README.md +++ b/examples/storage/nvs/nvs_rw_value_cxx/README.md @@ -9,6 +9,10 @@ This example demonstrates how to read and write a single integer value using NVS It is essentially the same as the nvs_rw_value example. The only difference is that it uses the C++ NVS handle API. Please see [nvs_rw_value README](../nvs_rw_value/README.md) for more details about this example. +## When to use this example + +- You are writing C++ and want the RAII-style C++ NVS handle API instead of the C API. + ## How to use example ### Hardware required diff --git a/examples/storage/nvs/nvs_statistics/README.md b/examples/storage/nvs/nvs_statistics/README.md index 05a599d4ea5..d156386dff4 100644 --- a/examples/storage/nvs/nvs_statistics/README.md +++ b/examples/storage/nvs/nvs_statistics/README.md @@ -5,6 +5,11 @@ This example demonstrates the usage of obtaining and interpreting statistics about the a given NVS partition, namely free/used/available/total entries and namespace count. +## When to use this example + +- You want to measure NVS partition usage (free/used/available/total entries, namespace count) via `nvs_get_stats()`. +- You need to understand blob storage overhead and fragmentation before sizing an NVS partition. + The default "nvs" partition is first erased, then a mock string data configuration is written to 2 different namespaces, followed by checking the changed statistics and mainly the number of newly used NVS entries. Statistics obtained via [nvs_get_stats()](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/storage/nvs_flash.html#_CPPv413nvs_get_statsPKcP11nvs_stats_t) are the following: diff --git a/examples/storage/nvs/nvsgen/README.md b/examples/storage/nvs/nvsgen/README.md index 6981293acad..acfdaba22ac 100644 --- a/examples/storage/nvs/nvsgen/README.md +++ b/examples/storage/nvs/nvsgen/README.md @@ -52,3 +52,8 @@ I (387) example: Reading values from NVS done - all OK ``` The logic of the example is contained in a [single source file](./main/nvsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. + +## When to use this example + +- You want to pre-populate an NVS partition at build time from a CSV file and flash it with the app. +- You need factory/default configuration baked into NVS without writing it from firmware. diff --git a/examples/storage/partition_api/partition_find/README.md b/examples/storage/partition_api/partition_find/README.md index 9d8b3693e0b..7b8dd34a50a 100644 --- a/examples/storage/partition_api/partition_find/README.md +++ b/examples/storage/partition_api/partition_find/README.md @@ -8,6 +8,10 @@ These functions return the matching partitions given a set of constraints. By co properties that returned results should match - notably partition type, subtype and label/name. In the case of `esp_partition_find_first`, the first matching instance is returned; for `esp_partition_find`, an iterator is returned iterating over matching instances. +## When to use this example + +- You need to locate partitions by type/subtype/label at runtime (`esp_partition_find` / `esp_partition_find_first`). + # Example Flow The example uses a [custom partition table](./partitions_example.csv). The first part uses `esp_partition_find_first` to search for partition instances diff --git a/examples/storage/partition_api/partition_mmap/README.md b/examples/storage/partition_api/partition_mmap/README.md index 53dc71ed635..36065514a45 100644 --- a/examples/storage/partition_api/partition_mmap/README.md +++ b/examples/storage/partition_api/partition_mmap/README.md @@ -5,6 +5,10 @@ This example demonstrates how to use `esp_partition_mmap` to configure MMU and map a partition into memory address space for read operations. +## When to use this example + +- You want to read a flash partition as if it were memory (memory-mapped), e.g. for zero-copy access to large read-only data. + # Example Flow The example uses a [custom partition table](./partitions_example.csv), with a data partition `storage` used for demonstration. Before mapping this partition to memory, diff --git a/examples/storage/partition_api/partition_ops/README.md b/examples/storage/partition_api/partition_ops/README.md index 3a89aa48dc4..77f4be0c373 100644 --- a/examples/storage/partition_api/partition_ops/README.md +++ b/examples/storage/partition_api/partition_ops/README.md @@ -5,6 +5,10 @@ This example demonstrates how to perform partition read, write and erase operations using API functions `esp_partition_read`, `esp_partition_write` and `esp_partition_erase`. +## When to use this example + +- You want raw read/write/erase access to a flash partition without a filesystem on top. + # Example Flow The example uses a [custom partition table](./partitions_example.csv), with a data partition `storage` used as the demo partition. For the most part the example code is well-commented so users should be able to follow along the code easily. Nevertheless, this section provides an overview of the code flow. diff --git a/examples/storage/parttool/README.md b/examples/storage/parttool/README.md index c960f298465..3ab7e03e7a1 100644 --- a/examples/storage/parttool/README.md +++ b/examples/storage/parttool/README.md @@ -17,6 +17,10 @@ The example performs the operations mentioned above in a straightforward manner: by reading it back. For partitions, contents are compared to the originally written file. For the partition table, contents are verified against the partition table CSV file. An erased partition's contents is compared to a generated blank file. +## When to use this example + +- You want to manipulate partitions from the *host* PC (read/write/erase, dump the partition table) using `parttool.py`. + ## How to use example ### Build and Flash diff --git a/examples/storage/perf_benchmark/README.md b/examples/storage/perf_benchmark/README.md index d397dd3fdb4..d756d5b1800 100644 --- a/examples/storage/perf_benchmark/README.md +++ b/examples/storage/perf_benchmark/README.md @@ -12,6 +12,11 @@ Only ESP32 and ESP32-S3 targets can use SDMMC mode when connecting to a SD card. This example provides comparison between different types of storage in terms of speed under various configurable (from menuconfig) conditions +## When to use this example + +- You want to benchmark and compare read/write speed across storage media and filesystems (SPI flash / SD card; raw, FATFS, SPIFFS, LittleFS). +- You are deciding which filesystem or medium best fits your performance needs. + Currently these mediums and file-systems are supported: - SPI Flash - Raw access diff --git a/examples/storage/sd_card/sdmmc/README.md b/examples/storage/sd_card/sdmmc/README.md index cbc8961e5ed..33e93a8d2df 100644 --- a/examples/storage/sd_card/sdmmc/README.md +++ b/examples/storage/sd_card/sdmmc/README.md @@ -18,6 +18,11 @@ This example demonstrates how to use an SD card with an ESP device. Example does 1. Create a file using `fopen` and write to it using `fprintf`. 1. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function. 1. Open renamed file for reading, read back the line, and print it to the terminal. + +## When to use this example + +- You have a removable SD/MMC card wired to the SDMMC host and want FATFS access with best throughput (1/4/8-line). + 1. __OPTIONAL:__ Format the SD card, check if the file doesn't exist anymore. This example supports SD (SDSC, SDHC, SDXC) cards and eMMC chips. diff --git a/examples/storage/sd_card/sdspi/README.md b/examples/storage/sd_card/sdspi/README.md index 04b8248df11..f6b44fa7c8a 100644 --- a/examples/storage/sd_card/sdspi/README.md +++ b/examples/storage/sd_card/sdspi/README.md @@ -18,6 +18,11 @@ This example demonstrates how to use an SD card with an ESP device over an SPI i 1. Create a file using `fopen` and write to it using `fprintf`. 1. Rename the file. Before renaming, check if destination file already exists using `stat` function, and remove it using `unlink` function. 1. Open renamed file for reading, read back the line, and print it to the terminal. + +## When to use this example + +- You want to access a removable SD card over the SPI bus, which works on any target and uses flexible GPIOs. + 1. __OPTIONAL:__ Format the SD card, check if the file doesn't exist anymore. This example support SD (SDSC, SDHC, SDXC) cards. diff --git a/examples/storage/semihost_vfs/README.md b/examples/storage/semihost_vfs/README.md index 5caf031a1c9..16986836fac 100644 --- a/examples/storage/semihost_vfs/README.md +++ b/examples/storage/semihost_vfs/README.md @@ -14,6 +14,10 @@ This example demonstrates how to use semihosting VFS driver with ESP32. Example 5. Opens text file on the host. 6. Reads the file and prints its content on stdout. +## When to use this example + +- You want the device to read/write files on the *host* PC through the debugger (semihosting), e.g. for logging or test data, without on-device storage. + ## How to use example ### Hardware and tools required diff --git a/examples/storage/spiffs/README.md b/examples/storage/spiffs/README.md index c71816081c9..c1059f96aac 100644 --- a/examples/storage/spiffs/README.md +++ b/examples/storage/spiffs/README.md @@ -3,6 +3,8 @@ # SPIFFS example +**Note:** SPIFFS is not recommended for new designs. Use FATFS or LittleFS instead. + (See the README.md file in the upper level 'examples' directory for more information about examples.) This example demonstrates how to use SPIFFS with ESP32. Example does the following steps: @@ -17,6 +19,10 @@ This example demonstrates how to use SPIFFS with ESP32. Example does the followi SPIFFS partition size is set in partitions_example.csv file. See [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/partition-tables.html) documentation for more information. +## When to use this example + +- You need to work with a legacy SPIFFS image. + ## How to use example ### Hardware required diff --git a/examples/storage/spiffsgen/README.md b/examples/storage/spiffsgen/README.md index 6033a1707c0..fdbed7ab9ed 100644 --- a/examples/storage/spiffsgen/README.md +++ b/examples/storage/spiffsgen/README.md @@ -54,3 +54,7 @@ I (330) example: SPIFFS unmounted ``` The logic of the example is contained in a [single source file](./main/spiffsgen_example_main.c), and it should be relatively simple to match points in its execution with the log outputs above. + +## When to use this example + +- You want to ship pre-created files on a SPIFFS partition, generated at build time from a host folder. diff --git a/examples/storage/wear_levelling/README.md b/examples/storage/wear_levelling/README.md index 7f99eda0345..54aef80b42f 100644 --- a/examples/storage/wear_levelling/README.md +++ b/examples/storage/wear_levelling/README.md @@ -1,21 +1,52 @@ | 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 | | ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- | -# Wear levelling example +# Wear levelling + FATFS example (See the README.md file in the upper level 'examples' directory for more information about examples.) -This example demonstrates how to use wear levelling library and FATFS library to store files in a partition inside SPI flash. Example does the following steps: +## Purpose -1. Use an "all-in-one" `esp_vfs_fat_spiflash_mount_rw_wl` function to: - - find a partition in SPI flash, - - initialize wear levelling library using this partition - - mount FAT filesystem using FATFS library (and format the filesystem, if the filesystem can not be mounted), - - register FAT filesystem in VFS, enabling C standard library and POSIX functions to be used. -2. Create a file using `fopen` and write to it using `fprintf`. -3. Open file for reading, read back the line, and print it to the terminal. +Demonstrate the wear levelling library together with FATFS on an internal SPI flash partition: mount, write/read files, format the FAT volume through the wear-levelling path, confirm files are gone, then write again and unmount. -Wear levelling partition size is set in partitions_example.csv file. See [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/partition-tables.html) documentation for more information. +## When to use this example + +- You need the wear levelling + FATFS lifecycle, especially the format step (`esp_vfs_fat_spiflash_format_rw_wl`). +- You want to see mount → write/read → format → verify → rewrite → unmount in one flow. + +Use a different example when you need: + +- the shortest first FATFS demo → [fatfs/getting_started](../fatfs/getting_started/) +- FATFS on an external SPI flash chip → [fatfs/ext_flash](../fatfs/ext_flash/) +- broader FATFS file operations → [fatfs/fs_operations](../fatfs/fs_operations/) + +### Wear levelling vs other storage + +- **FATFS on SPI flash (this example):** use the wear_levelling component via `esp_vfs_fat_spiflash_mount_rw_wl` so repeated writes do not wear out the same flash sectors. +- **LittleFS:** wear management is part of the filesystem design; see [littlefs](../littlefs/) (does not use this wear_levelling component). +- **NVS:** flash wear is handled inside NVS; see [nvs](../nvs/) for keys/values, not general files. + +## What this example demonstrates + +1. Mount with the all-in-one API `esp_vfs_fat_spiflash_mount_rw_wl`, which: + - finds the `storage` partition in SPI flash + - initializes the wear levelling library on that partition + - mounts FATFS (and formats if mount fails when `format_if_mount_failed` is set) + - registers the volume in VFS so POSIX / C library file APIs work +2. Write a file (`fopen` / `fprintf`) and read it back +3. Format the mounted volume with `esp_vfs_fat_spiflash_format_rw_wl` +4. Verify the previous file no longer exists (`stat`) +5. Write and read a new file after format +6. Unmount with `esp_vfs_fat_spiflash_unmount_rw_wl` + +Source: [main/wear_levelling_example_main.c](./main/wear_levelling_example_main.c) + +Partition size is set in [partitions_example.csv](./partitions_example.csv). See [Partition Tables](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/partition-tables.html). + +## Requirements + +- No special hardware; any common development board with enough internal flash for the partition table +- Partition label: `storage` ## How to use example @@ -31,15 +62,15 @@ Build the project and flash it to the board, then run monitor tool to view seria idf.py -p PORT flash monitor ``` -(Replace PORT with serial port name.) - -(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. +To wipe the wear-levelling / FAT contents and start clean, run `idf.py erase-flash`, then flash the example again. + ## Example output -Here is a typical example console output. +Typical console output (IDs and IDF version string vary): ``` I (280) example: Mounting FAT filesystem @@ -49,9 +80,14 @@ I (660) vfs_fat_spiflash: Mounting again I (660) example: Opening file I (910) example: File written I (910) example: Reading file -I (920) example: Read from file: 'written using ESP-IDF v3.1-dev-171-gf9ad17eee-dirty' -I (920) example: Unmounting FAT filesystem +I (920) example: Read from file: 'hello world, from ESP-IDF ' +I (920) example: file does not exist, format done +I (920) example: Opening file +I (950) example: File written +I (950) example: Reading file +I (960) example: Read from file: 'nihao shijie, from ESP-IDF ' +I (960) example: Unmounting FAT filesystem I (1000) example: Done ``` -To erase the contents of wear levelling partition, run `idf.py erase-flash` command. Then upload the example again as described above. +The `f_mount failed` / formatting lines appear on a fresh (unformatted) partition; later runs may skip that path if the filesystem already exists.