Troubleshooting

On this page we'll provide some troubleshooting tips to help you try and find the cause of any problems when using mt32-pi. This helps us if it can prevent the need to open an issue unnecessarily, or it might help us understand your issue better if you have tried some of the procedures here.

New revision Raspberry Pi 3A+

If you have the newest revision of Pi 3A+, mt32-pi may fail to boot. If the ACT LED blinks four times slowly followed by seven short flashes, you will need updated bootloader binaries, which you can get from the official Raspbian distribution. Copy the fixup_cd.dat and start_cd.elf (and maybe bootcode.bin?) from the Raspbian boot partition over the mt32-pi sd card.

Reading mt32-pi's logs

It can be very useful to see some logs when troubleshooting problems. Special debug builds of mt32-pi log messages to a framebuffer console that can seen via a monitor connected to the Raspberry Pi's HDMI port.

⚠️ Note: Release builds of mt32-pi do not output anything via HDMI for performance/latency reasons.

To see mt32-pi's logs, you can download and test a debug version as follows (note that you must have a GitHub account and be logged in):

1. Go to the Actions area and find the workflow run corresponding to the latest release by typing branch:vXX.YY.ZZ into the search box. For example, to find the workflow run for v0.12.1, type branch:v0.12.1. Click the title of the result to visit the summary page.
   • Alternatively, you may have been given a direct link to a specific test build during troubleshooting. In that case, use the link provided instead.
2. In the "Artifacts" section near the bottom of the page, click on kernels-hdmi and download the ZIP archive. Note that you must be logged in to GitHub to see the artifacts.
3. Extract the kernel*.img files from the archive and replace the kernels on the Raspberry Pi's SD card with the ones from this archive. These are the debug kernels with HDMI logging enabled. You may wish to back up the old kernels.
4. Connect an HDMI monitor to the Raspberry Pi and start mt32-pi as usual. Make sure you connect the monitor BEFORE powering on the Raspberry Pi.
5. You should see the message log scroll by as mt32-pi starts up.
6. Check for any error messages that may be related to your problem. Take photos of any messages of interest and provide them to whoever may be helping with your issue.
7. To revert to a non-debug build (recommended, as performance is lower with debug builds), you can download the kernels artifact (i.e. not kernels-hdmi) from the same summary page as before and simply replace the kernel files again. Alternatively, restore the kernel files from your backup.

Testing your hardware with Linux

It may be useful to test that your hardware is working properly outside of mt32-pi by testing it under Linux. If similar unexpected behaviour is experienced under Linux, then the issue may not be with mt32-pi, and you will need to correct any hardware problems or replace faulty components.

Raspberry Pi OS setup

We'll prepare a Linux environment on the Raspberry Pi running Munt that we can use to check behavior against mt32-pi.

1. Begin by preparing an SD card with a desktop-enabled edition of Raspberry Pi OS (formerly known as Raspbian). Ensure that you can reach the desktop and that you have internet connectivity.
2. Update your OS packages and reboot the Raspberry Pi by issuing the following commands in a terminal:

   $ sudo apt-get update
   $ sudo apt-get upgrade
   $ sudo reboot
   

3. We need to install some prerequisites for compiling Munt from source. Issue the following command in the terminal:

   $ sudo apt-get install git cmake libasound2-dev libglib2.0-dev libpulse-dev portaudio19-dev qt5-default qtbase5-dev qtmultimedia5-dev
   

4. Check out the latest Munt source code and compile it:

   $ git clone https://github.com/munt/munt.git
   $ cd munt
   $ mkdir build && cd build
   $ cmake .. -DCMAKE_BUILD_TYPE=Release
   $ cmake --build .
   $ sudo make install
   

5. If compilation was successful, you can now start Munt by running mt32emu-qt.
6. Copy your MT32_CONTROL.ROM and MT32_PCM.ROM files somewhere convenient, and use the Options -> ROM Configuration menu to locate and enable them.

Setting up and testing a GPIO MIDI interface

If you are trying to troubleshoot a GPIO MIDI interface, some further steps are required. N.B. USB MIDI interfaces should not require any further setup.

1. Edit the config.txt file on your Pi's SD card /boot partition and add the following lines to the end of it. This moves the Bluetooth UART onto the less capable mini UART, freeing up UART0 for MIDI, and also tweaks some clocks to allow the UART to communicate at the proper MIDI baud rate.

   enable_uart=1
   dtoverlay=miniuart-bt
   dtoverlay=midi-uart0
   

2. Edit the cmdline.txt file (again on the SD card /boot partition) and delete console=serial0,115200 from it. This prevents the Linux console from using the serial port.
3. Reboot the Pi, and compile a modified version of ttymidi that supports SysEx messages:

   $ git clone https://github.com/ElBartoME/ttymidi.git
   $ cd ttymidi
   $ make
   

4. Now you can start ttymidi with the following command - it needs to stay running throughout the session:

   $ ./ttymidi -b 38400 -s /dev/ttyAMA0 -v
   

5. Connect a MIDI source such as a keyboard to the GPIO MIDI input and play some notes, or play a song using a connected computer and MIDI player. Verify that the events appear correctly in the terminal. You could use a Windows PC with USB MIDI interface and Pocket MIDI to send MIDI notes by playing an on-screen keyboard. This way you can ensure that all key presses result in a corresponding Note On and Note Off pair. Try playing keys rapidly - if any Note Offs are missing, you probably have a hardware issue and missing/hanging notes will occur.

Testing with Munt

If you want to test an I²S DAC, follow its documentation to get it working under Linux. However, you should only troubleshoot one thing at a time - i.e. if you're having MIDI issues, just use the Pi's headphone jack until you have resolved it.

With a MIDI interface connected and set up, and Munt running, you can test it with Munt as follows:

1. Run aconnect -l. The output should be similar to the following:

    client 0: 'System' [type=kernel]
        0 'Timer           '
        1 'Announce        '
    client 14: 'Midi Through' [type=kernel]
        0 'Midi Through Port-0'
    client 128: 'ttymidi' [type=user,pid=2557]
        0 'MIDI out        '
        1 'MIDI in         '
    client 129: 'Munt MT-32' [type=user,pid=2302]
        0 'Standard        '
   

2. We want to connect the MIDI out port of our interface into the input of Munt. In the example above, ttymidi is our MIDI interface, so we run the following to connect it:

   $ aconnect 128:0 129:0
   

   Adapt this command as necessary if you're using a USB interface.
3. Munt should detect the connection and the interface should change to show the synthesizer.
4. Click Stop, then change the audio output device to ALSA: System default.
5. Click Properties, and set the chunk length to 64, and the audio latency to 1024.

   Note: You will probably experience clicks/pops and very high latency with this far-from-ideal setup - this is not a Linux low-latency audio guide. We just want to get something fairly listenable for testing purposes. If you can assist with documenting a better JACK-based configuration, feel free to edit this wiki page. Also feel free to try other values if these ones give you problems - for me, it worked with some occasional clicks/pops on a Pi 3 B+. Your mileage may vary.

6. If you're using the headphone jack, right-click the speaker at the top-right of the screen and set the output to AV Jack.
7. Click Start and start your MIDI source. You should hear Munt making sound.