control surface - dwhinham/mt32-pi GitHub Wiki

As of version 0.8.0, you can connect buttons and/or a rotary encoder to your Raspberry Pi to control mt32-pi.

Controls are enabled by setting the scheme option in the [control] section of configuration file. Only one of the following schemes may be enabled at a time.

Control schemes

Currently, two "simple" control schemes are implemented. The following schemes will eventually gain additional actions through combinations or long-presses. A menu system and other interactive controls are also planned for future versions.

simple_buttons

4 buttons via GPIO:

Control Action
Button 1 Switch synthesizer
Button 2 Switch MT-32 ROM or SoundFont
Button 3 Decrease volume
Button 4 Increase volume

simple_encoder

2 buttons and a rotary encoder via GPIO:

Control Action
Button 1 Switch synthesizer
Button 2 Switch MT-32 ROM or SoundFont
Encoder counter-clockwise Decrease volume
Encoder clockwise Increase volume
Encoder button Not yet used (shows a test message)

GPIO pin assignment

⚠ Note: Buttons should be connected between the appropriate GPIO pin and GND. No pull-up resistors are required for the buttons or encoder pins; the Raspberry Pi's internal pull-up resistors are enabled.

Rotary encoder

The rotary encoder has an additional option, encoder_type. When configured properly, one click of the encoder should increase or decrease the volume by exactly 1.

The default value of full assumes that one detent ("click") performs a full cycle of the Gray code.

  • If four clicks are needed for a single movement, try encoder_type = quarter.
  • If two clicks are needed for a single movement, try encoder_type = half.

A typical rotary encoder will have the following pinout. Note that this diagram is for a bare rotary encoder, and not a "breakout board" or "module".

  • If your encoder looks different, consult its datasheet.
  • If clockwise/counter-clockwise actions are reversed, swap the CLK and DAT pins.

KY-040 or similar modules

There are various "breakout boards" or "modules" available such as the KY-040 and its clones. These modules often have a "+" pin to enable their own pull-up resistors.

If you must use such a module, DO NOT connect the "+" pin to +5V on the Raspberry Pi, otherwise you could cause permanent damage to the Pi's GPIOs, which are not 5V tolerant.

Instead, connect it to 3.3V. Alternatively, remove the pullup resistors from the board and leave "+" disconnected - mt32-pi enables the Raspberry Pi's own internal pull-up resistors on the encoder pins, so external pullup resistors should not be necessary.

In general, we do not recommend these modules. The encoders themselves tend to be fairly poor quality.

© Dale Whinham 2020-2022. Released under the GNU General Public License v3.0.

⚠️ **GitHub.com Fallback** ⚠️