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!
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?
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