Learn how to upload files to the ESP8266 NodeMCU board filesystem (LittleFS) using VS Code with the PlatformIO IDE extension (quick and easy). Using the filesystem with the ESP8266 can be useful to save HTML, CSS and JavaScript files to build a web server instead of having to write everything inside the Arduino sketch.
If you’re using Arduino IDE follow this tutorial instead: Install ESP8266 Filesystem Uploader in Arduino IDE.
Introducing SPIFFS/LittleFS
There are two filesystems you can use for the onboard ESP8266 flash: SPIFFS and LittleFS.
SPIFFS and LittleFS let you access the flash memory like you would do in a normal filesystem in your computer, but simpler and more limited. You can read, write, close, and delete files.
SPIFFS:
- original filesystem;
- ideal for space and RAM constrained applications that use many files;
- doesn’t support directories – everything is saved on a flat structure;
- filesystem overhead on the flash is minimal;
- SPIFFS is currently deprecated and may be removed in future releases of the core.
LittleFS:
- recent;
- focuses on higher performance;
- supports directories;
- higher filesystem and per-file overhead (4K minimum vs. SPIFFS’ 256 byte minimum file allocation unit).
For more information about SPIFFS and LittleFS, refer to the ESP8266 Arduino Core documentation.
SPIFFS is currently deprecated and may be removed in future releases of the ESP8266
core. It is recommended to use LittleFS instead.
LittleFS is under active development, supports directories, and is many times faster for most operations. The methods used for SPIFFS are compatible with LittleFS, so, we can simply use the expression LittleFS instead of SPIFFS when converting a code from SPIFFS to LittleFS.
For example, converting most applications from SPIFFS to LittleFS simply requires changing the SPIFFS.begin() to LittleFS.begin() and SPIFFS.open() to LittleFS.open().
Using the filesystem with the ESP8266 board is specially useful to:
- Create configuration files with settings;
- Save data permanently;
- Create files to save small amounts of data instead of using a microSD card;
- Save HTML, CSS and JavaScript files to build a web server;
- Save images, figures and icons;
- And much more.
Upload Files to ESP8266 NodeMCU LittleFS
The files you want to upload to the ESP8266 filesystem should be placed in a folder called data under the project folder. For you to understand how everything works, we’ll upload a .txt file with some random text. You can upload any other file type.
If you’re not familiar with VS Code + PlatformIO IDE, follow the next tutorial first:
Using LittleFS as Default Filesystem
SPIFFS is currently deprecated and may be removed in future releases of the ESP8266 core. It is recommended to use LittleFS instead. LittleFS is under active development, supports directories, and is many times faster for most operations. So, we’ll use LittleFS in this tutorial.
In VS Code + PlatformIO, when uploading files, we must specify that we want to use LittleFS filesystem instead of SPIFFS (default), so you need to add the following line to the ESP826 platformio.ini configuration file.
board_build.filesystem = littlefs
Creating a data Folder
Create a folder called data inside your project folder. This can be done on VS Code.
With your mouse, select the project folder you’re working on. Click on the New Folder icon to create a new folder.
This new folder must be called data, otherwise, it won’t work.
Then, select the newly created data folder and create the files you want to upload by clicking on the New File icon. In this example, we’ll create a file called text.txt. You can create and upload any other file types like .html, .css or .js files, for example.
Write some random text inside that .txt file.
The data folder should be under the project folder and the files you want to upload should be inside the data folder. Otherwise, it won’t work.
Uploading Filesystem Image
After creating and saving the file or files you want to upload under the data folder, follow the next steps:
- Click the PIO icon at the left side bar. The project tasks should open.
- Select env:nodemcuv2 (it may different depending on the board you’re using).
- Expand the Platform menu.
- Select Build Filesystem Image.
- Finally, click Upload Filesystem Image.
Important: to upload the filesystem image successfully you must close all serial
connections (Serial Monitor) with your board.
After a while, you should get a success message.
Troubleshooting
Here’s a common mistake:
Could not open port “COMX” Access is denied.
This error means that you have a serial connection opened with your board in VS Code or in any other program. Close any program that might be using the board serial port, and make sure you close all serial connections in VS Code (click on the recycle bin icon on the terminal console).
Testing
Now, let’s just check if the file was actually saved into the ESP8266 filesystem. Copy the following code to the main.cpp file and upload it to your board.
/*********
Rui Santos
Complete project details at https://RandomNerdTutorials.com/esp8266-nodemcu-vs-code-platformio-littlefs/
*********/
#include <Arduino.h>
#include "LittleFS.h"
void setup() {
Serial.begin(9600);
if(!LittleFS.begin()){
Serial.println("An Error has occurred while mounting LittleFS");
return;
}
File file = LittleFS.open("/text.txt", "r");
if(!file){
Serial.println("Failed to open file for reading");
return;
}
Serial.println("File Content:");
while(file.available()){
Serial.write(file.read());
}
file.close();
}
void loop() {
}
You may need to change the following line depending on the name of your file.
File file = LittleFS.open("/text.txt");Open the Serial Monitor and it should print the content of your file.
You’ve successfully uploaded files to the ESP8266 filesystem (LittleFS) using VS Code + PlatformIO.
Wrapping Up
With this tutorial you’ve learned how to upload files to the ESP8266 filesystem (LittleFS) using VS Code + PlatformIO. It is quick and easy.
This can be specially useful to upload HTML, CSS and JavaScript files to build web server projects with the ESP8266 NodeMCU boards.
We have a similar tutorial for the ESP32:Â ESP32 with VS Code and PlatformIO: Upload Files to Filesystem (SPIFFS)
Learn more about the ESP8266 NodeMCU with our resources:
Do you have tutorial, about how to change api key, using Web server and littlefs method?
Hi Rafael.
What API key?
Regards,
Sara
Exactly what I was looking for, thanks for covering this.
Just a comment: in your test code, you seems to include:
#include “LittleFS.h”
I do not see it anywhere. Compiler complains about not finding it.
Is it some external library you include?
Hi.
In didn’t need to include anything.
Just make sure you have the right settings on the platformio.ini file.
But, what is exactly the error that you get?
Regards,
Sara
Thanks for your reply
In vscode + pio, I get the include line highlighted with this message:
“#include errors detected. Please update your includePath. ”
and then at compilation time I get this error:
“lib/filesystem/filesys.cpp:3:22: fatal error: LittleFS.h: No such file or directory”
My platformio.ini, contains:
[env:esp32doit-devkit-v1]
platform = espressif32
board = esp32doit-devkit-v1
framework = arduino
monitor_speed = 115200
board_build.filesystem = littlefs
lib_deps = me-no-dev/ESP Async WebServer@^1.2.3
The code is working well with SPIFFS version…
I’ll investigate a bit further but if you see where it could come from that would be helpful.
Regards,
Hello,
I was curious to know whether you managed to solve this issue?
I’m using “esphome” command to compile my project and I’m get the same error:
src/SomfyRts.cpp:2:10: fatal error: LittleFS.h: No such file or directory******************************************************************
* Looking for LittleFS.h dependency? Check our library registry!
*
* CLI > platformio lib search "header:LittleFS.h"
* Web > https://registry.platformio.org/search?q=header:LittleFS.h
*
******************************************************************
2 | #include <LittleFS.h>
| ^~~~~~~~~~~~
compilation terminated.
*** [.pioenvs/esp-somfy/src/SomfyRts.cpp.o] Error 1
Thanks for your tutorial. I have some problem when I do this program. The step of “Uploading Filesystem Image”, I don’t understand how this work, what does the function do in here? And on the left, my “PROJECT TASKS” is empty, nothing here. This my first time do it, I need your help, thanks.
Hi.
That function uploads any files inside the data folder to the ESP8266 filesystem.
Can you try the following?
With your project opened in VS Code, go to View > Pallete.
Then, write: >Refresh project tasks, and select that option.
Then, check if the Platform Tasks to upload an image to the filesystem were updated.
I hope this helps.
Regards,
Sara
Thank you. But I write refresh test: refreshing tests, I don’t find refresh project tasks, and then it shows error (command ‘python.refreshingTests’ not found) and “No tree view with id ‘platformio-activitybar.projectTasks’ registered”, while checking the ant logo.
Great content that save me a lot of time !! many thanks !
Hi ! Thanks for all your work !
I’m in step “Build Filesystem Image” and that terminate with error
Building file system image from ‘data’ directory to .pio\build\esp_wroom_02\littlefs.bin
*** [.pio\build\esp_wroom_02\littlefs.bin] Error 3221225620
Hi.
Check this discussion and see if it helps.
Regards,
Sara
Hi thanks for you fast answer !
I use
board_build.filesystem = littlefs in .ini
And i create “data” folder at the same level of src
I try
View > Pallete.
Then, write: >Refresh project tasks, and select that option.
But every time the same:
PACKAGES:
– framework-arduinoespressif8266 3.30002.0 (3.0.2)
– tool-esptool 1.413.0 (4.13)
– tool-esptoolpy 1.30000.201119 (3.0.0)
– tool-mklittlefs 1.203.210628 (2.3)
– tool-mkspiffs 1.200.0 (2.0)
– toolchain-xtensa 2.100300.210717 (10.3.0)
LDF: Library Dependency Finder -> https://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 37 compatible libraries
Scanning dependencies…
Dependency Graph
|– 2.1.0
| |– 1.2.3
| |– 1.0
| |– 1.0
|– 0.1.0
Building in release mode
Building file system image from ‘data’ directory to .pio\build\esp_wroom_02\littlefs.bin
*** [.pio\build\esp_wroom_02\littlefs.bin] Error 3221225620
and i check my littlefs.bin is empty
I someone have an idea for me!
Again thx for all of your website very helpful !
Have a good day
Hi.
don’t you have the “Upload Filesystem Image” option on the left sidebar?
Regards,
Sara
Hi Sara, thanks for your valuable support, I have your boock, Building a Web Server with ESP32 & 8266…….I have the same problem and ERROR, my PIO is fine instaled, platformio.ini is configured as you had indicated, but I don’t overcome the error:
Here the ERROR:
Building in release mode
Building file system image from ‘data’ directory to .pio\build\esp_wroom_02\littlefs.bin
*** [.pio\build\esp_wroom_02\littlefs.bin] Error 3221225620
Here my PIO config:
[env:esp_wroom_02]
platform = espressif8266
board = esp_wroom_02
framework = arduino
monitor_speed = 115200
lib_deps =
ESP Async WebServer
me-no-dev/ESPAsyncTCP@^1.2.2
ottowinter/ESPAsyncWebServer-esphome@^3.0.0
board_build.filesystem = littlefs
Hi.
Because you are one of our customers, please post your issue on the RNTLAB forum: https://rntlab.com/forum/
We can help you better there.
Check your PIO file and compare it with one on the tutorial. You’re not using the same exact libraries.
Regards,
Sara
Hi, thank you for your tutorial, Is it possible to use littlefs with esp8266 EEPROM emulation (eeprom.h)? Will they interfere as they both use ESP826 flash memory?
right now I’m using svelte tool kit for my webpage but when i try to load page by using esp32 dev kit it become panic and reset it. but the thing is when i use slow 3G throttle in chrome dev option it load my all elements perfectly every time.
so is there anything i do in server side so i load my page without using throttling option
I have tried to understand how to create different partitions in Platformio but would appreciate a tutorial to create partitions the same as the Arduino ide dose such as No OTA, 1mb app and 3mb flash.
Hi.
At the moment, we don’t have any detailed tutorial about that subject.
Here are some information: https://docs.platformio.org/en/latest/platforms/espressif32.html#partition-tables
I’ll see ifn I can create a detailed and easy to follow tutorial in the future.
Regards,
Sara
After 1 week I found this post and solve all.
It works fine.
Rui and Sara are two wizard.
Thanks!!! From Italy.
Although I have that line in platformio.ini …
board_build.filesytem = littlefs
… to tell the system that I’d like to use LittleFS, not the deprecated SPIFFS, it keeps building the following target file (not littlefs.bin):
Dependency Graph
|– LittleFS @ 0.1.0
Building in release mode
Building file system image from ‘data’ directory to .pio/build/nodemcuv2/spiffs.bin
As a result, the sample code fails to open the file for reading.
Any idea why VS Code + PlatformIO apparently creates the wrong file system image (SPIFFS instead of LittleFS)?
Please ignore my post –
I found the error (the typo in the platformio.ini).
Sorry for disturbing.
Hi Sara, Heres another example of issues with uploading to ESP8266. This time using VScode. Yes it was set up in the .ini folder, and included in the list of libraries.
src\main.cpp: In function ‘void initFS()’:
src\main.cpp:40:8: error: ‘littlefs’ was not declared in this scope
40 | if (!littlefs.begin()) {
| ^~~~~~~~
src\main.cpp: In lambda function:
src\main.cpp:132:19: error: ‘littlefs’ was not declared in this scope
132 | request->send(littlefs, “/index.html”, “text/html”,false);
| ^~~~~~~~
src\main.cpp: In function ‘void setup()’:
src\main.cpp:135:27: error: ‘littlefs’ was not declared in this scope
135 | server.serveStatic(“/”, littlefs, “/”);
Hi John,
I am not Sara, and I am a beginner only, but it seems to me that your issue is merely because you used all lowercase for “littlefs”. On my end it works within VScode+PlatformIO with “LittleFS”, like this:
if(!LittleFS.begin()) …
I hardly dare to mention that C/C++ is case-sensitive. Hope you don’t mind.
Thanks for the reply beginners, but no, I indeed use LittltFS.
Hi.
In the code, it should be LittleFS, not littlefs.
Replace “littlefs” with “LittleFS” on your code (not on the platformio.ini)
Regards,
Sara
Hi Sara, Since there seems to be so many different iterations of littlefs, LittleFS, LittleFS for ESP32, and various naming convensions dependent on what IDE is being used, there seems to be an inconsistency. After correcting as per your suggestion. I got this. Apparently I have a old/wrong version of AsyncWebServer? It is confusing when adding a library in platform io, as to which “AsyncWebServer” library to choose.
In file included from .pio\libdeps\d1_mini\ESP Async WebServer\src\SPIFFSEditor.cpp:1:
.pio\libdeps\d1_mini\ESP Async WebServer\src\SPIFFSEditor.h:16:101: warning: ‘SPIFFS’ is deprecated: SPIFFS has been deprecated. Please consider moving to LittleFS or other filesystems. [-Wdeprecated-declarations]
16 | SPIFFSEditor(const String& username=String(), const String& password=String(), const fs::FS& fs=SPIFFS);
| ^~~~~~
In file included from .pio\libdeps\d1_mini\ESP Async WebServer\src/ESPAsyncWebServer.h:27,
from .pio\libdeps\d1_mini\ESP Async WebServer\src\SPIFFSEditor.h:3,
from .pio\libdeps\d1_mini\ESP Async WebServer\src\SPIFFSEditor.cpp:1:
C:\Users\flagt.platformio\packages\framework-arduinoespressif8266\cores\esp8266/FS.h:286:15: note: declared here
286 | extern fs::FS SPIFFS attribute((deprecated(“SPIFFS has been deprecated. Please consider moving to LittleFS or other filesystems.”)));
| ^~~~~~
Hi.
Even though you’re using LittleFS, you may continue having those messages.
Those are just warning messages and not compilation errors.
That should not prevent the code from compiling or uploading.
Regards,
Sara
Hi Sara, Yeah I figured that, thanks for the clarification. For those of us that are from the vacuum tube days it can shake our confidence LOL. Thanks again.
Great staff!! Many thanks ! Just checking, I assume that the cycle of build/upload/build file system image/upload file system image in VS code is necessary every time you make a change in code, right?
Yes. That’s right.
Regards,
Sara
My code compiles and uploads to the ESP8266,
Under project tasks I do not have a menu option platform so do not have the option to upload the filesystem.
I have closed and restarted VSC, created a new project and cannot get the option.
If I open a terminal window and enter the command
pio run –target uploadfs
I get an error
sh: 1: mkspiffs: not found
my platformio.ini file is
; PlatformIO Project Configuration File
;
; Build options: build flags, source filter
; Upload options: custom upload port, speed and extra flags
; Library options: dependencies, extra library storages
; Advanced options: extra scripting
;
; Please visit documentation for the other options and examples
; https://docs.platformio.org/page/projectconf.html
[env:nodemcu]
platform = espressif8266
board = nodemcu
framework = arduino
monitor_speed = 115200
board_build.filesystem = littlefs
Any suggestions as to how to proceed?
I have tried searching for solutions without success, even trying other projects.
The ESP8266 has had other projects downloaded to it, do I need to erase the flash and then try the pio command ?
cheers
Steve
It is always the same, I post a problem and then sort of find the solution.
I tend to use my raspberry PI4 for running VSC etc.
That is using VSC version 1.09 and platform IO core 6.1.15 and home 3.4.4
I installed VSC on my MAC,
VSC version 90.1 and platform iIO is the same as my raspberry PI.
It works on my MAC and not the raspberry pi, so I need to see how I can update the version on my PI.
I thought I had updated it, maybe I need to wait until the PI foundation do an update.
Steve