85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```cpp
|
|
// 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.
|