Repository files navigation

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

There are two ways to add this component to your project

1. As a ESP-IDF managed component: In your project directory run

idf.py add-dependency joltwallet/littlefs==1.20.2

2. As a submodule: In your project, add this as a submodule to yourcomponents/ directory.

git submodule add https://github.com/joltwallet/esp_littlefs.gitgit submodule update --init --recursive

The library can be configured viaidf.py menuconfig underComponent config->LittleFS.

User @wreyford has kindly provided ademo repo showing the use ofesp_littlefs. A modified copy exists in theexample/ directory.

Add to the following line to your project'splatformio.ini file:

lib_deps = https://github.com/joltwallet/esp_littlefs.git

Exampleplatformio.ini file:

[env]platform = espressif32framework = espidfmonitor_speed = 115200[common]lib_deps = https://github.com/joltwallet/esp_littlefs.git[env:nodemcu-32s]board = nodemcu-32sboard_build.filesystem = littlefsboard_build.partitions = min_littlefs.csvlib_deps = ${common.lib_deps}

Examplemin_littlefs.cvs flash partition layout:

# Name,   Type, SubType,  Offset,  Size, Flagsnvs,      data, nvs,      0x9000,  0x5000,otadata,  data, ota,      0xe000,  0x2000,app0,     app,  ota_0,    0x10000, 0x1E0000,app1,     app,  ota_1,    0x1F0000,0x1E0000,littlefs, data, littlefs,   0x3D0000,0x20000,coredump, data, coredump, 0x3F0000,0x10000,

Currently, it is required to modifyCMakeList.txt. Add the following 2 lines to the your project'sCMakeList.txt:

get_filename_component(configName "${CMAKE_BINARY_DIR}" NAME)list(APPEND EXTRA_COMPONENT_DIRS "${CMAKE_SOURCE_DIR}/.pio/libdeps/${configName}/esp_littlefs")

ExampleCMakeList.txt:

cmake_minimum_required(VERSION 3.16.0)include($ENV{IDF_PATH}/tools/cmake/project.cmake)get_filename_component(configName "${CMAKE_BINARY_DIR}" NAME)list(APPEND EXTRA_COMPONENT_DIRS "${CMAKE_SOURCE_DIR}/.pio/libdeps/${configName}/esp_littlefs")project(my_project_name_here)

To configure LittleFS from PlatformIO, run the following command:

$pio run -t menuconfig

An entryComponent config->LittleFS should be available for configuration. If not, check yourCMakeList.txt configuration.

See the officialESP-IDF SPIFFS documentation, basically all the functionality is thesame; just replacespiffs withlittlefs in all function calls.

Also see the comments ininclude/esp_littlefs.h

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

1. max_files field doesn't exist since we removed the file limit, thanks to @X-Ryl669
2. grow_on_mount will expand an existing filesystem to fill the partition. Defaults tofalse.
   • LittleFS filesystems can only grow, they cannot shrink.

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

littlefs_create_partition_image(partition_name path_to_folder_containing_files FLASH_IN_PROJECT)

IfFLASH_IN_PROJECT is not specified, the image will still be generated, but you will have to flash it manually usingesptool.py,parttool.py, or a custom build system target.

For example, if your partition table looks like:

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

change it to:

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

and your project has a folder calleddevice_graphics/, your call should be:

littlefs_create_partition_image(graphics device_graphics FLASH_IN_PROJECT)

Here are some naive benchmarks to give a vague indicator on performance.Tests were performed with the following configuration:

• ESP-IDF: v4.4
• Target: ESP32
• CPU Clock: 160MHz
• Flash SPI Freq: 80MHz
• Flash SPI Mode: QIO

In these tests, FAT has a cache size of 4096, and SPIFFS has a cahce size of 256 bytes.

FAT:         549,494 usSPIFFS:   10,715,425 usLittleFS:    110,997 us

FAT:                            7,124,812 usSPIFFS*:                       99,138,905 usLittleFS (cache=128):           8,261,920 usLittleFS (cache=512 default):   6,356,247 usLittleFS (cache=4096):          6,026,592 us*Only wrote 374,784 bytes instead of the benchmark 440,000, so this value is extrapolated

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

SPIFFS:88000 bytes written in 2190635 us88000 bytes written in 2190321 us88000 bytes written in 5133605 us88000 bytes written in 16570667 us22784 bytes written in 73053677 us

FAT:                            5,685,230 usSPIFFS*:                        5,162,289 usLittleFS (cache=128):           6,284,142 usLittleFS (cache=512 default):   5,874,931 usLittleFS (cache=4096):          5,731,385 us*Only read 374,784 bytes instead of the benchmark 440,000, so this value is extrapolated

FAT:                              680,358 usSPIFFS*:                        1,653,500 usLittleFS (cache=128):              86,090 usLittleFS (cache=512 default):      53,705 usLittleFS (cache=4096):             27,709 us*The 5th file was smaller, did not extrapolate value.

• 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.

• The esp32 hasflash concurrency constraints.When using UART (either for data transfer or generic logging) at the same time, youMUST enable the following option in KConfig:menuconfig > Component config > Driver config > UART > UART ISR in IRAM.

To flash the unit-tester app and the unit-tests, clone or symbolicly link thiscomponent to$IDF_PATH/tools/unit-test-app/components/littlefs. Make sure thefolder name islittlefs, notesp_littlefs. Then, run the following:

cd $IDF_PATH/tools/unit-test-appidf.py menuconfig  # See notesidf.py -T littlefs -p YOUR_PORT_HERE flash monitor

Inmenuconfig:

• Set the partition table tocomponents/littlefs/partition_table_unit_test_app.csv

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

To test on an encrypted partition, add theencrypted flag to theflash_test partitioninpartition_table_unit_test_app.csv. I.e.

flash_test,  data, spiffs,    ,        512K, encrypted

Also make sure thatCONFIG_SECURE_FLASH_ENC_ENABLED=y inmenuconfig.

The unit tester can then be flashed via the command:

idf.py -T littlefs -p YOUR_PORT_HERE encrypted-flash monitor

• July 22, 2020 - Changed attribute type for file timestamp from0 to0x74 ('t' ascii value).
• May 3, 2023 - All logging tags have been changed to a unifiedesp_littlefs.

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