platform-espressif32/examples/arduino-spiffs/README.md

ESP32 SPIFFS Filesystem Test Project

This project tests the SPIFFS filesystem implementation on ESP32.

Overview

This project demonstrates:

• Building SPIFFS filesystem images
• Uploading SPIFFS images to ESP32
• Mounting and reading SPIFFS filesystem on ESP32
• Downloading and extracting SPIFFS images from ESP32

Requirements

• PlatformIO
• ESP32 development board
• USB cable

Project Structure

arduino-spiffs/
├── data/                    # Files to be included in SPIFFS image
│   ├── test.txt
│   ├── README.md
│   └── ...
├── src/
│   └── spiffs_test.ino     # Main Arduino sketch
├── partitions.csv          # Partition table with SPIFFS partition
├── platformio.ini          # PlatformIO configuration
└── unpacked_fs/            # Downloaded files (created by download_spiffs)

Usage

1. Build Firmware

pio run

2. Build SPIFFS Filesystem Image

Place your files in the data/ directory, then:

pio run -t buildfs

This creates a SPIFFS filesystem image at: .pio/build/esp32dev/spiffs.bin

3. Upload Firmware and Filesystem

# Upload firmware
pio run -t upload

# Upload filesystem
pio run -t uploadfs

4. Monitor Serial Output

pio run -t monitor

Expected output:

SPIFFS mounted successfully
Total space:    1507328
Used space:     12345
Listing directory: /
  FILE: test.txt    SIZE: 12
  FILE: README.md   SIZE: 456
Test complete

5. Download Filesystem from Device

To download and extract the filesystem from the device:

pio run -t download_spiffs

Files will be extracted to unpacked_fs/ directory.

Partition Table

The partitions.csv defines the flash layout:

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x5000,
otadata,  data, ota,     0xe000,  0x2000,
app0,     app,  ota_0,   0x10000, 0x140000,
app1,     app,  ota_1,   0x150000,0x140000,
spiffs,   data, spiffs,  0x290000,0x170000,

The spiffs partition:

• Type: data
• SubType: spiffs (0x82)
• Offset: 0x290000 (2,686,976 bytes)
• Size: 0x170000 (1,507,328 bytes = ~1.44 MB)

SPIFFS Configuration

Default SPIFFS configuration (can be customized in platformio.ini):

board_build.spiffs.page_size = 256
board_build.spiffs.block_size = 4096
board_build.spiffs.obj_name_len = 32
board_build.spiffs.meta_len = 4
board_build.spiffs.use_magic = true
board_build.spiffs.use_magic_len = true
board_build.spiffs.aligned_obj_ix_tables = false

These match ESP-IDF defaults:

• CONFIG_SPIFFS_PAGE_SIZE = 256
• CONFIG_SPIFFS_OBJ_NAME_LEN = 32
• CONFIG_SPIFFS_META_LENGTH = 4
• CONFIG_SPIFFS_USE_MAGIC = true
• CONFIG_SPIFFS_USE_MAGIC_LENGTH = true

Troubleshooting

"SPIFFS Mount Failed"

Possible causes:

1. Filesystem not uploaded
2. Wrong partition table
3. Corrupted filesystem

Solutions:

# Rebuild and upload filesystem
pio run -t buildfs
pio run -t uploadfs

# Or erase flash and start fresh
pio run -t erase
pio run -t upload
pio run -t uploadfs

"No SPIFFS filesystem partition found"

Cause: Partition table doesn't have a SPIFFS partition

Solution: Check partitions.csv has a partition with SubType: spiffs

Files not appearing

Cause: Files not in data/ directory when building

Solution:

1. Add files to data/ directory
2. Rebuild filesystem: pio run -t buildfs
3. Upload: pio run -t uploadfs

Code Example

#include "FS.h"
#include "SPIFFS.h"

void setup() {
    Serial.begin(115200);
    
    // Mount SPIFFS filesystem
    if (!SPIFFS.begin(false)) {
        Serial.println("SPIFFS Mount Failed");
        return;
    }
    
    // List files
    File root = SPIFFS.open("/");
    File file = root.openNextFile();
    while (file) {
        Serial.printf("File: %s, Size: %d\n", 
                     file.name(), file.size());
        file = root.openNextFile();
    }
    
    // Read file
    File f = SPIFFS.open("/test.txt", "r");
    if (f) {
        String content = f.readString();
        Serial.println(content);
        f.close();
    }
    
    // Write file
    f = SPIFFS.open("/output.txt", "w");
    if (f) {
        f.println("Hello from ESP32!");
        f.close();
    }
}

void loop() {
    // Your code here
}

Platform Configuration

This project uses a custom platform with SPIFFS filesystem support:

[env:esp32dev]
platform = espressif32
framework = arduino
board = esp32dev
board_build.filesystem = spiffs
board_build.partitions = partitions.csv

Comparison with Other Filesystems

Feature	SPIFFS	LittleFS	FatFS
Wear Leveling	Built-in	Built-in	Requires WL layer
Max File Size	~1MB	Limited by partition	4GB
Directories	No	Yes	Yes
Performance	Medium	Fast	Fast
RAM Usage	Low	Low	Medium
Reliability	Good	Excellent	Good

References

• ESP32 SPIFFS Library
• ESP-IDF SPIFFS
• SPIFFS Specification

Notes

• SPIFFS does not support directories (flat filesystem)
• File names are limited to 32 characters by default
• SPIFFS has built-in wear leveling
• Maximum file size depends on available RAM
• SPIFFS is being deprecated in favor of LittleFS in newer ESP-IDF versions