No Description

Brian Pugh 9eeac09c9c use the non-deprecated upload-components-ci-action 1 week ago
.github 9eeac09c9c use the non-deprecated upload-components-ci-action 1 week ago
example aeb985897e update example to read file flashed, and to FLASH_IN_PROJECT 3 weeks ago
include e43703c0cb Bump version: 1.5.4 → 1.5.5 1 week ago
mklittlefs @ 311ae7d203 2315e181aa Windows-compatible mklittlefs (#123) 4 weeks ago
src c4cc898626 remove unnecessary partition erasing 4 weeks ago
test 76d4602cdf add esp_vfs to test requirements (needed by IDF v5) 9 months ago
.bumpversion.cfg e43703c0cb Bump version: 1.5.4 → 1.5.5 1 week ago
.gitignore aeb985897e update example to read file flashed, and to FLASH_IN_PROJECT 3 weeks ago
.gitmodules 4470dfa1d7 add mklittlefs support; based on work done by pyjamasam, which was baed on the spiffs implementation 1 year ago
CMakeLists.txt 65f9eb4979 add esp_partition only if the major version >=5 6 months ago
Kconfig 5a375263fb Pass CONFIG_LITTLEFS_OBJ_NAME_LEN to the mklittlefs build command (#79) 4 weeks ago
LICENSE 8d9be9f82b Populate missing LICENSE to MIT 2 years ago
Makefile d9f6659f32 have github actions confirm build (#42) 1 year ago e43703c0cb Bump version: 1.5.4 → 1.5.5 1 week ago fcc425ae2f make private APIs in src folder really private 9 months ago
idf_component.yml e43703c0cb Bump version: 1.5.4 → 1.5.5 1 week ago
partition_table_unit_test_app.csv 845de5064b Add flash_test partition 3 years ago
project_include.cmake 2528b7fe0d build: fix for the misuse of IDF_VER to avoid build failure when using with mainline ESP-IDF 1 week ago
sdkconfig.defaults d96b4487ed try and fix some CI (#70) 1 year ago

LittleFS for ESP-IDF.

What is LittleFS?

LittleFS is a small fail-safe filesystem for microcontrollers. We ported LittleFS to esp-idf (specifically, the ESP32) because SPIFFS was too slow, and FAT was too fragile.

How to Use

There are two ways to add this component to your project

  1. As a ESP-IDF managed component: In your project directory run add-dependency joltwallet/littlefs==1.5.5
  2. As a submodule: In your project, add this as a submodule to your components/ directory.

    git submodule add
    git submodule update --init --recursive

The library can be configured via menuconfig under Component config->LittleFS.


User @wreyford has kindly provided a demo repo showing the use of esp_littlefs. A modified copy exists in the example/ directory.


See the official ESP-IDF SPIFFS documentation, basically all the functionality is the same; just replace spiffs with littlefs in all function calls.

Also see the comments in include/esp_littlefs.h

Slight differences between this configuration and SPIFFS's configuration is in the esp_vfs_littlefs_conf_t:

  1. max_files field doesn't exist since we removed the file limit, thanks to @X-Ryl669
  2. partition_label is not allowed to be NULL. You must specify the partition name from your partition table. This is because there isn't a define littlefs partition subtype in esp-idf. The subtype doesn't matter.

Filesystem Image Creation

At compile time, a filesystem image can be created and flashed to the device by adding the following to your project's CMakeLists.txt file:

littlefs_create_partition_image(partition_name path_to_folder_containing_files)

For example, if your partition table looks like:

# Name,   Type, SubType,  Offset,  Size, Flags
nvs,      data, nvs,      0x9000,  0x6000,
phy_init, data, phy,      0xf000,  0x1000,
factory,  app,  factory,  0x10000, 1M,
graphics,  data, spiffs,         ,  0xF0000, 

and your project has a folder called device_graphics, your call should be:

littlefs_create_partition_image(graphics device_graphics)


Here are some naive benchmarks to give a vague indicator on performance.

Formatting a ~512KB partition:

FAT:         963,766 us
SPIFFS:   10,824,054 us
LittleFS:  2,067,845 us

Writing 5 88KB files:

FAT:         13,601,171 us
SPIFFS*:    118,883,197 us
LittleFS**:   6,582,045 us
LittleFS***:  5,734,811 us
*Only wrote 374,784 bytes instead of the benchmark 440,000, so this value is extrapolated
***CONFIG_LITTLEFS_CACHE_SIZE=512 (default value)

In the above test, SPIFFS drastically slows down as the filesystem fills up. Below is the specific breakdown of file write times for SPIFFS. Not sure what happens on the last file write.


88000 bytes written in 1325371 us
88000 bytes written in 1327848 us
88000 bytes written in 5292095 us
88000 bytes written in 19191680 us
22784 bytes written in 74082963 us

Reading 5 88KB files:

FAT:          3,111,817 us
SPIFFS*:      3,392,886 us
LittleFS**:   3,425,796 us
LittleFS***:  3,210,140 us
*Only read 374,784 bytes instead of the benchmark 440,000, so this value is extrapolated
***CONFIG_LITTLEFS_CACHE_SIZE=512 (default value)

Deleting 5 88KB files:

FAT:         934,769 us
SPIFFS*:      822,730 us
LittleFS**:   31,502 us
LittleFS***:  20,063 us
*The 5th file was smaller, did not extrapolate value.
***CONFIG_LITTLEFS_CACHE_SIZE=512 (default value)

Tips, Tricks, and Gotchas

  • LittleFS operates on blocks, and blocks have a size of 4096 bytes on the ESP32.

  • A freshly formatted LittleFS will have 2 blocks in use, making it seem like 8KB are in use.

Running Unit Tests

To flash the unit-tester app and the unit-tests, clone or symbolicly link this component to $IDF_PATH/tools/unit-test-app/components/littlefs. Make sure the folder name is littlefs, not esp_littlefs. Then, run the following:

cd $IDF_PATH/tools/unit-test-app menuconfig  # See notes -T littlefs -p YOUR_PORT_HERE flash monitor

In menuconfig:

  • Set the partition table to components/littlefs/partition_table_unit_test_app.csv

  • Double check your crystal frequency ESP32_XTAL_FREQ_SEL; my board doesn't work with autodetect.

To test on an encrypted partition, add the encrypted flag to the flash_test partition in partition_table_unit_test_app.csv. I.e.

flash_test,  data, spiffs,    ,        512K, encrypted

Also make sure that CONFIG_SECURE_FLASH_ENC_ENABLED=y in menuconfig.

The unit tester can then be flashed via the command: -T littlefs -p YOUR_PORT_HERE encrypted-flash monitor

Breaking Changes

  • July 22, 2020 - Changed attribute type for file timestamp from 0 to 0x74 ('t' ascii value).
  • May 3, 2023 - All logging tags have been changed to a unified esp_littlfs.


This code base was heavily modeled after the SPIFFS esp-idf component.