ESP8266 NodeMCU with VS Code and PlatformIO: Upload Files to Filesystem (LittleFS)

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

ESP8266 NodeMCU with VS Code and PlatformIO IDE Upload Files to Filesystem LittleFS

If you’re using Arduino IDE follow this tutorial instead: Install ESP8266 Filesystem Uploader in Arduino IDE.

Introducing SPIFFS/LittleFS

There are two filesystems you can use for the onboard ESP8266 flash: SPIFFS and LittleFS.

SPIFFS and LittleFS let you access the flash memory like you would do in a normal filesystem in your computer, but simpler and more limited. You can read, write, close, and delete files.

SPIFFS:

  • original filesystem;
  • ideal for space and RAM constrained applications that use many files;
  • doesn’t support directories – everything is saved on a flat structure;
  • filesystem overhead on the flash is minimal;
  • SPIFFS is currently deprecated and may be removed in future releases of the core.

LittleFS:

  • recent;
  • focuses on higher performance;
  • supports directories;
  • higher filesystem and per-file overhead (4K minimum vs. SPIFFS’ 256 byte minimum file allocation unit).

For more information about SPIFFS and LittleFS, refer to the ESP8266 Arduino Core documentation.

SPIFFS is currently deprecated and may be removed in future releases of the ESP8266
core. It is recommended to use LittleFS instead.

LittleFS is under active development, supports directories, and is many times faster for most operations. The methods used for SPIFFS are compatible with LittleFS, so, we can simply use the expression LittleFS instead of SPIFFS when converting a code from SPIFFS to LittleFS.

For example, converting most applications from SPIFFS to LittleFS simply requires changing the SPIFFS.begin() to LittleFS.begin() and SPIFFS.open() to LittleFS.open().

Using the filesystem with the ESP8266 board is specially 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 ESP8266 NodeMCU LittleFS

The files you want to upload to the ESP8266 filesystem should be placed in a folder called data under the project folder. For you 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:

Using LittleFS as Default Filesystem

SPIFFS is currently deprecated and may be removed in future releases of the ESP8266 core. It is recommended to use LittleFS instead. LittleFS is under active development, supports directories, and is many times faster for most operations. So, 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 ESP826 platformio.ini configuration file.

board_build.filesystem = littlefs
Use LittleFS as default filesystem ESP8266 VS Code + PlatformIO

Creating a data Folder

Create a folder called data inside your project 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.

Create a data folder VS Code PlatformIO ESP8266

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.

Create files under data folder VS Code with PlatformIO ESP8266

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.

Create text file VS Code PlatformIO ESP8266

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 env:nodemcuv2 (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.
Upload Filesystem Image VS Code PlatformIO ESP8266

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.

Upload filesystem image ESP8266 VS Code PlatformIO success message

Troubleshooting

Here’s a common mistake:

Could not open port “COMX” Access is denied.

Upload filesystem image ESP32 VS Code PlatformIO Access Denied Error ESP8266

This error means that 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).

VS Code PlatformIO Close Terminal Window

Testing

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

/*********
  Rui Santos
  Complete project details at https://RandomNerdTutorials.com/esp8266-nodemcu-vs-code-platformio-littlefs/  
*********/

#include <Arduino.h>
#include "LittleFS.h"
 
void setup() {
  Serial.begin(9600);
  
  if(!LittleFS.begin()){
    Serial.println("An Error has occurred while mounting LittleFS");
    return;
  }
  
  File file = LittleFS.open("/text.txt", "r");
  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.

Reading File Content LittleFS ESP8266 VS Code PlatformIO

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

Wrapping Up

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

This can be specially useful to upload HTML, CSS and JavaScript files to build web server projects with the ESP8266 NodeMCU boards.

We have a similar tutorial for the ESP32: ESP32 with VS Code and PlatformIO: Upload Files to Filesystem (SPIFFS)

Learn more about the ESP8266 NodeMCU with our resources:



Build Web Server projects with the ESP32 and ESP8266 boards to control outputs and monitor sensors remotely. Learn HTML, CSS, JavaScript and client-server communication protocols DOWNLOAD »

Build Web Server projects with the ESP32 and ESP8266 boards to control outputs and monitor sensors remotely. Learn HTML, CSS, JavaScript and client-server communication protocols DOWNLOAD »


Enjoyed this project? Stay updated by subscribing our newsletter!

8 thoughts on “ESP8266 NodeMCU with VS Code and PlatformIO: Upload Files to Filesystem (LittleFS)”

  1. Exactly what I was looking for, thanks for covering this.

    Just a comment: in your test code, you seems to include:

    #include “LittleFS.h”

    I do not see it anywhere. Compiler complains about not finding it.
    Is it some external library you include?

    Reply
    • Hi.
      In didn’t need to include anything.
      Just make sure you have the right settings on the platformio.ini file.
      But, what is exactly the error that you get?
      Regards,
      Sara

      Reply
      • Thanks for your reply
        In vscode + pio, I get the include line highlighted with this message:

        “#include errors detected. Please update your includePath. ”

        and then at compilation time I get this error:

        “lib/filesystem/filesys.cpp:3:22: fatal error: LittleFS.h: No such file or directory”

        My platformio.ini, contains:

        [env:esp32doit-devkit-v1]
        platform = espressif32
        board = esp32doit-devkit-v1
        framework = arduino
        monitor_speed = 115200
        board_build.filesystem = littlefs
        lib_deps = me-no-dev/ESP Async [email protected]^1.2.3

        The code is working well with SPIFFS version…
        I’ll investigate a bit further but if you see where it could come from that would be helpful.
        Regards,

        Reply
  2. Thanks for your tutorial. I have some problem when I do this program. The step of “Uploading Filesystem Image”, I don’t understand how this work, what does the function do in here? And on the left, my “PROJECT TASKS” is empty, nothing here. This my first time do it, I need your help, thanks.

    Reply
    • Hi.
      That function uploads any files inside the data folder to the ESP8266 filesystem.

      Can you try the following?
      With your project opened in VS Code, go to View > Pallete.
      Then, write: >Refresh project tasks, and select that option.

      Then, check if the Platform Tasks to upload an image to the filesystem were updated.
      I hope this helps.
      Regards,
      Sara

      Reply
      • Thank you. But I write refresh test: refreshing tests, I don’t find refresh project tasks, and then it shows error (command ‘python.refreshingTests’ not found) and “No tree view with id ‘platformio-activitybar.projectTasks’ registered”, while checking the ant logo.

        Reply

Leave a Reply to Rafael Cancel reply

Download our Free eBooks and Resources

Get instant access to our FREE eBooks, Resources, and Exclusive Electronics Projects by entering your email address below.