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

  • Currently, SPIFFS does not support directories. It produces a flat structure. If SPIFFS is mounted under /spiffs, then 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.
  • Currently, it does not detect or handle bad blocks.

Tools

spiffsgen.py

spiffsgen.py is a write-only Python SPIFFS implementation used to create filesystem images from the contents of a host folder. To use spiffsgen.py, simply invoke it from your favorite terminal:

python spiffsgen.py <image_size> <base_dir> <output_file>
  • image_size: size of the partition on which the created SPIFFS image will be flashed to
  • base_dir: directory to create the SPIFFS image of
  • output_file: SPIFFS image output file

Besides the three required arguments: image_size, base_dir and output_file, there are other arguments that control image generation. Documentation on these arguments exist in the tool’s help:

python spiffsgen.py --help

These optional arguments correspond to possible SPIFFS build configuration. User should make sure that the image is generated with the same arguments/configuration as SPIFFS was built with, else the user ends up with an invalid image. As a guide, the help output indicates the SPIFFS build configuration the argument corresponds to. In cases when these arguments are not specified, the default values shown in the help output are used.

Once the image has been created, it can be flashed using esptool.py or parttool.py.

Aside from invoking spiffsgen.py standalone, it is also possible to use it directly from the build system by calling spiffs_create_partition_image.

Make:

$(eval $(call spiffs_create_partition_image,<partition>,<base_dir>,[FLASH_IN_PROJECT]))

CMake:

spiffs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT])

This is more convenient as the build configuration is automatically passed to the tool, ensuring that the image generated is valid for that build. An example of this is while the image_size is required for the standalone invocation, only the partition name is required when using spiffs_create_partition_image – the image size is automatically obtained from the project’s partition table. It is important to note that due to the differences in structure between the two build systems, when using Make, spiffs_create_partition_image must be called from the project Makefile; for CMake, it should be called from one of the component CMakeLists.txt. For both build systems, the image will be created in the build directory with filename partition.bin.

Optionally, user can opt to have the image automatically flashed together with the app binaries, partition tables, etc. on idf.py flash or make flash by specifying FLASH_IN_PROJECT. For example:

spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)

If FLASH_IN_PROJECT is not specified, the image is still generated, but user has to flash it manually using esptool.py, parttool.py or a custom build system target.

For an example, see examples/storage/spiffsgen>.

mkspiffs

Another tool for creating SPIFS partition images is mkspiffs. Like spiffsgen.py, it can be used 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

Notes on which SPIFFS tool to use

The two tools presented above offer very similar functionality. There are, however, reasons to prefer one over the other depending on the use case.

If the intent is to simply generate a SPIFFS image during build, spiffsgen.py makes it very convenient by providing functions/commands from the build system itself. This makes it easy to generate SPIFFS images that match the build configuration and can be flashed together with the application. Another case for choosing spiffsgen.py is when the host has no C/C++ compiler available, since mkspiffs requires compilation.

On the other hand, mkspiffs offers unpacking SPIFFS images in addition to image generation. This is not possible with spiffsgen.py, at least not yet. There might also be environments where a Python interpreter is not available, but a host compiler is or a pre-compiled mkspiffs binary can do the job. However, there is no build system integration for mkspiffs and the user has to do the corresponding work: compiling mkspiffs during build (if a pre-compiled binary is not used), creating build rules/targets for the output files, passing proper parameters to the tool, etc.

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.