We have had several entries in the series dedicated to the ESP8266 and the ESP32 functioning as a server. But now it’s time to start delving into its true potential by looking at the SPIFFS file system.
In previous entries we have seen how to configure a basic server, how to serve dynamic content, how to distinguish types of requests and parameters, and how to serve files from Flash memory to reduce RAM consumption.
We had already said that the above makes sense when we are serving dynamic or “pseudo-dynamic” content, such as when we make an API. But to serve exclusively static content we have the SPIFFS file system.
In reality, we should talk about file systems, in the plural, since, in addition to SPIFFS, there is LittleFS. However, the latter has appeared much more recently, and many libraries are still not compatible. So for now we will focus on SPIFFS, and we will talk about LittleFS in its own entry.
What is SPIFFS?
SPIFFS (SPI Flash File System) is a file system designed to work on flash memories connected by SPI in embedded devices and with a small amount of RAM, such as the ESP8266 and the ESP32.
For this reason, it has certain “simplifications” compared to a file system that we are accustomed to. For example, SPIFFS does not support directories, although in practice it often manages to make the difference unnoticeable.
Thus, creating a file myDir/myFile.txt will create a file with that name, instead of a file myFile.txt inside the directory myDir. When listing the files in a directory, basically, the SPIFFS system “filters” the files whose path starts with the desired directory.
Another important limitation is that the maximum length of a path is 31 characters, including directory, subdirectories, ’/’, file name, and extension. This is a very short path, so keep that in mind when naming your files.
How to configure Arduino IDE to work with ESP8266 SPIFFS
We can modify the Arduino IDE to support the SPIFFS system of the ESP8266 easily by installing the ESP8266 FS plugin for Arduino.
First, we download the latest available version of the plugin from the following link for ESP8266 or from this link for ESP32.
Next, we extract the contents (esp8266fs.jar) into the following folder in the Arduino IDE
- Linux/Mac: ~/Arduino/tools/
- Windows: C:\Users\YOURUSERNAME\Documents\Arduino\tools/
So the installation of the plugin would look something like this,
Using the ESP8266 FS plugin
We start the Arduino environment, and we will see that we have a new option available.
To use it, as usual, we must first make sure that we have the board and the port correctly chosen.
On the other hand, in boards with ESP8266, we have an option with several combinations between memory space and SPIFFS. In order for SPIFFS to work, logically, we must choose a combination that has more file space than we are going to use (in particular, if you use zero, you cannot use it).
To use the plugin we must create a folder called ‘data’ within the folder where the Sketch is located with the program of the ESP8266. You will see that this folder is common in most ESP8266 projects.
Finally, when using the ‘ESP8266 Sketch Data Upload’ command the contents of the ‘data’ folder will be uploaded to the SPIFFS memory, deleting everything that was previously there.
Details of the FS.h library
To work with SPIFFS files, the ESP8266 has the ‘FS.h’ library that we can include in our programs. This library contains interesting objects and functions for file management in SPIFFS. It is worth taking a look at its code, but here is a brief summary.
Structure FSInfo64
The directory object represents a directory in SPIFFS, and has the following properties.
struct FSInfo64 {
uint64_t totalBytes;
uint64_t usedBytes;
size_t blockSize;
size_t pageSize;
size_t maxOpenFiles;
size_t maxPathLength;
};Directory Class
The Directory object represents a directory in SPIFFS, and has the properties of FSInfo64 and the following functions.
// iterates over files in directory
bool next();
bool rewind();
// actions over current item
File openFile(const char* mode);
String fileName();
size_t fileSize();
bool isFile() const;
bool isDirectory() const;File Class
The File object represents a file in SPIFFS, and has the properties of FSInfo64 and the following functions.
// Print methods:
size_t write(uint8_t);
size_t write(const uint8_t *buf, size_t size);
// Stream methods
int available();
int read();
int peek();
void flush();
size_t readBytes(char *buffer, size_t length)
size_t read(uint8_t* buf, size_t size);
bool seek(uint32_t pos, SeekMode mode);
size_t position();
// file information
size_t size() const;
const char* name();
const char* fullName(); // Includes path
bool isFile();
bool isDirectory();
// close file
void close();FS.h Functions
The FS.h library provides the following functions for handling files and directories.
bool setConfig(const FSConfig &cfg);
bool begin(); // mount file system
void end(); // unmount file system
bool format(); // format file system
// return FSinfo structure with file system info
bool info(FSInfo& info); information
bool info64(FSInfo64& info);
// return true if a path exists
bool exists(const char* path);
bool exists(const String& path);
// open a file
// mode is a string specifying access mode. It can be one of “r”, “w”, “a”, “r+”, “w+”, “a+”
File open(const char* path, const char* mode); // open a file
File open(const String& path, const char* mode);
// delete file
bool remove(const char* path);
bool remove(const String& path);
// rename file
bool rename(const char* pathFrom, const char* pathTo);
bool rename(const String& pathFrom, const String& pathTo);
// open a directory
Dir openDir(const char* path);
Dir openDir(const String& path);
// Create a directory
bool mkdir(const char* path);
bool mkdir(const String& path);
// Delete a directory
bool rmdir(const char* path);
bool rmdir(const String& path);So far, the entry to present the SPIFFS file system on a SoC like the ESP8266. In the next entry we will learn to use the SPIFFS to serve static pages, which will (finally) open the doors of the ESP8266 as a server. See you soon!