LCD and OLED displays

mt32-pi supports various LCD and OLED displays, both traditional character displays like the original MT-32, and modern graphical displays.

The MT-32 had a single row, 20 column display, but these are hard to find nowadays. 20x2 and 20x4 displays are common however, and mt32-pi can use the extra rows to display additional information.

To enable a display, you will need to edit mt32-pi.cfg accordingly, and correctly connect your display to the Raspberry Pi.

Drivers

There are currently three different LCD drivers, which are detailed in the following sections.

Hitachi HD44780 compatible 4-bit driver (hd44780_4bit)

This driver is for connecting a traditional HD44780 or compatible (e.g. Winstar WS0010/Raystar RS0010) character display directly to the Pi's GPIO pins in 4-bit mode. Currently, only 20x2 and 20x4 displays are supported. Rotation is not supported.

Consult your display's datasheet to determine the correct LCD pins to connect to the GPIOs. The current pinout is as follows:

LCD signal	Physical Raspberry Pi pin	BCM pin
RS	19	10
RW	21	9
EN	23	11
D4	27	0
D5	29	5
D6	31	6
D7	33	13

You will also need to connect a power source and ground to your display. Consult its datasheet to see if it requires 3.3V or 5V. You should be able to use the Pi's 3.3V, 5V, and ground pins as necessary, but check the datasheet to ensure the display doesn't draw more current than the Pi can deliver safely.

⚠️ Note: The GPIO assignment could change in later versions as more functionality is added, so BE WARNED if you are thinking about designing hardware.

Hitachi HD44780 compatible I²C driver (hd44780_i2c)

This driver is functionally equivalent to the 4-bit driver, but instead of using GPIOs to drive the LCD's data signals directly, the Pi communicates with the display via an I²C-connected I/O expander. Some vendors refer to these as an "I²C backpack".

These displays are very convenient as they only need 4 wires to connect to the Pi. Your display will connect to the Pi's SDA and SCL lines (pins 3 and 5 respectively), as well as power and ground. As always, check your display's datasheet for power requirements.

As with all I²C devices, you must know the LCD's I²C address in order for it to work. You should be able to find its address on the datasheet, or the "backpack" may have jumpers to configure the address. In case of doubt, you can connect the display and use Linux to discover your display using the same procedure described in the DAC section.

SSD1306 I²C driver (ssd1306_i2c)

The SSD1306 controller is found in mini 128x32 and 128x64 OLED displays, which are well-known for their use in FlashFloppy/Gotek devices. They can be found for very little money on eBay and AliExpress.

Currently, only 128x32 and 128x64 variants are supported. These displays can be inverted using the rotation configuration file option. These displays usually have an I²C address of 0x3c.

Some displays can be used with both I²C and SPI interfaces and may need to be reconfigured by setting some resistors on the back of the assembly. mt32-pi currently only supports I²C displays, so read your display's documentation to learn how to put it into I²C mode.

This driver should also work with SSD1309 displays such as the Diymore 2.42" OLED, but the display may need some small modifications to ensure it is in I²C mode, that the address is correct, and to deal with any reset signals.

Compatibility

The following displays and configurations have been confirmed as working by our testers. Please note the necessary configuration file options.

Manufacturer	Device	Config file options	Comments
BuyDisplay.com	2002-1 Series	type = hd44780_i2c, width = 20, height = 2, i2c_lcd_address = 27	Very bright and inexpensive 20x2 LCD. Tested by @dwhinham.
Diymore	2.42" OLED	type = ssd1306_i2c, width = 128, height = 64, i2c_lcd_address = 3c	Large 128x64 OLED. Requires modifications: R4 removed, R3 shorted, R5 shorted, DC tied to GND, RES tied to GND via a 10K pull-down resistor [1]. Tested by @flynnsbit.
Generic	128x32 OLED	type = ssd1306_i2c, width = 128, height = 32, i2c_lcd_address = 3c	Extremely cheap yet nice and bright mini OLED. Widely available on AliExpress and eBay. Tested by @dwhinham.
Generic	128x64 OLED	type = ssd1306_i2c, width = 128, height = 64, i2c_lcd_address = 3c	Similar to the 32 pixel high OLED, just with more rows. Tested by @dwhinham.
Raystar	REC002004B	type = hd44780_4bit, width = 20, height = 4	High-contrast 20x4 OLED display. Tested by @dwhinham.