ESP32 Arduino: List all files in the SPIFFS file system

In this tutorial we will check how to list all the files on the SPIFFS file system of the ESP32, using the Arduino core. The tests were performed using a DFRobot’s ESP32 module integrated in a ESP32 development board.

Introduction

In this tutorial we will check how to list all the files on the SPIFFS file system of the ESP32, using the Arduino core.

For an introductory tutorial on how to write a file to the SPIFFS file system, please check here. You can also read more about SPIFFS here.

For this tutorial we are going to use this Arduino IDE plugin, which allows us to upload files to the SPIFFS file system. You can check a tutorial on how to use it here.

One important thing to consider about SPIFFS is that it does not support directories [1][2]. Thus, it means that if we create a file with the path “/dir/test.txt“, it will actually create a file with name “/dir/test.txt” instead of a file called “test.txt” inside a “/dir” folder.

So, when using the Arduino IDE SPIFFS plugin, if we create files inside folders, they will be uploaded but their name will correspond to their full path inside the sketch data folder.

Another important point to consider is that the filename can only have a maximum of 31 characters [3]. Thus, since the full path will be used as the name of the file in the SPIFFS file system, we need to be careful to avoid exceeding this limit.

The tests were performed using a DFRobot’s ESP32 module integrated in a ESP32 development board.

The folder structure

In order to test the listing of the files in the whole SPIFFS file system, we are going to use the already mentioned Arduino IDE plugin to upload some files to our ESP32. To test multiple use cases, we are going to create some folders and files to cover some different use cases.

The folder structure we are going to use is the one shown below. Folders are represented in green and files in blue.

|– emptyFolder
|– folder1
|– — other_file.txt
|– — nested
|– — — nested.txt
|– folder2
|– — some_file.txt
|– file.txt

Note that, as already covered in the previous tutorial, the files to be uploaded with the plugin need to be placed in a data folder inside the folder of the Arduino sketch that we are using. So, you should create the previous folder structure inside the Arduino sketch data folder.

Since we only want to list the file names, you don’t need to write any actual content inside the files.

As mentioned before in the introductory section, the SPIFFS file system only contains files and not directories. So, the emptyFolder that we have in our folder hierarchy should not exist in our file system after the upload.

For the files, we expect to obtain the following names, which contain their whole paths:

• /file.txt
• /folder1/nested/nested.txt
• /folder1/other_file.txt
• /folder2/some_file.txt

After finishing the creation of the previous folder structure inside the data folder of your Arduino sketch, simply upload it to your ESP32 using the Arduino IDE plugin.

The code

We will start our code by including the SPIFFS.h library, so we have access to the file system related functionalities. In particular, we will have access to the SPIFFS extern variable, which we will use to interact with the file system.

#include "SPIFFS.h"

Moving on to the Arduino setup, where we will write the rest of the code, we will start by opening a serial connection. It will be used to later output the name of the files found in the file system.

Serial.begin(115200);

Then, we will need to mount the file system, before we can start using it.

if (!SPIFFS.begin(true)) {
    Serial.println("An Error has occurred while mounting SPIFFS");
    return;
}

After this, we will call the open method on the SPIFFS extern variable, passing as input a string with the root path “/“. This will return a File object, even though there is no file with this name on the file system.

This object will represent the root directory and we can use it to loop across all the files of the file system that belong to this “directory”.

Note however that, as mentioned before, directories don’t actually exist in SPIFFS, only files. So, we will obtain all the files currently on the file system starting by “/”, regardless of how many other “/” characters exist in their names (simulating nested folders).

File root = SPIFFS.open("/");

After this, we will obtain the first file in the SPIFFS file system with a call to the openNextFile method on our root directory File object. This will return another File object, now representing an actual file.

File file = root.openNextFile();

Then, we will enter in a loop where we will print the name of the file and then call the openNextFile method again, until there are no more files in the file system.

Note that the File class overloads the C++ Boolean operator, which means that we can use the actual File object as stopping condition of our loop.

while(file){

      Serial.print("FILE: ");
      Serial.println(file.name());

      file = root.openNextFile();
}

The final code can be seen below.

#include "SPIFFS.h"

void setup() {

  Serial.begin(115200);

  if (!SPIFFS.begin(true)) {
    Serial.println("An Error has occurred while mounting SPIFFS");
    return;
  }

  File root = SPIFFS.open("/");

  File file = root.openNextFile();

  while(file){

      Serial.print("FILE: ");
      Serial.println(file.name());

      file = root.openNextFile();
  }
}

void loop() {}

Testing the code

To test the code, simply compile and upload it to your ESP32, assuming that you have already uploaded all the files with the Arduino IDE SPIFFS plugin.

Once the procedure finishes, you should see a result similar to figure 1. As can be seen, all the 4 files we had in our folders are shown and their names correspond to their original full path. There aren’t any folders listed, as expected.

Figure 1 – Listing all files in the ESP32 SPIFFS file system.

References

[1] https://github.com/pellepl/spiffs

[2] https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/storage/spiffs.html

[3] https://github.com/espressif/arduino-esp32/issues/1820