short-header

Setup debugging

Everything on this page is done over SSH on the Pi, as the patch user, unless it says otherwise. Install instructions are on Setup; this page is what to do once it is installed and something is not right.

Check that both services are running

MSEQ is two services: mseq.service is Pure Data and the sequencer itself, and mseq-webapp.service is the browser control surface on port 8080. Run systemctl --user status mseq mseq-webapp --no-pager and expect both to report active (running). If the sequencer is dead the webapp will still answer on port 8080 and show “MSEQ not responding”, which is the quickest way to tell the two apart from a phone: a page that loads but shows that banner means the webapp is fine and Pure Data is not.

Restart MSEQ

systemctl --user restart mseq kills Pure Data and relaunches it through start_MSEQ.sh, which also re-wires the MIDI connections. It takes about ten seconds, during which every browser client drops its connection and then reconnects on its own. Restarting the sequencer is the right first move after anything that leaves MIDI half-wired, such as a device unplugged and plugged back in while the patch was running. The webapp survives that restart untouched, so restart it separately with systemctl --user restart mseq-webapp only when the browser surface itself is the thing misbehaving.

Read the logs

journalctl --user -u mseq -n 50 gives you Pure Data’s output, which is where every console message from the patch lands: missing arrays, session load warnings, failed file writes. journalctl --user -u mseq-webapp -n 50 gives you the webapp, which is where PIN failures, WebSocket errors and OSC problems show up. Add -f to either to follow it live while you reproduce the fault, which is far more useful than reading it afterwards.

Shut down and power off

Do not pull the power. sudo shutdown -h now closes both services cleanly and parks the SD card, and only then is it safe to switch off at the wall. A hard power cut during a write is the one reliable way to corrupt a session file or the catalog, and the boot-time backup described below is your only protection against it. To reboot instead, sudo reboot brings both services back on its own: they are enabled at boot and need no login.

Verify a fresh install

After bootstrap-pi.sh --all exits cleanly, check three things in order. Both services report active (running). http://<your-pi-hostname>:8080/ answers from another device on the same network and asks for a PIN. Pressing play on your clock source makes the Launchpads move. If the first fails, read the journal; if the second fails, check that the device is on the same network as the Pi and that the PIN is right; if the third fails, the problem is MIDI routing rather than the install.

When a Launchpad or LaunchControl stops responding

Each device is pinned to a stable name by udev rules, and a reconnect rule re-wires a device to Pure Data when it comes back. So unplugging a Launchpad mid-set and plugging it back in normally recovers on its own within a second or two. If it does not, restart the sequencer, which re-runs the whole MIDI wiring. If a device is still missing after that, confirm the system can see it at all with aconnect -l: a device that does not appear there is a cable, hub or power problem rather than an MSEQ one.

Change the PIN

The PIN ships as 1234 and lives in /etc/mseq/webapp.env, outside the repository, readable only by root and the patch group. Edit it with sudoedit /etc/mseq/webapp.env, set MSEQ_WEB_PIN=, then restart the webapp service: the file is read once at start, so nothing changes until you do. Confirm by trying the old PIN, which should now be refused. Never commit a file containing a real PIN.

Change the hostname or the Wi-Fi network

Both are Raspberry Pi OS jobs rather than MSEQ ones, and both are worth doing before a gig rather than at one. Changing the hostname changes the address the webapp answers on, so tell the other player. Adding a second Wi-Fi network in advance (the venue’s, alongside the studio’s) means the rig comes up on whatever is in range, which is the difference between a five-minute setup and a lost evening. The step-by-step for both is in the install readme.

Back up and restore sessions without cloud sync

Every launch snapshots the whole patches/ directory, which is your session files and their catalog, into a timestamped folder before Pure Data starts. The five most recent snapshots are kept and older ones are dropped, so a bad load or an accidental overwrite is recoverable as long as you notice within five launches. Run scripts/restore_patches_backup.sh with no arguments to list what is there, newest first, and again with a snapshot name to restore it. Stop the sequencer before restoring and start it again afterwards. For copying sessions between rigs instead, use cloud sync: Google Drive session sync.

Recover a damaged catalog

If the catalog file is lost but the session files survive, the patch rebuilds the catalog at boot from the metadata inside each session file, resolving two sessions that claim the same slot in favour of the more recently modified one and moving the loser to a free slot. Files too damaged to read are logged and skipped rather than stopping the rebuild, so check the sequencer’s log after a recovery boot to see which ones did not make it. If the result is not what you expected, restore a backup snapshot instead.

Update to a new runtime

Updating is a git pull in ~/code/sequencer followed by sudo install/bootstrap-pi.sh --all, which fetches the pinned runtime build, verifies its checksum, swaps it into place and re-runs the smoke tests. Check cat /opt/mseq/VERSION afterwards to confirm what you are on. Do not update on the day of a gig. If an update goes wrong, the previous runtime is one lockfile away: the rollback procedure, along with the full set of install options, is in the install readme.

Where to go next