Pkg.SPIFFS

Overview

SPIFFS (SPI Flash File System) is a flat file system designed for SPI NOR flash memory, commonly used in ESP8266, ESP32, and other embedded microcontrollers. It provides wear leveling and power-loss resilience with minimal RAM overhead.

Key characteristics:

• Flat file namespace (no directories)

• Configurable page size (typically 256 bytes) and block size (typically 4096 bytes)

• 16-bit object IDs

• No timestamps

• Optional magic numbers for filesystem identification

• Little-endian or big-endian byte order

The Pkg.SPIFFS.SPIFFSObject class automatically detects the image configuration (page size, block size, endianness) and presents the flat file list through the CFS interface. Files with path separators in their names (e.g. /config/wifi.json) are presented in a synthesized directory structure.

Enumerating SPIFFS Files

The following code demonstrates how to open a SPIFFS image and enumerate its files:

from Pro.Core import *
from Pkg.SPIFFS import SPIFFSObject

def inspectSPIFFS(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = SPIFFSObject()
    obj.Load(c)
    if not obj.Initialize():
        return
    print("Page size:", obj.GetPageSize())
    print("Block size:", obj.GetBlockSize())
    print("Files:", obj.GetFileCount())
    nre = CFSNonRecursiveEnum(obj)
    nre.AddPath(obj.FSRootDirectory())
    while True:
        path = nre.Next(None)
        if not path:
            break
        entry = obj.FSGetEntry(path, None)
        if entry.isNull():
            continue
        print(path, entry.DataSize(), "bytes")

Module API

Pkg.SPIFFS module API.

Classes:

SPIFFSObject()

This class represents a SPIFFS (SPI Flash File System) image.

class SPIFFSObject

This class represents a SPIFFS (SPI Flash File System) image.

SPIFFS is a flat file system designed for SPI NOR flash memory, commonly used in ESP8266 and ESP32 microcontrollers. It has no directory support; files are stored with flat paths (e.g. /config.json). The class provides file system support through the CFS interface inherited from CFFObject, with automatic detection of page size, block size, and endianness. Files with path separators in their names are presented in a synthesized directory structure.

Methods:

GetBlockSize()	Returns the logical block size in bytes.
GetFileCount()	Returns the number of files in the file system.
GetFreePageCount()	Returns the number of free pages available for new data.
GetPageSize()	Returns the logical page size in bytes.
GetUsedPageCount()	Returns the number of used (non-free, non-deleted) pages.
HasMagic()	Returns whether the image uses SPIFFS magic numbers for block identification.

GetBlockSize() → int

Returns the logical block size in bytes.

Common values are 4096, 8192, or 65536. Each block contains one or more lookup pages followed by content pages.

Returns

Returns the block size.

Return type

int

GetFileCount() → int

Returns the number of files in the file system.

Returns

Returns the file count.

Return type

int

GetFreePageCount() → int

Returns the number of free pages available for new data.

Returns

Returns the free page count.

Return type

int

GetPageSize() → int

Returns the logical page size in bytes.

Common values are 256, 128, or 64.

Returns

Returns the page size.

Return type

int

GetUsedPageCount() → int

Returns the number of used (non-free, non-deleted) pages.

Returns

Returns the used page count.

Return type

int

HasMagic() → bool

Returns whether the image uses SPIFFS magic numbers for block identification.

When enabled, each block contains a magic value derived from the page size and filesystem geometry, allowing validation of the filesystem configuration.

Returns

Returns True if magic numbers are present, False otherwise.

Return type

bool