SPIFFS is a file system intended for SPI NOR flash devices on embedded targets. It supports wear levelling, file system consistency checks, and more.
Currently, SPIFFS does not support directories, it produces a flat structure. If SPIFFS is mounted under
/spiffs, then creating a file with the path
/spiffs/tmp/myfile.txtwill create a file called
/tmp/myfile.txtin SPIFFS, instead of
myfile.txtin the directory
It is not a real-time stack. One write operation might take much longer than another.
For now, it does not detect or handle bad blocks.
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, open Terminal and run:
python spiffsgen.py <image_size> <base_dir> <output_file>
The required arguments are as follows:
image_size: size of the partition onto which the created SPIFFS image will be flashed.
base_dir: directory for which the SPIFFS image needs to be created.
output_file: SPIFFS image output file.
There are also other arguments that control image generation. Documentation on these arguments can be found in the tool’s help:
python spiffsgen.py --help
These optional arguments correspond to a possible SPIFFS build configuration. To generate the right image, please make sure that you use the same arguments/configuration as were used to build SPIFFS. As a guide, the help output indicates the SPIFFS build configuration to which the argument corresponds. In cases when these arguments are not specified, the default values shown in the help output will be used.
When the image is created, it can be flashed using
Aside from invoking the
spiffsgen.py standalone by manually running it from the command line or a script, it is also possible to invoke
spiffsgen.py directly from the build system by calling
SPIFFS_IMAGE_FLASH_IN_PROJECT := ... SPIFFS_IMAGE_DEPENDS := ... $(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
spiffs_create_partition_image(<partition> <base_dir> [FLASH_IN_PROJECT] [DEPENDS dep dep dep...])
This is more convenient as the build configuration is automatically passed to the tool, ensuring that the generated image 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.
Due to the differences in structure between Make and CMake, it is important to note that:
- for Make
spiffs_create_partition_image must be called from the project Makefile
- for CMake
spiffs_create_partition_image must be called from one of the component CMakeLists.txt files
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_IMAGE_FLASH_IN_PROJECT := 1 $(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
spiffs_create_partition_image(my_spiffs_partition my_folder FLASH_IN_PROJECT)
If FLASH_IN_PROJECT/SPIFFS_IMAGE_FLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually using
parttool.py, or a custom build system target.
There are cases where the contents of the base directory itself is generated at build time. Users can use DEPENDS/SPIFFS_IMAGE_DEPENDS to specify targets that should be executed before generating the image.
dep: ... SPIFFS_IMAGE_DEPENDS := dep $(eval $(call spiffs_create_partition_image,<partition>,<base_dir>))
add_custom_target(dep COMMAND ...) spiffs_create_partition_image(my_spiffs_partition my_folder DEPENDS dep)
+For an example, see examples/storage/spiffsgen>.
Another tool for creating SPIFFS partition images is mkspiffs.
spiffsgen.py, it can be used to create an image from a given folder and then flash that image using
For that, you need to obtain the following 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 a partition table)
Partition Offset: Starting address of the partition (can be obtained from a partition table)
To pack a folder into a 1-Megabyte image, run:
mkspiffs -c [src_folder] -b 4096 -p 256 -s 0x100000 spiffs.bin
To flash the image onto ESP32 at offset 0x110000, run:
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. However, there are reasons to prefer one over the other, depending on the use case.
spiffsgen.py in the following cases:
1. If you want to simply generate a SPIFFS image during the build.
spiffsgen.py makes it very convenient by providing functions/commands from the build system itself.
2. If the host has no C/C++ compiler available, because
spiffsgen.py does not require compilation.
mkspiffs in the following cases:
1. If you need to unpack SPIFFS images in addition to image generation. For now, it is not possible with
2. If you have an environment where a Python interpreter is not available, but a host compiler is available. Otherwise, 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.
An example of using SPIFFS is provided in the storage/spiffs directory. This example initializes and mounts a SPIFFS partition, then writes and reads data from it using POSIX and C library APIs. See the README.md file in the example directory for more information.
High-level API Reference¶
esp_vfs_spiffs_register(const esp_vfs_spiffs_conf_t *conf)¶
Register and mount SPIFFS to VFS with given path prefix.
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
conf: Pointer to esp_vfs_spiffs_conf_t configuration structure
esp_vfs_spiffs_unregister(const char *partition_label)¶
Unregister and unmount SPIFFS from VFS
ESP_OK if successful
ESP_ERR_INVALID_STATE already unregistered
partition_label: Optional, label of the partition to unregister. If not specified, first partition with subtype=spiffs is used.
esp_spiffs_mounted(const char *partition_label)¶
Check if SPIFFS is mounted
true if mounted
false if not mounted
partition_label: Optional, label of the partition to check. If not specified, first partition with subtype=spiffs is used.
esp_spiffs_format(const char *partition_label)¶
Format the SPIFFS partition
ESP_OK if successful
ESP_FAIL on error
partition_label: Optional, label of the partition to format. If not specified, first partition with subtype=spiffs is used.
esp_spiffs_info(const char *partition_label, size_t *total_bytes, size_t *used_bytes)¶
Get information for SPIFFS
ESP_OK if success
ESP_ERR_INVALID_STATE if not mounted
partition_label: Optional, label of the partition to get info for. If not specified, first partition with subtype=spiffs is used.
[out] total_bytes: Size of the file system
[out] used_bytes: Current used bytes in the file system
Configuration structure for esp_vfs_spiffs_register.
const char *
File path prefix associated with the filesystem.
const char *
Optional, label of SPIFFS partition to use. If set to NULL, first partition with subtype=spiffs will be used.
Maximum files that could be open at the same time.
If true, it will format the file system if it fails to mount.
- const char *