minimum-necessary-change / LITTLEFS

LittleFS library for arduino-esp32

LittleFS_esp32

Notice: The Library is been integrated to Arduino esp32 core idf-release/v4.2 branch for future major core release. On built-in library, #define tweaks below will be unavailable.

LittleFS library for arduino-esp32

• A LittleFS wrapper for Arduino ESP32 of littlefs-project
• Based on ESP-IDF port of joltwallet/esp_littlefs , thank you Brian!
• As a reference, see LillteFS library for ESP8266 core
• PR and merge at esp32 core development
• PR at esp-idf development
• The functionality is similar to SPIFFS

Installation

• Use Arduino Library Manager
• Or download / use git to have latest repository of LITTLEFS added to Arduino IDE /libraries folder
  (File > Preferences > Sketchbook location).
• See #define CONFIG_LITTLEFS_FOR_IDF_3_2 in esp_littlefs.c.
  Now it is defined / undefined automatically by detecting the IDF version and core version. When defined, the library works with old and new IDFs 3.2 - 4.x but file timestamp feature is removed. See LITTLEFS_time example.
• See #define CONFIG_LITTLEFS_SPIFFS_COMPAT in esp_littlefs.c.
  When set to 1, folders are recursively created or deleted if empty on creating/deleting a new file like SPIFFS. Default is 0.
• The other #define CONFIG_LITTLEFS_xxxxx are set to optimal default values.
  Read here and here if you want to modify.
• For low-level default error reporting modifications, see the defines at beginning of the lfs.c here.

Usage

• Use LITTLEFS with identical methods as SPIFFS plus mkdir() and rmdir()
• A quick startup based on your existing code you can re-define SPIFFS

#define USE_LittleFS

#include <FS.h>
#ifdef USE_LittleFS
  #define SPIFFS LITTLEFS
  #include <LITTLEFS.h> 
#else
  #include <SPIFFS.h>
#endif 

• Note, this may not work if your sketch uses other libraries that use SPIFFS themselves.
• See also esp_partition.h . LITTLEFS re-uses same type and subtype as SPIFFS

Differences with SPIFFS

• LittleFS has folders, you need to iterate files in folders unless you set #define CONFIG_LITTLEFS_SPIFFS_COMPAT 1
• At root a "/folder" = "folder"
• Requires a label for mount point, NULL will not work. Recommended is to use default LITTLEFS.begin()
• maxOpenFiles parameter is unused, kept for compatibility
• LITTLEFS.mkdir(path) and LITTLEFS.rmdir(path) are available
• file.seek() behaves like on FFat see more details
• file.write() and file.print() when partition space is ending may return different than really written bytes (on other FS is also inconsistent).
• Speed comparison based on LittleFS_test.ino sketch (for a file 1048576 bytes):

Filesystem	Read time [ms]	Write time [ms]
FAT	276	14493
LITTLEFS	446*	16387
SPIFFS	767	65622

*The read speed improved by changing #define CONFIG_LITTLEFS_CACHE_SIZE from 128 to 512

Arduino ESP32 LittleFS filesystem upload tool

• Use (replace if exists) arduino-esp32fs-plugin with this variant, which supports SPIFFS, LittleFS and FatFS
• Requires mklittlefs executable which is available in releases section here or download the zipped binary here or from esp-quick-toolchain releases here
• Copy it to /tools folder of esp32 platform where espota and esptool (.py or.exe) tools are located
• Restart Arduino IDE.

PlatformIO

• See LITTLEFS_PlatformIO example here
  ( based on notes below from BlueAndi )

• Add to platformio.ini: extra_scripts = replace_fs.py

• Add replace_fs.py to project root directory (where platformio.ini is located):

Import("env")
print("Replace MKSPIFFSTOOL with mklittlefs.exe")
env.Replace (MKSPIFFSTOOL = "mklittlefs.exe")

• Add mklittlefs.exe to project root directory as well.

Credits and license

• This work is based on littlefs-project , ESP-IDF port of joltwallet/esp_littlefs , Espressif Arduino core for the ESP32, the ESP-IDF - SPIFFS Library
• Licensed under GPL v2 (text)

To Do

• Submit to be added to Arduino Library Manager
• Optional drop-in compatibility with SPIFFS' lack of folders, similar to esp8266' way - implemented as a choice by a #define
  • recursive folders auto creation when a new file is created at non-existing path
  • recursive folders auto deletion on "last file" deletion (SPIFFS cannot have "folder w/o file")
  • review other differences: opendir(), rmdir(), unlink()
• Retire this library when released by esp32 Arduino core
• Cleanup examples