RaftFileManagerSysMod

FileManager SysMod

Built-in SysMod that mounts a local flash file system (LittleFS or SPIFFS), optionally an SD card, and exposes file-system operations as REST endpoints.

Source: RaftSysMods/components/FileManager/

What it provides

• Mount of local (LittleFS or SPIFFS) and optionally sd.
• File listing, read, delete, upload (HTTP and chunked-RICREST) and full reformat.
• Routing of incoming FileBlock chunks to ProtocolExchange when uploads come over BLE/serial.

SysType configuration

{
    "name": "FileManager",
    "LocalFsDefault": "littlefs",
    "LocalFsFormatIfCorrupt": 1,
    "SDEnabled": 0,
    "DefaultSD": 0,
    "CacheFileSysInfo": 0,
    "SDMOSI": "",
    "SDMISO": "",
    "SDCLK": "",
    "SDCS": ""
}

Key	Default	Meaning
LocalFsDefault	"littlefs"	Local FS driver: "littlefs" or "spiffs"
LocalFsFormatIfCorrupt	true	Auto-format if mount fails
SDEnabled	false	Enable SPI SD card mount
DefaultSD	false	When set, default file ops resolve to the SD card if present
CacheFileSysInfo	false	Cache directory listings between calls
SDMOSI / SDMISO / SDCLK / SDCS	""	SD SPI pins (named pin or numeric string)
WritePacingPct	30	Maximum percentage of time spent in slow file system writes during an upload (0 = no pacing). See Write pacing. (RaftCore versions after 1.58.1)

Write pacing

Writing to flash periodically needs a 4 KB sector to be erased, which takes about 60-70 ms. On ESP32 chips the flash cache is disabled on both cores during an erase, so all code running from flash stalls whichever task is writing. A continuous upload can therefore stall the whole system most of the time (measured at about 76% on a UM FeatherS3).

With write pacing, after a slow write, uploads are held off long enough that slow writes take at most WritePacingPct of the time:

• HTTP uploads (fileupload): the web server stops reading the request, so the client is slowed by TCP flow control.
• RICSerial uploads (e.g. raftjs over WebSocket, BLE or serial): received messages stay queued, so the transfer's own flow control slows the sender.

No extra buffering is needed and uploads still only complete once the data is written. The cost is upload speed: at the default 30% a FeatherS3 uploaded at about 17 kB/s (HTTP) instead of 44 kB/s.

Flash chips which support auto-suspend (CONFIG_SPI_FLASH_AUTO_SUSPEND, ESP32-S3 and later with specific flash chips only) avoid the stall altogether.

REST endpoints exposed

In all paths the file system name (local or sd) is the first path segment after the verb; folders use ~ instead of /.

Endpoint	Method	Purpose
reformatfs/<fs>	GET	Reformat a file system — destructive
filelist/<fs>/<folder>	GET	List directory contents as JSON
fileread/<fs>/<path>	GET	Read file contents
filedelete/<fs>/<path>	GET	Delete a file
fileupload	POST	Upload a file (HTTP multipart or RICREST chunked)

Related

• File Download Protocol (OKTO) — outbound file streaming
• ProtocolExchange — owns file/stream sessions
• WebServer SysMod — for HTTP access