The most common reason for an update to "fail" is that the user blindly copied the entire contents of the installation package over the top of their previous version, a.k.a. a "dirty update".

This is NEVER recommended, because the configuration files will be overwritten and reset to defaults, meaning the the user will lose any settings that may enable I²S DACs, displays, controls, and so on.

⚠️ Note: mt32-pi supports many hardware configurations, and the defaults from the installation package are designed for a bare Raspberry Pi with no accessories. If you are using accessories that provide a display, audio output, or MiSTer interface for example, you MUST pay attention when upgrading and ensure you backup your configuration files, otherwise these devices will not be enabled.

Some scripts are available that assist with installing and updating mt32-pi, which can be run from a Linux PC or MiSTer FPGA system. The updater script aims to preserve all your settings and safely upgrade the rest of the system.

You'll need to enable networking support as the script relies on the embedded FTP server.

You also need to be running mt32-pi v0.11.0 or above, as this was the first version to feature the FTP server upon which the updater script relies.

Visit the scripts directory to learn more.

If the script doesn't work for you, you are unable to run Python scripts, or you prefer not to use the network features of mt32-pi, this section is for you.

mt32-pi uses a version numbering scheme in the form vXX.YY.ZZ.

First, compare the old version with the new version. If you don't know what the old version is, enable the verbose option in mt32-pi.cfg. mt32-pi will then report its version number on startup.

Read the changelog to see what's new since the old version. The changelog often includes important information about new features or changes in how the software works.

• If only ZZ has changed between the version you are upgrading from and the new version, this is a "patch" update. You can simply replace all of the kernel*.img files on the SD card with the updated versions from the installation package and leave everything else unchanged.
• If either XX or YY has changed, you should perform a full update. A "major" or "minor" release is likely to contain new firmware or boot files, and failure to update these can result in things going wrong. Additionally, new features and configuration file options may be available, so it's recommended that you use the latest default configuration file as a template and reconfigure mt32-pi so that you can benefit from new features.

1. Backup the entire contents of your SD card to your computer.
2. Delete EVERYTHING on the SD card EXCEPT the roms and soundfonts directories.
3. Extract the new installation package and copy the entire contents to the SD card EXCEPT the roms and soundfonts directories.
4. You now have a choice. You can either:
   • Recommended (reconfigure using latest config template): Open mt32-pi.cfg on the SD card and the old version you backed-up onto your computer. Compare the two files side-by-side carefully and copy each setting from the old file into the new file.
   • Lazy (keep old config): Replace mt32-pi.cfg on the SD card with the old version you backed-up onto your computer.
5. Repeat step 4 for config.txt and wpa_supplicant.cfg. These two files will rarely change, but the changelog will say so if they do.
6. Test mt32-pi. If something isn't working, check the config files for typos you may have introduced during your edits. If all else fails, either restore your backup and try again, or perform a clean installation of the latest version following the quick-start guide in the main README.