The ESP8266 contains a Serial Peripheral Interface Flash File System (SPIFFS). SPIFFS is a lightweight filesystem created for microcontrollers with a flash chip. This article shows how to easily upload files to the ESP8266 filesystem using a plugin for Arduino IDE.
Note: if you have an ESP32 board, read Install ESP32 Filesystem Uploader in Arduino IDE.
Introducing SPIFFS
SPIFFS lets you access the flash chip 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 doesn’t support directories, so everything is saved on a flat structure.
Using SPIFFS 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 and CSS files to build a web server;
- Save images, figures and icons;
- And much more.
In most of our web server projects, we’ve written the HTML code for the web server as a String directly on the Arduino sketch. With SPIFFS, you can write the HTML and CSS in separated files and save them on the ESP8266 filesystem.
Installing the Arduino ESP8266 Filesystem Uploader
You can create, save and write files to the ESP8266 filesystem by writing the code yourself in Arduino IDE. This is not very useful, because you’d have to type the content of your files in the Arduino sketch.
Fortunately, there is a plugin for the Arduino IDE that allows you to upload files directly to the ESP8266 filesystem from a folder in your computer. This makes it really easy and simple to work with files. Let’s install it.
First, make sure you have the latest Arduino IDE installed, and you have the ESP8266 add-on for the Arduino IDE. If you don’t, follow the next tutorial to install the add-on:
Follow the next steps to install the filesystem uploader:
1) Go to the releases page and click the ESP8266FS-X.zip file to download.
2) Go to the Arduino IDE directory, and open the Tools folder.
3) Unzip the downloaded .zip folder to the Tools folder. You should have a similar folder structure:
<home_dir>/Arduino-<version>/tools/ESP8266FS/tool/esp8266fs.jar
4) Finally, restart your Arduino IDE.
To check if the plugin was successfully installed, open your Arduino IDE and select your ESP8266 board. In the Tools menu check that you have the option “ESP8266 Sketch Data Upload“.
Uploading Files using the Filesystem Uploader
To upload files to the ESP8266 filesystem follow the next instructions.
1) Create an Arduino sketch and save it. For demonstration purposes, you can save an empty sketch.
2) Then, open the sketch folder. You can go to Sketch > Show Sketch Folder. The folder where your sketch is saved should open.
3) Inside that folder, create a new folder called data.
4) Inside the data folder is where you should put the files you want to be saved into the ESP8266 filesystem. As an example, create a .txt file with some text called test_example.
5) In the Arduino IDE, in the Tools menu, select the desired SPIFFS size (this will depend on the size of your files)
6) Then, to upload the files, in the Arduino IDE, you just need to go to Tools > ESP8266 Sketch Data Upload.
You should get a similar message on the debugging window. The files were successfully uploaded to the ESP8266 filesystem.
Testing the Uploader
Now, let’s just check if the file was actually saved into the ESP8266 filesystem. Simply upload the following code to your ESP8266 board.
/*********
Rui Santos
Complete project details at https://RandomNerdTutorials.com
*********/
#include "FS.h"
void setup() {
Serial.begin(115200);
if(!SPIFFS.begin()){
Serial.println("An Error has occurred while mounting SPIFFS");
return;
}
File file = SPIFFS.open("/test_example.txt", "r");
if(!file){
Serial.println("Failed to open file for reading");
return;
}
Serial.println();
Serial.println("File Content:");
while(file.available()){
Serial.write(file.read());
}
file.close();
}
void loop() {
}
After uploading, open the Serial Monitor at a baud rate of 115200. Press the ESP8266 “RST” button. It should print the content of your .txt file on the Serial Monitor.
You’ve successfully uploaded files to the ESP8266 filesystem using the plugin.
Wrapping Up
Using the filesystem uploader plugin is one of the easiest ways to upload files to the ESP8266 filesystem. You can save HTML and CSS files to build a web server, images or small icons, save configuration files, etc…
We have a project example in which we build a web server using HTML and CSS files saved on the filesystem. The example is for the ESP32, but it should be compatible with the ESP8266 with small changes on the code.
If you like the ESP8266, you may like the following resources:
- Home Automation using ESP8266
- ESP8266 DHT11 Temperature and Humidity Web Server
- ESP8266 Web Server Control Outputs
- ESP8266 GPIO Reference Guide
- More ESP8266 resources
Thanks for reading
doesnt work 🙁
Hi.
What do you mean? What is not working?
Regards,
Sara
Olá Sara, o meu apresentou erro no Python, porém o mesmo está instalado e funcionando.
Pode-me dizer qual é o erro que está a tert?
Pode-me dizer qual é o erro que está a ter?
Hello Sara,
Target: Sparkfun ESP8255 Thing,
Empty sketch => test.ino
Data: test.txt (in dir data) => Dit is een test…
IDE: Arduino 1.8.10
ESP8266FS-0.4.0
esptool write_flash: error: argument : Must be pairs of an address and the binary filename to write there
Can you help me?
Thanks and regards…
Same problem. Did you find a solution??
The problem lies in the combination of the board esp8266 by ESP8266 Community version 2.6.1 and ESP8266FS-0.4.0.
Go back to version 2.6.0 and it works.
Regards…
Thanks for the solution….
I don’t see a “programs” folder under documents. Using Windows 10
I do see this: C:\Program Files (x86)\Arduino\tools, should I decompress to there?
I keep getting an error about Python not being installed:
[SPIFFS] python : python3.exe
[SPIFFS] uploader : C:\Users\Brian Kenney\AppData\Local\Arduino15\packages\esp8266\hardware\esp8266\2.5.2\tools\upload.py
Python was not found but can be installed from the Microsoft Store: https://go.microsoft.com/fwlink?linkID=2082640SPIFFS Upload failed!
I just installed Python for that reason, even though I wasn’t aware that I needed it. Do I need Python? Anyway, it’s looking in a different place than you I believe.
i had the Pythgon error aswell.
Use ESP8266FS version 0.5.0, together with the ESP8266 version 2.60 board add-on. All older or newer version combinations didn’t work for me aswell. like Jeroen mentioned
How can i install this in Arduino IDE for Ubuntu Linux?
Hi Jose.
You can follow these instructions: https://github.com/esp8266/arduino-esp8266fs-plugin#installation
Regards,
Sara
Excellent tuto! I’m learning new stuff every day.
I’m working on a project where I have to send data of a sensor to a server through FTP once a day. Then, data are processed by a php script, which add it to a database and display it into a webpage.
First, I was thinking using a Mega2560 with a ESP01, but the more I read your tutorials, the more I think I’m going in the wrong direction.
1. Do you think an esp8266-NodeMCU would be enough for this kind of project (without the Mega2560)?
2. Can you upload files on a ESP-01, similarly as the NodeMCU?
3. Can you upload files (including the arduino) from anywhere if you need let’s say to change 1 parameter in your file, or do you have to be next to it?
4. Have you ever work on such a project?
Thank you so much in advance for your help
Hi.
You don’t need to use an Arduino Mega. You can simply use an ESP-01 or an ESP8266 NodeMCU. Usually the NodeMCU is more practical to work with because it is easier to upload code, apply power and it has more GPIOs if you want to connect sensors and peripherals. You can read our comparison guide: https://makeradvisor.com/best-esp8266-wi-fi-development-board/
You can upload code to the ESP-01 and to the ESP8266 using Arduino IDE: https://randomnerdtutorials.com/how-to-install-esp8266-board-arduino-ide/
If you want to upload files, you can use SPIFFS with both boards. (Note that some people reported problems using SPIFFS with some ESP-01 boards)
If you need to change the code, you can use OTA updates or Web OTA.
We have some projects that use PHP and database. See these projects (compatible with ESP8266):
https://randomnerdtutorials.com/cloud-weather-station-esp32-esp8266/
https://randomnerdtutorials.com/visualize-esp32-esp8266-sensor-readings-from-anywhere/
https://randomnerdtutorials.com/esp32-esp8266-mysql-database-php/
I hope this helps.
Regards,
Sara
It helps a lot!
Thank you very much
I also had problems with using SPIFFS on my ESP-01(s).
But I managed by using ESP8266FS version 0.5.0, together with the ESP8266 version 2.60 board add-on. All older or newer version combinations didn’t work for me.
And uploading the sketch was for me only possible with connecting the GPIO0 to the GRD. Testing was only possible with disconnecting the GPIO0 from the GRD.
“But I managed by using ESP8266FS version 0.5.0, together with the ESP8266 version 2.60 board add-on. All older or newer version combinations didn’t work for me.”
Thank you, i just had the same Problem
Hey Rui&Sara,
I just updated the IDE in the middle of a project TO 1.8.12 (Yeah I know, dumb). When I went to upload to spiffs, I found the menu didn’t have the necessary item. Then my old brain remembered it had to be installed, BUT, when I wen’t to Iger’s github I see there is an update that is designed to support Python 3.0. In addition following your instructions for adding the feature, the file structure doesn’t add up. I seem to remember a change in that around IDE 1.18.10 or there abouts. So now I’m not sure how to install it. Any help would be greatly appreciated. Thanks
Hi John.
I think you need to have Python 3 installed.
Regards,
Sara
Hello everybody,
I did everything as described here. However, I do not see the SPIFFS size in the tool menu but still the FS OTA as flash size.
Does anyone have a solution for me?
Regards Michael
Thanks a lot for the tutorial!
Just a small tip. I spent some hours unable to make the Sketch Data Upload.
I was getting an error saying “resource busy”.
Eventually, I found out that while doing the Sketch Data Upload, I must have the Serial Monitor closed.
Now it’s working.
Thanks for the tip!
Thank you Joan. You saved my bacon.
Everything goes as it is except the content doesn’t show up. What to do?
Hi.
What do you mean?
The content of the file?
Regards,
Sara
Hi,
When I use ‘ESP8266 Sketch Upload’ I get a message that ‘SPIFFS Image Uploaded’. But it doesn’t actually upload. The previously uploaded program continues to run. What should I do?
Hi.
Try erasing the ESP8266 flash and try again.
Regards,
Sara
I tried erasing it. I tried all combinations of tool version 4.0 and 5.0 and board version 2.60 and 2.74 with restarting in between. At best I get ‘SPIFFS Image Uploaded’ but it doesn’t actually upload. Any ideas?
I get the same problem too. It says SPIFF image uploaded, but I cannot read the file after uploading. I am not evens sure that the file is there or not. Sam please help me out if you had found the solution.
Hello Sara, Day one for me using an ESP8266. I installed the file system uploader and was able to upload a one line test file and I see its content using your sketch to read and serial.print the contents. Now I need to lean how to delete files no longer needed to free up space. I have been googling for it and not yet found how to do it. Can you tell me how you do that?
Thank you for your time, help and all the great information you provide.
Hi.
You can use the SD card functions: https://github.com/espressif/arduino-esp32/blob/master/libraries/SD/examples/SD_Test/SD_Test.ino
When calling the functions, instead of passing SD as argument, pass SPIFFS.
I hope this helps.
Regards,
Sara
Hi Sara-Rui,
I have installed ESP8266LittleFS-2.5.1.zip in the following directory on the Mac:
/Users/carles/Documents/Arduino/tools/ESP8266LittleFS/tool/esp8266littlefs.jar.
I have the following option in the tool menu:
ESP8266 LittleFS Data Ulpoad
When I upload the document I get the following error:
Arduino:1.8.13 (Mac OS X), Tarjeta:”NodeMCU 1.0 (ESP-12E Module), 80 MHz, Flash, Legacy (new can return nullptr), All SSL ciphers (most compatible), 4MB (FS:1MB OTA:~1019KB), 2, v2 Lower Memory, Disabled, None, Only Sketch, 921600″
[LittleFS] data : /var/folders/w6/rbt_v68j0xj28wrd4d7pmm6w0000gn/T/untitled509538315.tmp/sketch_jan23a/data
[LittleFS] size : 1000
[LittleFS] page : 256
[LittleFS] block : 8192
/text.txt
[LittleFS] upload : /var/folders/w6/rbt_v68j0xj28wrd4d7pmm6w0000gn/T/arduino_build_243359/sketch_jan23a.mklittlefs.bin
[LittleFS] address : 0x300000
[LittleFS] reset : –before default_reset –after hard_reset
[LittleFS] port : /dev/cu.SLAB_USBtoUART
[LittleFS] speed : 921600
[SPIFFS] python : python
[SPIFFS] uploader : /Users/carles/Library/Arduino15/packages/esp8266/hardware/esp8266/2.7.4/tools/upload.py
usage: esptool [-h] [–chip {auto,esp8266,esp32}] [–port PORT] [–baud BAUD]
[–before {default_reset,no_reset,no_reset_no_sync}]
[–after {hard_reset,soft_reset,no_reset}] [–no-stub]
[–trace] [–override-vddsdio [{1.8V,1.9V,OFF}]]
{load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,chip_id,flash_id,read_flash_status,write_flash_status,read_flash,verify_flash,erase_flash,erase_region,version}
…
esptool: error: unrecognized arguments: –end
LittleFS Upload failed!
Any solution to this problem?
I left it out in the initial post.
The two LittleFS examples, LittleFS_Timestamp and SpeedTest, work correctly.
Fixed. I found a newer version
I thank you very much.
If you can’t do it from esp01, you can add https://dl.espressif.com/dl/package_esp32_index.json, http://arduino.esp8266.com/stable/package_esp8266com_index.json
to your preferences and install the latest version of esp8266 from the board manager.
Also esp8266fs.To insert jar, you can unpack the .zip file and place the ESP8266FS folder inside C:\Program Files (x86)\Arduino\tools.
SPIFFS has been downgraded/not used (IDE 1.8.15). Use LittleFS instead (#include LittleFS.h> and change all ocurrences of SPIFFS to LittleFS
Hi.
SPIFFS still works, but it is recommended to use LittleFS: https://randomnerdtutorials.com/install-esp8266-nodemcu-littlefs-arduino/
Regards,
Sara
Hi I’m Ger from the Netherlands with a question: I’m working on the project and it’s a nice learning project, but why do I still have to load many libraries and is it not possible to do this in one go. For example, I am talking about avr/io.h, avr/interrupt.h,
avr/power.h, avr/pgmspace.h, util/twi.h, and more.
Thanks for an answer, greetings Ger
Hi.
I’m sorry, but I didn’t understand your question.
What project are you currently running and what issue are you having?
Regards,
Sara
Hi Sara, my apologies for the unclear response. It is about the project “ESP8266 MPU6050 Web Server Accelerometer and Gyroscope Dashboard with 3D Animation (SSE Events)”. As I said a nice learning project for many of us. I myself work with RPI and Python and wanted to shift my mind to Arduino. That works nicely but is a bit slower, but nice projects. My question about the project is that I have the web server running but the html, json, css won’t work. Now I first uploaded files to arduino with SPIFFS because I thought the ESP32 was equal to the ESP8266 but it turned out not to be. Now in the file I use #include <LittleFS.h>, should I upload with LittleFS as well?
I hope you can give me some explanation as to why I am getting a blank webpage from the web server.
many thanks and greetings
Ger
Hi Sara, I have now uploaded with LittleFS and found a bug in the html script when calling the https://cdnjs in lines 16 and 51. It works now but is very slow. If I build a refresh in the html it works but in between the 3d jumps to 0.
Do you know a solution for this? I may be asking a lot, but Arduino C+ is still unknown to me.
thanks in advance,
Ger
To maybe save somebody some time, the new Arduino IDE 2.0 does not support loadable tools. So you can’t use that version of the IDE with the Filesystem Uploader – you won’t be able to load files to your ESP8266.
See https://forum.arduino.cc/t/tools-for-arduino-ide-2-0-beta/894962 for details.
I did everything as described here. However, I do not see the SPIFFS size in the tool menu but still the FS OTA as flash size.
Does anyone have a solution for me?
Same problem…
Hi.
For the ESP8266, you should use LittleFS instead of SPIFFS. You can follow this tutorial to install the plugin: https://randomnerdtutorials.com/install-esp8266-nodemcu-littlefs-arduino/
Then, you can use all the sketches that use SPIFFS, you only need to replace the word SPIFFS with LittleFS.
I hope this helps.
Regards,
Sara
I’ve attempted another of your tutorials using what I now know is an ESP8266EX – I uploaded the text file using the ESP8266 uploader…then it gives another code to upload but I’m unsure where or with what it just says upload. Well every way I’ve tried has lead in the file not being able to read the text file. I’ve bought chip after chip and still getting the same issues. PLEASE HELP ME.
Hi.
You need to provide more details about the specific code you uploaded and the errors that you get.
Regards,
Sara