Place data in the flash memory of the ESP

Hello and welcome to today's post.

The ESP modules are very popular. We have shown in the past how easy it is to connect to the WLAN, display web pages, and switch relays.

However, a very useful feature is the ability to store data in the flash memory of the ESP. So it is possible to upload files that we can access later with our sketch. Or to store information that is still available after a reboot.

Upload files to the ESP

We need the tool "ESP8266FS" - an extension that integrates into the Arduino IDE. It adds the entry "ESP8266 Sketch Data Upload" in the "Tools" menu. 

First we download the tool from the ESP8266 GitHub page:

https://github.com/esp8266/arduino-esp8266fs-plugin/releases/download/0.1.3/ESP8266FS-0.1.3.zip

We now create a folder named "tools" in the same folder as our Arduino sketches. Normally this is located at "C:\Users\<username>\Documents\Arduino\".

Unzip the downloaded .zip file and copy the ESP8266FS folder into the "tools" directory. We will end up with "C:\Users\<username>\Documents\Arduino\tools\ESP8266FS\tool\esp8266fs.jar".

Now we restart the Arduino IDE, and make a new sketch. I call mine in this example "ESP-Data-Test". Now we have to save this sketch.

We now navigate to the newly created folder "C:\Users\<username>\Documents\Arduino\ESP-Data-Test" and create the folder "data" there. All files placed here will be uploaded to the flash memory of the ESP as soon as we do the upload. 

I create a new text file named test.txt, write a few lines of text in it, and save it to the new "data" folder.

I use one ESP8266-01S with USB adapter, so I set the following options under tools:

• Board: "Generic ESP8266 modules"
• Flash Size: "1m (64k Spiffs)
• Upload speed: "115200"
• Port: "Comx" - Select your COM port

If you don't know the memory size of your module, there is a tip at the end of the article how to determine it. 

As a test let's try to load the empty sketch (only void setup() and void loop()) to the ESP. For my ESP I have to make sure that the programming mode is activated.

If all this worked, we can try to upload the content of the "data" folder to the ESP. For this we go to "Tools" -> "ESP8266 Sketch Data Upload".

In the IDE appears "SPIFFS Uploading Image..." ... and after a short time appears: "SPIFFS Image Uploaded":

If you get an error at this point ("SPIFFS Upload failed!"), it is probably because the ESP is no longer in programming mode. Just disconnect and reconnect the USB connection, making sure that the programming mode is activated.

Use Spiffs in a sketch

To use SPIFFS in Sketch, we include the FS.h library:

#include "FS.h"

Now we have the following commands available:

File system object (Spiffs)

SPIFFS.begin()

Mounted the Spiffs file system. Must always be carried out before all other commands. Gives back "True" if the mounting worked, otherwise "false".

SPIFFS.format()

Formatted (deletes) the file system. Gives back "True" when the formatting was successful.

SPIFFS.open(path, mode)

Opens a file. As "path" they specify the file name including the absolute path (e.g. "/folder name/test.txt"). "mode" specifies the type of access. Can contain the following options: "r", "w", "a", "r+", "w+", "a+".

• "r" Opens the file for reading. The file must exist
• "w" Creates a new file without content. If a file with the same name exists, its content is deleted and the file is seen as a new empty file.
• "a" Appends data to the file. The data is appended to the end of the file. If the file does not exist, a new one is created.
• "r+" Opens a file for reading and writing. The file must exist.
• "w+" Creates an empty file for reading and writing.
• "a+" Opens a file for reading and appending.

SPIFFS.exists(path)

Gives back "True" if the path exists, otherwise "false".

SPIFFS.openDir(path)

Opens the specified directory. Gives back a "object".

SPIFFS.remove(path)

Deletes the specified path. Gives back a "true" if the deletion was successful.

SPIFFS.rename(pathFrom, pathTo)

Names a file to "Pathfrom" to "Pathto". The path must be absolutely. Gives back a "True" if the renaming was successful.

File system info structure

FSInfo fs_info;
SPIFFS.info(fs_info);

Fills the FSINFO structure with information about the file system. Gives a "True" back in the event of success, otherwise a "false".

Structure:

struct FSInfo {
  size_t totalBytes;
  size_t usedBytes;
  size_t blockSize;
  size_t pageSize;
  size_t maxOpenFiles;
  size_t maxPathLength;
};

Directory Object (Dir)

The "you" object enables us to address files within a directory using the "Next ()", "Filename ()" and "OpenFile (fashion)" methods.

Dir dir = SPIFFS.openDir("/data");
while (dir.next()) {
Serial.print(dir.fileName());
File f = dir.openFile("r");
Serial.println(f.size());
}

dir.next() is true as long as it finds files in the directory. It must be called before "fileName" or "openFile".

"openFile" takes the "mode" argument, which is identical to SPIFFS.open.

File Object (file)

SPIFFS.open and dir.openFile return a "file" object. This is a stream object and supports all functions like "readbytes", "findUntil", "parseInt", "println" and all other stream methods.

But there are also some that are specific to the file object.

file.seek(offset, mode)

Like the Fseek function in C. The current position shifts as follows depending on the value of "fashion":

• SeekSet -> Position is set on "Offset" bytes from the beginning
• SeekCur -> Current position is moved by "Offset" bytes
• SeekEnd -> Position on "Offset" bytes from the end of the file

file. position ()

Gives the current position within the file as a value in bytes

file.size ()

The file size in bytes is reflected.

file.name ();

Gives the file name again as "Const Char*". Can use "String Name = File.Name ();" be saved in a string.

file.close ()

Closes the file.

Practical example

Now we are writing a small sketch to test the whole thing: We want our text file "Test.txt" which we create at the beginning and filled with a few lines of text on the serial monitor.

#include "Fs.H" // Here we bind the required library

void set up() {
  Serial.Begin(9600); // activate serial output
  delay(1000); // short break so that we have time to open the serial monitor.
  
  Spiff.Begin(); // Mounten file system
  File F = Spiff.open( "/test.txt", "R"); // open file to read
  IF (!F) {
    Serial.print("File Open Failed");
  }
  String data = F.reapring(); // Content of the text file is read ...
  Serial.print("Content of the open file:");
  Serial.print(data); // ... and spent again
  F.close(); // We close the file
}
void loop() {
}

After uploading, the output appears on the serial monitor:

Bonus tip: How big is the flash memory of my ESP 8266?

Depending on which ESP8266 module you use, the size of the flash memory may differ. While you can look for the datasheet by the label on the chip, to be sure there is a small sketch that checks the size, speed and mode of your module. The sketch is available at https://github.com/esp8266/Arduino/tree/master/libraries/esp8266/examples/CheckFlashConfig

Simply upload this sketch and set the serial monitor to 115200 baud, the size of the chip is already displayed.

I hope you enjoyed today's blog post and that it inspired your creativity. From now on you can use the SPIFFS function of your ESP to store e.g. HTML text modules, permanently save sensor data, and much more.

We are very pleased about praise, criticism and suggestions to our blog.

Your Markus Neumann