Exploring MicroPython Filesystem: Listing Files

MicroPython is a lean and efficient implementation of the Python 3 programming language that includes a small subset of the Python standard library and is optimised to run on microcontrollers and constrained systems. One of the useful features it offers is a filesystem, which allows you to store and manage files on the device. In this blog post, we'll delve into the details of listing files in the MicroPython filesystem, covering fundamental concepts, usage methods, common practices, and best practices.

Table of Contents#

  1. Fundamental Concepts of MicroPython Filesystem
  2. Usage Methods for Listing Files
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts of MicroPython Filesystem#

The MicroPython filesystem provides a way to interact with the storage device attached to the microcontroller, such as an SD card or internal flash memory. It follows a hierarchical structure similar to traditional file systems, with directories and files organised in a tree-like manner.

To work with the filesystem in MicroPython, you typically use the os module. This module provides functions for file and directory operations, including listing files.

Usage Methods for Listing Files#

Using os.listdir()#

The most straightforward way to list files in a directory is by using the os.listdir() function. This function takes an optional argument specifying the directory path and returns a list of all the files and directories in that path. If no argument is provided, it lists the contents of the current working directory.

Here's a simple example:

import os
 
# List files in the current directory
files = os.listdir()
for file in files:
    print(file)
 
# List files in a specific directory
specific_dir = '/sdcard'
files_in_specific_dir = os.listdir(specific_dir)
for file in files_in_specific_dir:
    print(file)

In this example, we first list the files in the current directory and then list the files in a specific directory named /sdcard.

Differentiating between Files and Directories#

The os.listdir() function returns a list of names without indicating whether each item is a file or a directory. To differentiate between them, you can use the os.stat() function. This function returns a tuple containing information about a file or directory, including its type.

import os
 
# List files in the current directory and differentiate between files and directories
files = os.listdir()
for file in files:
    stats = os.stat(file)
    if stats[0] & 0x4000:  # Check if it's a directory
        print(f'{file} is a directory')
    else:
        print(f'{file} is a file')

In this code, we use the bitwise AND operation to check the file type. If the result of stats[0] & 0x4000 is non-zero, it means the item is a directory.

Common Practices#

Error Handling#

When working with the filesystem, it's important to handle errors properly. For example, if the specified directory does not exist, the os.listdir() function will raise an OSError. You can use a try-except block to handle such errors gracefully.

import os
 
try:
    files = os.listdir('/nonexistent_dir')
    for file in files:
        print(file)
except OSError as e:
    print(f'Error: {e}')

In this example, we try to list the files in a non-existent directory and catch the OSError if it occurs.

Iterating through Subdirectories#

If you want to list all the files in a directory and its subdirectories recursively, you can use a recursive function.

import os
 
def list_files_recursively(path):
    try:
        files = os.listdir(path)
        for file in files:
            full_path = os.path.join(path, file)
            stats = os.stat(full_path)
            if stats[0] & 0x4000:  # Check if it's a directory
                list_files_recursively(full_path)
            else:
                print(full_path)
    except OSError as e:
        print(f'Error: {e}')
 
# List files recursively in the current directory
list_files_recursively('.')

In this code, the list_files_recursively function lists the files in a directory and its subdirectories. If it encounters a directory, it calls itself recursively to list the files in that subdirectory.

Best Practices#

Memory Management#

Microcontrollers have limited memory, so it's important to be mindful of memory usage when working with the filesystem. For example, if you're dealing with a large number of files, you can process them one by one instead of loading all the file names into a list at once.

import os
 
# Process files one by one to save memory
for file in os.ilistdir():
    name = file[0]
    stats = os.stat(name)
    if stats[0] & 0x4000:
        continue  # Skip directories
    # Do something with the file
    print(f'Processing file: {name}')

In this example, we use os.ilistdir() instead of os.listdir() to iterate through the files one by one, which helps save memory.

Performance Optimization#

If you need to list files frequently, consider caching the results to avoid unnecessary filesystem operations. You can use a variable to store the list of files and update it only when necessary.

import os
 
# Cache the list of files
file_list = None
 
def get_file_list():
    global file_list
    if file_list is None:
        file_list = os.listdir()
    return file_list
 
# Use the cached file list
files = get_file_list()
for file in files:
    print(file)

In this code, we cache the list of files in the file_list variable and only update it if it's None.

Conclusion#

Listing files in the MicroPython filesystem is a fundamental operation that can be easily achieved using the os module. By understanding the basic concepts, usage methods, common practices, and best practices, you can efficiently manage and manipulate files on your microcontroller. Remember to handle errors, optimize memory usage, and consider performance when working with the filesystem.

References#

2025-10