buzzer_2/firmware/fs

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.

python3.11 -m venv venv
. venv/bin/activate
pip install -r requirements.txt

On Windows:

py -3.11 -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

Build LittleFS Image

./venv/bin/python build_lfs_audio.py

Example with imported WAV files and a custom system prompt YAML:

./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:

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:

./program.sh

On Windows:

program.bat

Both scripts use paths relative to their own location, so they can be started from any working directory.