How to Call lfs_dir_read in Arduino: A Step-by-Step Guide
Blog
Olivia Brown  

How to Call lfs_dir_read in Arduino: A Step-by-Step Guide

So, you’ve started playing with LittleFS on an Arduino and stumbled upon lfs_dir_read. This powerful function lets you read the contents of a directory, but using it properly requires a few steps. Don’t worry—we’ll break everything down into a simple, fun guide anyone can follow.

TL;DR

Want to get a list of files in a LittleFS directory? You’ll need to use lfs_dir_open, then lfs_dir_read, and finally lfs_dir_close. It might seem complicated at first, but it’s really just a set of small, easy steps. Arduino doesn’t support it directly, so you’ll be working a bit closer to the C library level. Still with us? Let’s go deeper!

📁 What’s lfs_dir_read Anyway?

lfs_dir_read is part of the LittleFS embedded filesystem. When you want to browse files on a filesystem, this is how you peek inside a folder. Think of it like opening a drawer and pulling out each item one by one.

This function returns information about the next file or folder in a directory. You keep calling it in a loop until you’ve seen everything. Then, you close the directory.

🔧 Things You’ll Need

  • Arduino board — Something like an ESP32 or STM32.
  • LittleFS source code — You’ll be including the littlefs.h and related files.
  • Courage — You’re about to work with low-level code! 😉

🧪 Step-by-Step Guide

1. Include LittleFS and Setup Variables

You’ll need some variables to keep track of the filesystem state. Add these to your sketch (or create a separate C file if doing this more seriously):

#include "lfs.h"

lfs_t lfs;
lfs_file_t file;
lfs_dir_t dir;
struct lfs_info info;

Now, define the configuration. It should match how your filesystem is mounted (this usually involves specifying block sizes and cache sizes). Arduino wrappers like ESP32’s LittleFS handle this for you, but if you’re doing it bare-metal or custom, you’ll need a full lfs_config structure.

2. Mount the Filesystem

Mounting lets you access files. First, initialize the config (not shown here for brevity), then:

int err = lfs_mount(&lfs, &cfg);
if (err) {
  // try formatting if mounting failed
  lfs_format(&lfs, &cfg);
  lfs_mount(&lfs, &cfg);
}

Once that’s done, you’re ready to explore directories!

3. Open a Directory

Let’s say you want to read the root directory /. Open it like this:

lfs_dir_open(&lfs, &dir, "/");

This directory handle will now be used in your reading loop.

4. Read Files with lfs_dir_read

This is the heart of the guide!

while (lfs_dir_read(&lfs, &dir, &info) > 0) {
    if (info.type == LFS_TYPE_REG) {
        Serial.print("File: ");
        Serial.println(info.name);
    } else if (info.type == LFS_TYPE_DIR) {
        Serial.print("Dir: ");
        Serial.println(info.name);
    }
}

Every time lfs_dir_read succeeds, it fills info with details: file name, type, etc.

Keep looping until the return value is zero. That means you’ve read it all.

5. Close the Directory

Always clean up!

lfs_dir_close(&lfs, &dir);

And you’re done browsing that directory.

📌 Notes and Common Pitfalls

  • Arduino IDE doesn’t provide lfs_dir_read by default.
  • You need to download and integrate LittleFS manually.
  • Configuration errors are the most common issue. Double-check cache sizes, block sizes, and filesystem layout.
  • File and folder names are stored in info.name. This is just a char array.

🚀 Bonus: Print All Files Recursively

If you want to go deeper and list all files — even inside folders — you can turn our previous example into a recursive function:

void listDirRecursively(const char* path) {
    lfs_dir_t dir;
    struct lfs_info info;

    if (lfs_dir_open(&lfs, &dir, path) == 0) {
        while (lfs_dir_read(&lfs, &dir, &info) > 0) {
            if (strcmp(info.name, ".") == 0 || strcmp(info.name, "..") == 0) continue;

            char fullPath[128];
            snprintf(fullPath, sizeof(fullPath), "%s/%s", path, info.name);
            
            if (info.type == LFS_TYPE_DIR) {
                Serial.print("Dir: ");
                Serial.println(fullPath);
                listDirRecursively(fullPath);
            } else {
                Serial.print("File: ");
                Serial.println(fullPath);
            }
        }
        lfs_dir_close(&lfs, &dir);
    }
}

Just call: listDirRecursively("/");

Careful with stack overflows on very deep directory trees, though!

🛠️ Troubleshooting Tips

  • Seeing junk filenames? Double-check if you’re using sufficient buffer sizes for lfs_info.name.
  • Filesystem doesn’t mount? Could be corrupted — try format + re-mount.
  • Nothing being printed? Check your Serial baud rate and make sure your Serial.begin() is set properly.

🎉 You Did It!

You’ve just unlocked one of the cooler features of low-level embedded programming — reading directories directly using the LittleFS C API. And you did it with style!

Now you can:

  • List files
  • Build a file explorer on an LCD or web server
  • Create logs and manage them via folders

📚 Additional Resources

Now go on, explorer! Your Arduino adventures just leveled up. 🧭

olivia