ESP8266/Arduino: Playing around with the upcoming filesystem feature

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
Related:  ESP8266: Fixing extended ASCII issues in SSD1306 OLED library

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. 

Related:  ESP8266 Weather Station Preview Video


Now a beer! Did you like this post? It often takes me several hours of my free time to write one. If I was your neighbour would you offer me a beer for the hard work I did for you? The beauty is: beers can be teletransported with a painless donation using Paypal. A beer in a Swiss bar costs about USD $4.80. Or use this affiliate link if you order something on Banggood and I'll get a small kickback. Thank you!