01 Overview

SPIFFS is the built-in flash filesystem in ESP-IDF, designed for small files and low-capacity scenarios. It formats a partition of internal flash and exposes it through the standard VFS interface (fopen/fwrite/readdir).

It solves the problem of managing static resources (web pages, icons, certificates, small logs) as files, instead of stuffing data into NVS or compiling it into firmware. SPIFFS allows runtime read/write and supports pre-seeding files at manufacturing time.

Typical uses: local web server pages and CSS/JS, TLS client certificates, JSON backups of device config, low-frequency sensor logs.

It is not a general-purpose hard disk: capacity is small (typically hundreds of KB to a few MB), write endurance is limited, and power loss can corrupt files. For high-rate logs, use an SD card or external storage.

Division of labor with NVS: NVS is for small key-value pairs (Wi-Fi config, calibration values), SPIFFS is for file-type data. Keep critical config in NVS to avoid device lockout due to file corruption.

This example demonstrates how to mount SPIFFS, read/write files, and pre-seed resources in a factory image.

02 Hardware

• Flash partition: SPIFFS uses a partition of internal flash; define it in the partition table (partitions.csv), e.g., `spiffs, data, spiffs, , 0x100000`. Partition size determines available space.
• No extra hardware: No external storage chip; all operations happen on the ESP32's internal flash.
• Flash endurance: Internal flash has limited erase cycles (~100k), SPIFFS has wear leveling, but frequent writes still shorten lifespan.
• Power-loss protection: Hardware cannot guarantee atomic writes during power loss; software measures are needed (e.g., write temp file then rename).
• Wiring: No external wiring; just ensure stable power to avoid drops during writes.
• Layout note: Partition table must be configured at build time; ensure spiffs partition does not overlap others.

03 Software flow

1. Configure partition table: Add a spiffs partition in `partitions.csv` with appropriate size (e.g., 1MB).

2. Initialize SPIFFS: Call `esp_vfs_spiffs_register` with partition label, max files, etc.

3. Check mount: Use `esp_spiffs_check` to verify filesystem consistency; format if necessary.

4. Read/write files: Use standard C functions `fopen`/`fwrite`/`fread` or POSIX APIs.

5. Pre-seed assets: Use `spiffs_create_partition_image` in CMake to pack files from `spiffs_image` directory into firmware; mounted on first boot.

6. Error handling: Check return values of mount and file operations; handle insufficient space, corruption, etc.

7. Power-loss safety: For important files, write to a temp file then `rename` to reduce corruption risk.

8. Log rotation: For log files, implement size limits and rotation to avoid filling the partition.

04 Core points

• Power-loss corruption: Power loss during write can corrupt the filesystem; do not store critical config only in SPIFFS, use NVS.
• Capacity limits: SPIFFS is not for large files or many small files; plan partition size based on actual assets.
• Wear leveling: Although SPIFFS has wear leveling, frequent writes still wear flash; avoid high-rate logging.
• Difference from NVS: Do not use SPIFFS for small key-value pairs; NVS is more efficient and reliable.
• Customizable: Partition size, pre-seeded assets, and filesystem parameters (e.g., logical block size) can be adjusted.
• Cross-chip caution: Different ESP32 models have different flash sizes; partition tables must be adapted, not copied directly.