Chapter 2. API Reference
• SPIFFS is able to reliably utilize only around 75% of assigned partition space.
• When the filesystem is running out of space, the garbage collector is trying to find free space by scanning the
filesystem multiple times, which can take up to several seconds per write function call, depending on required
space. This is caused by the SPIFFS design and the issue has been reported multiple times (e.g. here) and in
the official SPIFFS github repository. The issue can be partially mitigated by the SPIFFS configuration.
• Deleting a file does not always remove the whole file, which leaves unusable sections throughout the filesystem.
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, 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 esptool.py or parttool.py.
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_create_partition_image.
Make:
SPIFFS_IMAGE_FLASH_IN_PROJECT := ...
SPIFFS_IMAGE_DEPENDS := ...
$(eval
$(call
spiffs_create_partition_image,<partition>,<base_dir>))
CMake:
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 CMake-
Lists.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,
in Make:
Espressif Systems 765
Submit Document Feedback
Release v4.4
To Next Page
Loading...
Need help?
General