musicmouse/docs/REPO_OVERVIEW.md

MusicMouse — repo overview

Orientation doc for AI agents (or humans) working on this repo for the first time. Written from what's actually in the repo — no roadmap speculation beyond esp-firmware/todo.md.

What this is

MusicMouse is a DIY, Toniebox-style physical music player for kids, shaped like a mouse and living on a shelf. Small 3D-printed animal figurines (fox, owl, dog, elephant, squirrel, crocodile, rabbit, snowman, puppy — see hardware/3dprints/figures/) each carry an RFID tag. Placing a figurine on the mouse triggers an RFID read, which starts that figure's music playlist. The mouse also has a rotary encoder + touch buttons (ears/feet) for volume/skip control, addressable RGBW LED rings with animated effects, and MQTT/Home Assistant integration so a "shelf light" shows up as a smart-home device.

Repo layout

Path	What it is
python-backend/	Python host application — the main runtime. Reads RFID/button/encoder events from the ESP32 over serial, drives playback via VLC, sends LED effect commands, bridges to MQTT/Home Assistant. Start here for backend work.
esp-firmware/	ESP32 firmware (C++, Arduino framework via PlatformIO). Reads the RFID reader and buttons, drives the LED strips, talks to python-backend over serial.
hardware/	3D-print models for the figurines and enclosure (FreeCAD/Blender/OBJ/STL), a Fritzing electronics sketch, datasheets, and pinout.md (RFID reader + button-board wiring).
claude-design/	An unrelated exploratory web-UI mockup ("Dolphin Beats Music Player" / rebrand concept). Not integrated with the rest of the repo — no build system ties it in. Don't assume it reflects current product direction.
.vscode/	Editor settings (C++ header associations).

There is no top-level README elsewhere in the repo; this file plus esp-firmware/todo.md and hardware/pinout.md are the only prose docs.

How the pieces talk to each other

• ESP32 firmware ↔ python-backend: a length-prefixed binary protocol over serial (pyserial-asyncio), implemented in python-backend/host_driver.py. Messages are framed with magic tokens (MAGIC_TOKEN_HOST_TO_FW/MAGIC_TOKEN_FW_TO_HOST) and a struct-packed header. The message-ID maps and struct formats in host_driver.py must stay byte-for-byte in sync with the firmware's esp-firmware/src/Messages.h — there's no shared schema or test verifying this cross-language contract, so a firmware protocol change can silently desync the Python side.
• python-backend ↔ MQTT/Home Assistant: python-backend/mqtt_json.py exposes the shelf LED strip as a Home-Assistant-discoverable JSON-schema MQTT light (ShelveLightMqtt), and main.py also calls Home Assistant services directly (e.g. toggling room lights) via hass-client.

Running it

python python-backend/main.py <config_dir>

main.py expects <config_dir>/config.yml (schema documented in the new python-backend/config.yml.example — no real config was previously checked in or documented). In production this is deployed as a systemd service reading music from /media/musicmouse/; see esp-firmware/musicmouse.service for the unit template — note its ExecStart path (.../espmusicmouse/host_driver/main.py) is stale, referencing the pre-reorg directory layout from before the bd8925a "Cleaned up repository" commit moved things to python-backend/. Update that path before relying on the service file.

Config schema (see python-backend/config.yml.example)

• general.{alsa_device, serial_port, hass_url, hass_token, mqtt.{server,user,password}, min_volume, max_volume, volume_increment, button_leds_brightness}
• figures.<name>.{id, colors, media_files} — id is a hex RFID tag id, colors is a list of 4 colors (primary, secondary, background, accent, each "#rrggbb" or "wNN"), media_files is optional (auto-globbed from the config dir by figure name if omitted).

Known gaps / notes for agents

• No automated tests, no lint/formatter config, no CI anywhere in the repo (neither python-backend/ nor esp-firmware/, aside from a PlatformIO native build env for firmware unit testing).
• python-backend/audio_analysis.py and the three chord-recognition notebooks (C5S2_ChordRec_Templates.ipynb, C5S3_ChordRec_HMM.ipynb, C5S3_HiddenMarkovModel.ipynb) are university-course exploratory material (chroma/chord-recognition DSP), not imported by main.py and not part of the running app. They reference stale personal absolute paths.