Update filesystem tooling and LittleFS defaults

firmware/fs/README.md

@@ -0,0 +1,86 @@
+# FS Tooling
+
+This directory contains the tooling to build and flash the external LittleFS image used by the firmware.
+
+## Python Version
+
+Use Python 3.11.
+
+The filesystem/audio build tool is currently tested with Python 3.11.
+Python 3.13 is not supported at the moment, especially on Windows, because some dependencies in the TTS toolchain may fall back to source builds and fail to install.
+
+In particular, the dependency chain around `kokoro`, `spacy`, `thinc`, and `blis` may fail to install on Windows when no compatible wheels are available.
+
+## Install Dependencies
+
+`ffmpeg` is required in addition to the Python packages.
+
+```sh
+python3.11 -m venv venv
+. venv/bin/activate
+pip install -r requirements.txt
+```
+
+On Windows:
+
+```bat
+py -3.11 -m venv venv
+venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+## Build LittleFS Image
+
+```sh
+./venv/bin/python build_lfs_audio.py
+```
+
+Example with imported WAV files and a custom system prompt YAML:
+
+```sh
+./venv/bin/python build_lfs_audio.py \
+	--wav-dir ./my_wavs \
+	--sys-yaml ./sys_prompts.yaml
+```
+
+Notes:
+
+- `--wav-dir` imports all `.wav` files from the given directory into `/lfs/a`
+- `--sys-yaml` overrides the default TTS prompt list for `/lfs/sys`
+- generated audio is converted to mono 16 kHz PCM before it is written into the LittleFS image
+
+This generates:
+
+- `lfs_external_flash.hex`
+
+The default image layout is aligned to a 4 KiB flash page layout.
+
+After the build, the script also prints a usage summary for `/lfs/sys`, `/lfs/a`, and the combined image.
+
+Example:
+
+```text
+Usage summary:
+	sys: files=4, raw=48.0 KiB, fs=56.0 KiB (14 blocks, standalone estimate)
+	audio: files=12, raw=224.0 KiB, fs=264.0 KiB (66 blocks, standalone estimate)
+	total: raw=272.0 KiB, fs=300.0 KiB (75 blocks in combined image)
+```
+
+`raw` is the sum of file sizes in the staging tree.
+`fs` is the estimated or measured LittleFS space usage with the configured block size.
+
+## Flash Image
+
+On macOS/Linux:
+
+```sh
+./program.sh
+```
+
+On Windows:
+
+```bat
+program.bat
+```
+
+Both scripts use paths relative to their own location, so they can be started from any working directory.