ESP8266/Arduino: Playing around with the upcoming filesystem feature

Do you like this post? Writing posts, developing libraries and programming online font creators is actually hard work. I order most of my electronics from a Chinese website called Banggood. It is save and the items usually arrive in good quality. With every order you do there by following this link you are supporting the blog. Thank you!

I recently stumbled on a feature that hopefully soon will be integrated into the stable release of the ESP8266/Arduino environment: a file system interface.

Low-Level: EEPROM

Up until now and currently your best bet for data persistence in the stable release you could use the EEPROM interface to write and read your data so it would be available between reboots of the device. This persistence interface is pretty low-level: you have to define the range of the memory you want to use and then it’s all on you how to organize this stream of bytes. Of course, you could write yourself some code to write and read the data in a more accessible way but this is cumbersome and error-prone. Especially if the stored data has different formats, lets say one part is a JSON object and the next is HTML you have to create a table of content (TOC) and keep track of the sizes and start points of these blocks.


But why re-invent the wheel? This organization of all the single blocks in a TOC is generally called a file system and the team around the ESP8266/Arduino environment is currently integrating the SPIFFS into their development branch. SPIFFS stands for SPI flash file system and is especially targeted for embedded devices such as the ESP8266. According to the Github page of the SPIFFS project the file system has the following features:

  •  Specifically designed for low ram usage
  •  Uses statically sized ram buffers, independent of number of files
  •  Posix-like api: open, close, read, write, seek, stat, etc
  •  Implements static wear leveling
  •  Built in file system consistency checks

There are also a few limitations but hey, what do you expect from anything especially targeted for small and embedded devices?



I couldn’t resist and wanted to try out this new feature. As a preparation you’ll have to install the staging version of the ESP8266/Arduino environment (as the time of writing – 2015-08-16 the stable version does not include this feature yet). To do that follow the instructions on the following link and use the reference to the staging version instead of stable:
Once you have done that you should be able to run the following code:
#include "FS.h"

void setup() {

  // always use this to "mount" the filesystem
  bool result = SPIFFS.begin();
  Serial.println("SPIFFS opened: " + result);

  // this opens the file "f.txt" in read-mode
  File f ="/f.txt", "r");
  if (!f) {
    Serial.println("File doesn't exist yet. Creating it");

    // open the file in write mode
    File f ="/f.txt", "w");
    if (!f) {
      Serial.println("file creation failed");
    // now write two lines in key/value style with  end-of-line characters
  } else {
    // we could open the file
    while(f.available()) {
      //Lets read line by line from the file
      String line = f.readStringUntil('n');


void loop() {
  // nothing to do for now, this is just a simple test


You can also find the example here:


The above code tries first to open a file called f.txt. If this succeeds it will read from it line by line and print the result to the serial console. If it cannot open the file it probably doesn’t exist yet. The code will then create the file and fill it with some imaginary key/value pairs, one pair per line.


While other ESP8266 firmwares (NodeMCU, smart.js and frankenstein) already come with a filesystem it is great to see that the Arduino/ESP8266 environment soon will be blessed with this important feature. It is easy to apply and a huge improvement over the very low-level EEPROM persistence interface. Directories let you structure your files and you can freely create new files, delete or rename them.
Compared to the NodeMCU firmware you have worry how you can get the files onto the device. If you want to run a web server you cannot just transfer the html, css and js files from your PC to the ESP8266. There is no interface for such an operation yet. But you could store them on another webserver and store/update them in flash when the device connects to WiFi.



Posted by squix78


  1. Thanks for the information and sample code. I tested it out on the latest version of Arduino and it failed, could not find the includes for "FS.h". I looked in the libraries and they were not there, so I manually loaded them and it failed on the "file.close();" the error is "file" was not declared in this scope. So i figured for testing I did not need to close the file. The code works! If you have any ideas on how to fix the file.close()?

Leave a Reply