ESP32 with VS Code and PlatformIO: Upload Files to LittleFS Filesystem

Learn how to upload files to the ESP32 LittleFS filesystem using VS Code with the PlatformIO IDE extension. Using the filesystem with the ESP32 can be useful to save .txt, HTML, CSS and JavaScript files to build a web server instead of having to write everything inside the Arduino sketch.

If you’re using Arduino IDE follow this tutorial instead: Arduino IDE 2: Install ESP32 LittleFS Uploader (Upload Files to the Filesystem)

Introducing LittleFS

LittleFS is a lightweight filesystem created for microcontrollers that lets you access the flash memory as you do in a standard file system on your computer, but it’s simpler and more limited. You can read, write, close, and delete files. Using LittleFS with the ESP32 boards is useful to:

• Create configuration files with settings;
• Save data permanently;
• Create files to save small amounts of data instead of using a microSD card;
• Save HTML, CSS, and JavaScript files to build a web server;
• Save images, figures, and icons;
• And much more.

Upload Files to ESP32 LittleFS

The files you want to upload to the ESP32 filesystem should be placed in a folder called data at the same level as the src folder in PlaformIO. To understand how everything works, we’ll upload a .txt file with some random text. You can upload any other file type.

If you’re not familiar with VS Code + PlatformIO IDE, follow the next tutorial first:

• Getting Started with VS Code and PlatformIO IDE for ESP32 and ESP8266

Using LittleFS as Default Filesystem

SPIFFS is currently deprecated and may be removed in future releases of the ESP32 core. It is recommended to use LittleFS instead. LittleFS is under active development, supports directories, and is many times faster for most operations. We’ll use LittleFS in this tutorial.

In VS Code + PlatformIO, when uploading files, we must specify that we want to use LittleFS filesystem instead of SPIFFS (default), so you need to add the following line to the ESP32 platformio.ini configuration file.

board_build.filesystem = littlefs

Creating a data Folder

Create a folder called data inside your project folder. It must be at the same level as the src folder. This can be done on VS Code.

With your mouse, select the project folder you’re working on. Click on the New Folder icon to create a new folder.

This new folder must be called data, otherwise, it won’t work.

Then, select the newly created data folder and create the files you want to upload by clicking on the New File icon. In this example, we’ll create a file called text.txt. You can create and upload any other file types like .html, .css or .js files, for example.

Write some random text inside that .txt file.

The data folder should be under the project folder and the files you want to upload should be inside the data folder. Otherwise, it won’t work.

Uploading Filesystem Image

After creating and saving the file or files you want to upload under the data folder, follow the next steps:

1. Click the PIO icon at the left side bar. The project tasks should open.
2. Select esp32doit-devkit-v1 (it may different depending on the board you’re using).
3. Expand the Platform menu.
4. Select Build Filesystem Image.
5. Finally, click Upload Filesystem Image.

Important: to upload the filesystem image successfully you must close all serial
connections (Serial Monitor) with your board.

After a while, you should get a success message.

Troubleshooting

Here’s a common mistake:

Could not open port “COMX” Access is denied.

This error means you have a serial connection opened with your board in VS Code or in any other program. Close any program that might be using the board serial port, and make sure you close all serial connections in VS Code (click on the recycle bin icon on the terminal console).

Testing

Now, let’s just check if the file was actually saved into the ESP32 LittleFS filesystem. Copy the following code to the main.cpp file and upload it to your board.

/*********
  Rui Santos & Sara Santos - Random Nerd Tutorials
  Complete project details at https://RandomNerdTutorials.com/esp32-vs-code-platformio-littlefs/
*********/

#include <Arduino.h>
#include "LittleFS.h"
 
void setup() {
  Serial.begin(9600);
  
  if(!LittleFS.begin(true)){
    Serial.println("An Error has occurred while mounting LittleFS");
    return;
  }
  
  File file = LittleFS.open("/text.txt");
  if(!file){
    Serial.println("Failed to open file for reading");
    return;
  }
  
  Serial.println("File Content:");
  while(file.available()){
    Serial.write(file.read());
  }
  file.close();
}
 
void loop() {

}

View raw code

You may need to change the following line depending on the name of your file.

File file = LittleFS.open("/text.txt");

Open the Serial Monitor and it should print the content of your file.

You’ve successfully uploaded files to the ESP32 filesystem (LittleFS) using VS Code + PlatformIO.

Wrapping Up

With this tutorial you’ve learned how to upload files to the ESP32 LittleFS filesystem (LittleFS) using VS Code + PlatformIO. It is quick and easy.

This can be useful to upload HTML, CSS, and JavaScript files to build web server projects with the ESP32 boards. If you prefer to use SPIFFS filesystem you can check this tutorial instead.

We have a similar tutorial for the ESP8266: ESP8266 NodeMCU with VS Code and PlatformIO: Upload Files to Filesystem (LittleFS)

Learn more about the ESP32 with our resources:

• Learn ESP32 with Arduino IDE (eBook)
• SMART HOME with Raspberry Pi, ESP32, and ESP8266 eBook
• Build Web Servers with ESP32 and ESP8266 eBook
• Free ESP32 Guides and Tutorials