The ESP32 contains a Serial Peripheral Interface Flash File System (SPIFFS). SPIFFS is a lightweight filesystem created for microcontrollers with a flash chip, which are connected by SPI bus, like the ESP32 flash memory. In this article we’re going to show how to easily upload files to the ESP32 filesystem using a plugin for Arduino IDE.
Note: if you have an ESP8266 board, read Install ESP8266 Filesystem Uploader in Arduino IDE.
Introducing SPIFFS
SPIFFS lets 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. At the time of writing this post, SPIFFS doesn’t support directories, so everything is saved on a flat structure.
Using SPIFFS with the ESP32 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 a separated file and save them on the ESP32 filesystem. Check the following tutorial to learn how to build a web server with files stored on the ESP32 file system:
Installing the Arduino ESP32 Filesystem Uploader
You can create, save and write files to the ESP32 filesystem by writing the code yourself on the 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 ESP32 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 ESP32 add-on for the Arduino IDE. If you don’t, follow one of the following tutorials to install the add-on:
Follow the next steps to install the filesystem uploader:
1) Go to the releases page and click the ESP32FS-1.0.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/ESP32FS/tool/esp32fs.jar
4) Finally, restart your Arduino IDE.
To check if the plugin was successfully installed, open your Arduino IDE. Select your ESP32 board, go to Tools and check that you have the option “ESP32 Sketch Data Upload“.
Uploading Files using the Filesystem Uploader
To upload files to the ESP32 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 ESP32 filesystem. As an example, create a .txt file with some text called test_example.
5) Then, to upload the files, in the Arduino IDE, you just need to go to Tools > ESP32 Sketch Data Upload.
The uploader will overwrite anything you had already saved in the filesystem.
Note: in some ESP32 development boards you need to keep the ESP32 on-board “BOOT” button pressed while it’s uploading the files. When you see the “Connecting …….____……” message, you need to press the ESP32 on-board “BOOT” button.
When you see the message “SPIFFS Image Uploaded“, the files were successfully uploaded to the ESP32 filesystem.
Testing the Uploader
Now, let’s just check if the file was actually saved into the ESP32 filesystem. Simply upload the following code to your ESP32 board.
/*********
Rui Santos
Complete project details at https://randomnerdtutorials.com
*********/
#include "SPIFFS.h"
void setup() {
Serial.begin(115200);
if(!SPIFFS.begin(true)){
Serial.println("An Error has occurred while mounting SPIFFS");
return;
}
File file = SPIFFS.open("/test_example.txt");
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() {
}
After uploading, open the Serial Monitor at a baud rate of 115200. Press the ESP32 “ENABLE” button. It should print the content of your .txt file on the Serial Monitor.
You’ve successfully uploaded files to the ESP32 filesystem using the plugin.
Wrapping Up
Using the filesystem uploader plugin is one of the easiest ways to upload files to the ESP32 filesystem. Check the following project to see how to build a web server using HTML and CSS files stored on the filesystem: ESP32 Web Server using SPIFFS (SPI Flash File System).
For more projects with ESP32, check the following tutorials:
- Build an All-in-One ESP32 Weather Station Shield
- ESP32 Servo Motor Web Server
- Getting Started with ESP32 Bluetooth Low Energy (BLE)
- More ESP32 tutorials
This is an excerpt from our course: Learn ESP32 with Arduino IDE. If you like ESP32 and you want to learn more, we recommend enrolling in Learn ESP32 with Arduino IDE course.
You stated that “After uploading, open the Serial Monitor at a baud rate of 115200. Press the ESP32 “ENABLE” button.”
Just where is this ESP32 “ENABLE” button located?
My sketch does not show any of the test data from the text file. It does print out “File Content:”. But nothing elese.
And even when I deliberately rename the file in the sketch to something else, it does not tell me that “Failed to open file for reading” but still displays “File Content:” with nothing else.
I am using Arduino 1.8.5 on Windows 10
Hi Mark.
The following image shows where the EN button is located: https://i0.wp.com/randomnerdtutorials.com/wp-content/uploads/2018/10/esp32-EN-enable-button.jpg?w=608&ssl=1
Have you successfully uploaded the text file to the ESP32 by going to Tools > ESP32 Sketch Data Upload ? Did you get the “SPIFFS Image Uploaded” message?
Try this sketch that deals with files and see if everything is working well with files on your ESP32: https://github.com/espressif/arduino-esp32/blob/master/libraries/SD/examples/SD_Test/SD_Test.ino
It should create a file, read its content and then delete it.
for me, show this mensage:”SPIFFS Error: esptool not found!”
[ My Ide arduino : 1.8.7]
Hi Sandro.
To be honest, I don’t know why you are getting that error.
That situation was already pointed out on Github yesterday.
Let’s way and see if someone has the answer
https://github.com/espressif/arduino-esp32/issues/2339
Regards,
Sara
Version 0.1 had this problem in me too. Version 1.0 (ESP32FS-1.0.zip) worked great 🙂
instale la actualización para la tarjeta esp32 y ya debe funcionar
You must name the file same as it is displayed in the code, for example, in this code there is written:
File file = SPIFFS.open(“/test_example.txt”);
So you need to call the file as test_example or change the code to the name you want, of course adding .txt .
PD. Do not add the .txt on the file name, just create the file as a text file and name it as you want. The program will understand you are talking about a .txt file.
Boa tarde!
Será possível através dos SPIFFS controlar os GPIO do ESP32? Ou seja, eu quero gravar um ficheiro de configuração (formato json) onde indico que pinos desejo ler os dados de sensores do meu ESP32, quando ele arrancar vai ler esse ficheiro.
Cumprimentos,
Francisco Pinheiro
Ola Francisco.
Sim, é possível guardar ficheiros no SPIFFS.
Depois de a ESP32 arrancar tem de adicionar todo co código que lê os ficheiros e decide o que fazer.
Só para orientação, temos um tutorial que faz uma página web a partir de ficheiros no SPIFFs (não é relacionado com o que quer fazer, mas pode ajudar a perceber como funciona): https://randomnerdtutorials.com/esp32-web-server-spiffs-spi-flash-file-system/
Também pode ver este tutorial para ver como trabalhar com JSON em arduino IDE: https://randomnerdtutorials.com/decoding-and-encoding-json-with-arduino-or-esp8266/
Cumprimentos,
Sara
So far I haven’t been successful uploading additional files.
SPIFFS.open(“[FilePath]”) always returns true whether or not the file was uploaded.
SPIFFS.exists(“[FilePath]”) return false whether or not the file was included in the /data directory.
Specs
Mac OS 10.14.5
Arduino IDE 1.8.9
On an ESP32
Using Arduino IDE > Tools > Board > ESP32 Dev Module
Hi Carl.
I’ve never faced that issue.
Unfortunately, without further information, it is very difficult to understand what might be wrong.
If anyone knows a solution for this, please help.
Regards,
Sara
Hi: I’m trying to install ESP32 filesystem uploader into the Arduino IDE 1.8.5. I have the esp32fs.jar in this path: Macintosh HD ▸ Users ▸ richardromig ▸ Dropbox ▸ Arduino IDE 1.8.5 ▸ Tools ▸ ESP32FS ▸ tool but the option “ESP32 Sketch Data Upload“ does not appear in the IDE. I am running MacOS 10.14.6 Any suggestions?
yes, I copied-pasted the file esp32fs.jar in creating some folders like this : Macintosh HD ▸ Utilisateurs ▸ MyName ▸ Documents ▸ Arduino ▸ tools ▸ ESP32FS ▸ tool ▸ esp32fs.jar and the option “ESP32 Sketch Data Upload“ appear in the IDE.
macOS Mojave 10.14.6
Very important for linux users! I create in data folder text file. Then I do same, but I dont see file content (nothing wrong, just dont see characters). Then I try to rename file to like this “test_example.txt”. And it works! In linux, mostly txt file is not txt file.
Thank you for sharing that info.
Regards,
Sara
Hi.
Richard , I had the same problem. But creating a Tools folder under the Sketch folder and placing the ESP32FS there did the trick.-Not the first time something like this comes up.
Hi,
great THX from Austria. Solved my problem 🙂
Thanks, I tried all of the other options mentioned and they didn’t work. Yours, however, did work. Many thanks. I’m migrating from Windows to Mac and things are a bit different. I also had to move by library folder into the sketches folder.
I had a problem when I installed the ESP32 filesystem uploader in a new tools folder where all my arduino archives are kept. It didn’t install properly.
However, it worked when I installed the uploader to Local Disk(c:), Program Files(x86), Arduino, tools folder.
Excellent.
Just make sure a data folder is in the same folder as your arduino code.
It works for txt files but do you have a tutorial on reading and displaying a jpg file?
I’ve solved this last problem. I can now read and display jpg file on web browser.
For those who had problem when uploading and got error code :
serial.serialutil.SerialException: could not open port ‘COM3’: WindowsError(5, ‘Access is denied.’)
Turn your serial monitor or plotter off. I hope it helps…
Source : Stupid mistake I made.
This is explained very well, thank you for the tutorial.
Will this work with an ESP8266 as well?
Hi.
Yes. Here’s the tutorial for ESP8266: https://randomnerdtutorials.com/install-esp8266-filesystem-uploader-arduino-ide/
Regards,
Sara
I am having zero luck with this.
I can upload the SPIFFS file the first time and then thereafter I get:
[SPIFFS] data : /Users/davidh/Documents/Arduino/spiffs-check/data
[SPIFFS] start : 2686976
[SPIFFS] size : 1472
[SPIFFS] page : 256
[SPIFFS] block : 4096
/test_example.txt
[SPIFFS] upload : /var/folders/n1/59y24n0j2z128fchsgxh1f5w0000gn/T/arduino_build_804785/spiffs-check.spiffs.bin
[SPIFFS] address: 2686976
[SPIFFS] port : /dev/cu.SLAB_USBtoUART
[SPIFFS] speed : 921600
[SPIFFS] mode : dio
[SPIFFS] freq : 80m
esptool.py v2.6
Serial port /dev/cu.SLAB_USBtoUART
Traceback (most recent call last):
File “esptool.py”, line 2959, in
File “esptool.py”, line 2952, in _main
File “esptool.py”, line 2652, in main
File “esptool.py”, line 222, in init
File “serial/init.py”, line 88, in serial_for_url
File “serial/serialposix.py”, line 268, in open
serial.serialutil.SerialException: [Errno 16] could not open port /dev/cu.SLAB_USBtoUART: [Errno 16] Resource busy: ‘/dev/cu.SLAB_USBtoUART’
Failed to execute script esptool
SPIFFS Upload failed!
If I restart the Arduino application it uploads. However running the SPIFFS read test program always comes up with failed to open file for reading.
So issues with upload and with reading.
Hi David.
Can you take a look at this discussion and see if it helps: https://rntlab.com/question/spiffs-error-esptool-not-found/
See Stéphane answer.
Regards,
Sara
I am not having much luck with the web servers using the SPIFF. I am using Arduino V1.8.13. When I try to include the .zip library ESP32FS-1.0 I always get the error message: “TTGO LoRa32-OLED V1, 80MHz, 921600, None”
“Specified folder/zip file does not contain a valid library”
I am wondering if the LoraESP32 board supports ESP32FS.
Thanks
Hi Brian.
Where are you trying to include the filesystem uploader?
It shouldn’t be in the project folder.
The data folder should be in the project folder.
You’re probably not installing the uploader plugin properly.
Regards,
Sara
1.) I download ESP32FS-1.0.zip
2.) In Arduino IDE, I go to: Sketch -> Include Library-> Add .zip Library
3.) I choose ESP32FS1.0.zip from my download folder.
4.) I get the following error message at the bottom of the IDE:
“Specified folder/zip file does not contain a valid library” with an orange background.
The newer versions of Arduino IDE do not have a Tool folder like the previous versions.
Should I maybe just unzip the ESP32FS-1.0.zip outside of the Arduino IDE and place the .jar file in a Tool folder that I create myself?
Many thanks for your help!
Hi Brian.
I don’t think it should be installed in that way. But you can try it.
I think you may need to install the Arduino version that comes with a .zip file: https://downloads.arduino.cc/arduino-1.8.13-windows.zip
And then, follow our instructions to install the filesystem.
Regards,
sara
Hello Sara,
Thank you very much for this tutorial and it worked well for me, but when I opened the serial monitor, after the sketch had been down loaded, it was blank. However, I realized that the text had been and gone before I opened the monitor and I just pressed the reset button on the ESP32 board and up came the text as you specified. I wonder is this would be of help to the gentleman who seemed to have similar problems.
I was so pleased that this worked for me as yesterday evening I had been trying for hours to try and get LittleFS working without success and I spotted your tutorial, like a life belt to a drowning man.
Kindest regards
Adrian
Hi.
Yes, that’s normal because the text is printed in the setup().
So, you need to press the RST button to be able to see it.
We have a tutorial about LittleFS with the ESP8266 with VSCode + PlatformIO: https://randomnerdtutorials.com/esp8266-nodemcu-vs-code-platformio-littlefs/
Regards,
Sara
Hi Rui and Sara,
A slight word of warning/note: The uploader will overwrite anything you had already saved in the filesystem. For me, not a big deal since it was just some test files for an ESP32-based shell/file editor I’ve been working on. But in a production environment where I might be saving config files and runtime data, this would be an issue.
You might wish to note this in the text of the tutorial (unless I missed it!!).
Steve
Yes, you are right.
Thanks for the warning.
I’ve added a note about that.
Regards,
Sara
For those who struggling on Mac.
Make a folder, “tools” inside Arduino directory.
Then, move downloaded folder to “tools” folder
Finally, you should change the the name of the folder from “ESP32FS 2” to “ESP32Fs”.
Now, you may find “ESP32 Sketch Data Upload” at the tools bar.
sorry the folder name should be changed to “ESP32FS”, not “ESP32Fs”.
Hi Rui et al,
Great project!
I’m quite new in the field, please help me out:
I’m getting the “expected unqualified-id before ‘<‘ token
” error while trying to compile the code, line 23 ().
Where should I dig?
Regards,
Th.
Hi.
that is a syntax error.
Double-check that you have copied the complete code and that you haven’t inserted any character by mistake.
Regards,
Sara