SPIFFS Filesystem

Overview

SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear leveling, file system consistency checks and more.

Notes

  • Presently, spiffs does not support directories. It produces a flat structure. If SPIFFS is mounted under /spiffs creating a file with path /spiffs/tmp/myfile.txt will create a file called /tmp/myfile.txt in SPIFFS, instead of myfile.txt under directory /spiffs/tmp.
  • It is not a realtime stack. One write operation might last much longer than another.
  • Presently, it does not detect or handle bad blocks.

Tools

Host-Side tools for creating SPIFS partition images exist and one such tool is mkspiffs. You can use it to create image from a given folder and then flash that image with esptool.py

To do that you need to obtain some parameters:

  • Block Size: 4096 (standard for SPI Flash)
  • Page Size: 256 (standard for SPI Flash)
  • Image Size: Size of the partition in bytes (can be obtained from partition table)
  • Partition Offset: Starting address of the partition (can be obtained from partition table)

To pack a folder into 1 Megabyte image:

mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin

To flash the image to ESP32 at offset 0x110000:

python esptool.py --chip esp32 --port [port] --baud [baud] write_flash -z 0x110000 spiffs.bin

Application Example

An example for using SPIFFS is provided in storage/spiffs directory. This example initializes and mounts SPIFFS partition, and writes and reads data from it using POSIX and C library APIs. See README.md file in the example directory for more information.

High level API Reference

Functions

esp_err_t esp_vfs_spiffs_register(const esp_vfs_spiffs_conf_t *conf)

Register and mount SPIFFS to VFS with given path prefix.

Return
  • ESP_OK if success
  • ESP_ERR_NO_MEM if objects could not be allocated
  • ESP_ERR_INVALID_STATE if already mounted or partition is encrypted
  • ESP_ERR_NOT_FOUND if partition for SPIFFS was not found
  • ESP_FAIL if mount or format fails
Parameters

esp_err_t esp_vfs_spiffs_unregister(const char *partition_label)

Unregister and unmount SPIFFS from VFS

Return
  • ESP_OK if successful
  • ESP_ERR_INVALID_STATE already unregistered
Parameters
  • partition_label: Optional, label of the partition to unregister. If not specified, first partition with subtype=spiffs is used.

bool esp_spiffs_mounted(const char *partition_label)

Check if SPIFFS is mounted

Return
  • true if mounted
  • false if not mounted
Parameters
  • partition_label: Optional, label of the partition to check. If not specified, first partition with subtype=spiffs is used.

esp_err_t esp_spiffs_format(const char *partition_label)

Format the SPIFFS partition

Return
  • ESP_OK if successful
  • ESP_FAIL on error
Parameters
  • partition_label: Optional, label of the partition to format. If not specified, first partition with subtype=spiffs is used.

esp_err_t esp_spiffs_info(const char *partition_label, size_t *total_bytes, size_t *used_bytes)

Get information for SPIFFS

Return
  • ESP_OK if success
  • ESP_ERR_INVALID_STATE if not mounted
Parameters
  • partition_label: Optional, label of the partition to get info for. If not specified, first partition with subtype=spiffs is used.
  • total_bytes: Size of the file system
  • used_bytes: Current used bytes in the file system

Structures

struct esp_vfs_spiffs_conf_t

Configuration structure for esp_vfs_spiffs_register.

Public Members

const char *base_path

File path prefix associated with the filesystem.

const char *partition_label

Optional, label of SPIFFS partition to use. If set to NULL, first partition with subtype=spiffs will be used.

size_t max_files

Maximum files that could be open at the same time.

bool format_if_mount_failed

If true, it will format the file system if it fails to mount.