ESP32 Filesystem Guide

Overview

This guide explains how to create filesystem images, flash them, and use them in ESP32 projects.

Loction

Location of mkspiffs:

C:\Users\<user_name>\AppData\Local\Arduino15\packages\esp32\tools\mkspiffs\0.2.3\mkspiffs.exe

Location of mklittlefs:

C:\Users\<user_name>\AppData\Local\Arduino15\packages\esp32\tools\mklittlefs\3.0.0-gnu12-dc7f933\mklittlefs.exe

Project Structure

your_project/
 ├── main.ino
 └── data/
     ├── index.html
     ├── config.json

Step 1: Partition Table

spiffs, data, spiffs, <Offset>, <Size>,

spiffs, data, spiffs, 0x290000, 0x170000,

Offset: 0x290000
Size: 0x170000

Step 2: Create Filesystem

SPIFFS

mkspiffs -c <data_folder_name> -p 256 -b 4096 -s <size_given_in_parition_table> spiffs.bin

mkspiffs -c data -p 256 -b 4096 -s 0x170000 spiffs.bin

LittleFS

mklittlefs -c <data_folder_name> -p 256 -b 4096 -s <size_given_in_parition_table> littlefs.bin

mklittlefs -c data -p 256 -b 4096 -s 0x170000 littlefs.bin

Step 3: Flash

esptool.py --chip esp32 --port COM5 --baud 921600 write_flash 0x290000 spiffs.bin

🚀 ESP-IDF (Automatic Method)

ESP-IDF can automatically generate and flash the SPIFFS image without manual tools.

Add to CMakeLists.txt

spiffs_create_partition_image(spiffs data FLASH_IN_PROJECT)

Build & Flash

idf.py build
idf.py flash

This will:

• Create SPIFFS image from data/
• Use correct partition size automatically
• Flash to correct offset

Enable SPIFFS

idf.py menuconfig

Go to: Component config → SPIFFS → Enable SPIFFS

Add Dependency

REQUIRES spiffs

Example Code (ESP-IDF SPIFFS)

#include <stdio.h>
#include "esp_log.h"
#include "esp_spiffs.h"

static const char *TAG = "SPIFFS";

void app_main(void)
{
    esp_vfs_spiffs_conf_t conf = {
        .base_path = "/spiffs",
        .partition_label = NULL,
        .max_files = 5,
        .format_if_mount_failed = true
    };

    if (esp_vfs_spiffs_register(&conf) != ESP_OK) {
        ESP_LOGE(TAG, "Mount failed");
        return;
    }

    FILE *f = fopen("/spiffs/config.json", "r");
    if (!f) {
        ESP_LOGE(TAG, "File open failed");
        return;
    }

    char line[128];
    while (fgets(line, sizeof(line), f)) {
        printf("%s", line);
    }

    fclose(f);
}

Example Code (Arduino SPIFFS)

#include <SPIFFS.h>
void setup() {
  Serial.begin(115200); 
  if (!SPIFFS.begin(true))
  {
    Serial.println("SPIFFS Mount Failed"); 
    return; 
  } 
  File file = SPIFFS.open("/config.json", "r");
  if (file)
  {
    Serial.println(file.readString());
    file.close();
  }
}
void loop() {}

Example Code (Arduino LittleFS)

#include <LittleFS.h>

void setup()
{
   Serial.begin(115200);
   if (!LittleFS.begin(true))
   {
     Serial.println("LittleFS Mount Failed");
     return;
    }
    File file = LittleFS.open("/config.json", "r");
    if (file)
    {
       Serial.println(file.readString());
       file.close();
    }
}
void loop() {}

Example Code (Arduino FFat)

#include <FFat.h>

void setup() {
  Serial.begin(115200);

  if (!FFat.begin(true)) {
    Serial.println("FFat Mount Failed");
    return;
  }

  File file = FFat.open("/test.txt", FILE_WRITE);
  file.println("Hello from FATFS!");
  file.close();

  file = FFat.open("/test.txt");
  while (file.available()) {
    Serial.write(file.read());
  }
  file.close();
}

void loop() {}

Filesystem Comparison

Notes

• Always match partition size
• Wrong size = mount failure
• LittleFS is recommended
• ESP-IDF path uses /spiffs/ prefix