ansible/roles/pi_musicmouse

pi_musicmouse

Deploys the MusicMouse backend (python-backend/) and its built web frontend.

• Checks out musicmouse_version from pi_musicmouse_repo to /opt/musicmouse, then fails early if that checkout has no python-backend/pyproject.toml - see "Which version" below.
• Installs a pinned uv release and uses it to create /opt/musicmouse/.venv with Python pi_musicmouse_python_version (the backend needs 3.12+ for PEP 695 syntax; Raspbian Bookworm's apt python3 is only 3.11) and pip install the backend into it.
• Builds the frontend (web/) on the control machine (delegated to localhost, not the Pi - no Node/npm is installed on the Pi) and syncs web/dist over.
• Installs /media/musicmouse/config.yml from files/config-<inventory_hostname>.yml (one file per host - the schema differs between a host with a real mouse attached and a display-only one; see those files' own comments), the typing game's curriculum beside it, and the systemd unit copied straight from the checked-out repo's python-backend/musicmouse.service, so it can never drift from what's actually in the app repo.
• Sets up a Samba share of /media/musicmouse for copying music onto the device.

Which version

musicmouse_version is set per host in host_vars, with no default, and points at a deploy/<host> branch on the remote. Those branches are the deployment record: what is installed on that box right now. Moving one is a force-push, and the next run follows it (the git: task uses force: true):

git push -f origin rearchitect-backend:deploy/musicdolphin
just mediapis musicdolphin

This role only understands the post-rearchitecture layout - python-backend/ as an installable package plus a web/ frontend. On older commits the host driver lives at espmusicmouse/host_driver/main.py, there is no pyproject.toml, the unit file is under esp-firmware/, there is no frontend at all, and the config is a different format that this role's config files would fail to load. There is deliberately no legacy path: the role stops at the checkout with an explanation instead.

musicmouse (Kinderzimmer) is on such an older commit and still working, so it has mediapi_install_kidsmusic: false and this role skips it entirely; deploy/musicmouse exists purely as the rollback marker for what is installed there. Migrating it means moving /media/musicmouse/<figure>/ into Figuren/ and switching to the new config schema - files/config-musicmouse.yml is already written for that.

config.yml is install-once

The app writes to its own config at runtime: parent mode (?parentMode=1) patches the volume keys, and the remote-control page rewrites the whole remote: block. A plain copy: would throw those away on every ansible run, so the config task is force: "{{ pi_musicmouse_force_config }}", default false. Push a changed config when you actually mean to:

just run mediapis.yml musicdolphin -e pi_musicmouse_force_config=true

The curriculum file is not written by the app, so it is installed unconditionally. A config with a tippen: section will not start without it - curriculum_file is validated as must-exist - so a host whose config has no tippen: section should set pi_musicmouse_curriculum_file: "".

Manual steps after a first deploy

• Set the Samba password with smbpasswd.
• Get the music onto the device. The app repo's scripts/sync-library.sh is the way to do it: as well as the library it carries over the cover and track-analysis cache, which is the part that costs minutes of DSP per track to recompute, and it knows which parts of that cache survive the move and which must not be copied. The Samba share works too, and then the device does all that work itself.