StaticFileService

Serves static files from the device's LittleFS filesystem over HTTP.

Overview

Service name: StaticFileService
Mounts: LittleFS at startup
Endpoints:
- GET / → serves /index.html
- GET /* → serves any file under LittleFS by path

Files are looked up relative to the filesystem root. If a requested path is empty or /, it falls back to index.html. Unknown paths return 404; a helper exists to fall back to index.html for SPA routing if desired.

Content types

Determined by filename extension:

.html, .htm → text/html
.css → text/css
.js → application/javascript
.json → application/json
.png → image/png
.jpg, .jpeg → image/jpeg
.gif → image/gif
.svg → image/svg+xml
.ico → image/x-icon
default → application/octet-stream

Building and uploading the filesystem

Place your web assets under the data/ folder at the project root. The build system packages data/ into a LittleFS image matching the environment's flash layout.

Upload via PlatformIO

# Build and upload filesystem for esp01_1m
pio run -e esp01_1m -t uploadfs

# Build and upload filesystem for d1_mini
pio run -e d1_mini -t uploadfs

Manual image build (optional)

There are helper commands in ctl.sh if you need to build and flash the FS image manually:

# Build image from ./data into littlefs.bin
./ctl.sh mkfs

# Flash image at preconfigured offset
./ctl.sh flashfs

Note: Offsets and sizes must match the environment's ldscript. The project defaults are:

esp01_1m: ldscript eagle.flash.1m64.ld (64KB FS)
d1_mini: ldscript eagle.flash.4m1m.ld (1MB FS)

See docs/Development.md for details on filesystem and ldscript mapping.

Enabling the service

StaticFileService is registered as a core service in the framework and enabled by default:

// part of Spore::registerCoreServices()
auto staticFileService = std::make_shared<StaticFileService>(ctx, apiServer);
services.push_back(staticFileService);

If you maintain a custom build without the default services, ensure you instantiate and add the service before starting the API server.

Routing notes

Place your SPA assets in data/ and reference paths relatively.
To support client-side routing, you can adapt handleNotFound to always serve /index.html for unknown paths.

Troubleshooting

"LittleFS Mount Failed": Ensure board_build.filesystem = littlefs is set and the ldscript provides a filesystem region.
404 for known files: Confirm the file exists under data/ and was uploaded (pio run -t uploadfs).
Incorrect MIME type: Add the extension mapping to getContentType() if using custom extensions.

2.6 KiB Raw Permalink Blame History