ESP8266 Sming – Accessing files in SPIFFs filesytem

This short post is just to document some functions of the file system API when using the Sming framework. The Sming framework has a simple API to access the SPIFF file system for opening, reading/writing and deleting files.

The file system can be used for holding web server files, configuration files, log files, anything that needs a file system…

So my quick notes:

Files at flashing time
As I notice in Sming – How to Start we can, at flash time of the firmware, to add files in the Spiffs file system. The only thing needed is to create a sub-drectory, add the files there and then refer the directory on the For a directory named files:


Also it seems that on the latest version, this directory is detected if exists, and if so, the file system is created.

One important thing is to use this version of the spiffy tool that comes with the release of Sming from Sming Hub. Just go to the /opt/Sming/Sming/spiffy directory and execute make to build and make available the spiffy binary. Other option is when building Sming libraries just execute make followed by make spiffy on /opt/Sming/Sming.
Don’t use spiffy from other sources as I previously was using. Otherwise it won’t work.

Using the Spiffs file system
If your application uses the Spiffy file system it must now must explicitly mount the file system at run time:

void init() {


If the file system is not mounted we will get an error -10024 that means the SPIFFs file system is not available/configured…

Listing files
At the application level we can list the contents of the SPIFFs file system with the following function:

void listFileSystem() {
    Vector filelist = fileList();
    Serial.println(" ")  ;
    Serial.println("Spiffs file system contents ");
    for ( int i = 0 ; i < filelist.count() ; i++ ) {
        Serial.print(" ");
        Serial.println(filelist.get(i) + " (" + String( fileGetSize(filelist.get(i))) + ")"     );

We can see here the fileList() function that returns a Vector of Strings with the available list of files. We can then get the file size of a file with the fileGetSize( filename ) function.

We don’t need to do nothing to start using these functions right away, except the inclusion of SmingCore.h.

Error List
Before going further, we need to know the meaning of the errors that the file system functions may return.
These errors are described here: spiffs.h
We can see if trying to open a file we get -10002 it means that the file was not found, or for another example, -10021 we are trying to write into a file open in read mode.

File Flags
The file flags are flags passed to fileOpen() API call to open files.

At least one of the following three MUST be present:

  • eFO_ReadOnly  – Opens the file in READ ONLY mode
  • eFO_WriteOnly   – Opens the file in WRITE ONLY mode
  • eFO_ReadWrite  – Opens the file for reading and writing.

The remaining flags can be associated to change the fileOpen behaviour. For example:

  file_t fh = fileOpen("config.json", eFO_ReadOnly)

The variable fh, if positive holds the file handle to be used by other functions for accessing/manipulating the opened file.
If negative, it holds the error, for example -10002, the file doesn’t exist.

So this flags:

  • eFO_CreateIfNotExist – If the file doesn’t exist it creates it.
  • eFO_Truncate – Before opening the file, it resets its contents to nothing.
  • eFO_CreateNewAlways – Identical it seems to the above, but first it deletes the file. It seems a bug workaround
  • eFO_Append – Opens the file and moves the file pointer to the end of the file.

With the above flags we can do this:

   file_t fh = fileOpen("config.json", eFO_ReadWrite | eFO_CreateIfNotExist  );

In this case if the file doesn’t exist, it is created and no error is returned.

Another set of flags exist for the seek operation where we can seek from the start, current position or the file end:

  • eSO_FileStart – The seek offset is from the file start position (0).
  • eSO_CurrentPos – The seek offset is from the current file pointer position.
  • eSO_FileEnd – The seek offset is from the end of the file.

File operations
So the with the above information, using the SPIFFs file system has the same logic as in other language and platforms: open, read/write, close:

        char data[20] = "" ;
        file_t f = fileOpen("teste.json", eFO_ReadWrite | eFO_CreateIfNotExist );
        if ( f > 0  ){
            // Let's write
            fileWrite( f , "ola", 3 );
            // Let's return to the beginning of the file
            fileSeek ( f , 0 , eSO_FileStart );
            // Let's read what we have written.
            int br = fileRead ( f , &data , 3);   // br holds the bytes read.
            // Let's close the file.
        } else {
            Serial.println("Couldn't create file");

Other functions
The API offers other functions, that in a IDE like NetBeans can be seen at code completion.
Worth mention are the setContent() function where all the logic above is done internally, for example:

  setContent("log.txt", "System started");

The above instruction creates and writes on the log.txt file the content “System Started”.

There are other functions, like fileRename(), fileDelete(), getContent() that allow a quick and easy way to use the flash file system on the ESP8266 using the Sming framework.


3 thoughts on “ESP8266 Sming – Accessing files in SPIFFs filesytem

  1. What versions of Sming and the Espressif SDK are you using?

    I’m a fan of Sming and have been using it for months. I had a bit of trouble with the Spiffy file system working when it first came out, so I haven’t tried it since.

    • Hi. I’m using the latest version pulled from GitHub for Sming and for the esp-open-sdk. For me the latest versions works fine
      Also regarding spiffy, only the version that works fine for me is this: the one provided with Sming itself. See the spiffy sub-directory.

      We must use this spiffy version to build the filesystem. Using this version the file system API works as it should. If you use other versions (available at Github) the most common error is the file not found. I think it has something to do with some spiffy file system offset.

    • Hi! I’ve corrected the post for using the latest Sming version from SmingHub. I’ve tested and the above examples work fine.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s