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 based on the PCF8574. 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.

You can find adaptor boards (sometimes known as "backpacks") as well as pre-assembled I²C displays very cheaply on AliExpress - just ensure they have the correct chipset.

⚠️ Note: Only displays using the PCF8574 I²C expander are supported. Other chipsets (e.g. the MCP23017 used in the Adafruit I²C "backpack") are not supported.

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 0.91"/0.96" 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 is also reported to work with:

• SSD1309 displays such as the Diymore 2.42" OLED, but the display may need some hardware hacks to ensure it is in I²C mode, that the address is correct, and to deal with any reset signals.
• SSD1305 displays such as the Waveshare 1.3" OLED HAT by setting a magic width value of 132. Again, hardware hacks may be required.

SH1106 I²C driver (sh1106_i2c)

This controller is very similar to the SSD1306 and is found in the larger 1.3" modules, except the framebuffer is 132 pixels wide instead of 128, and can only be addressed one page at a time, so the update routines are slightly different. Despite the larger framebuffer, most modules still only have a physical pixel width of 128.

Again, these devices usually have an I²C address of 0x3c.

A note on "8-bit" I²C addresses

The valid 7-bit address range for an I²C device is from 0x08 to 0x77 inclusive [1]. Some OLED screens may be marked with a silkscreen or have documentation showing I²C addresses outside of this range, e.g 0x78 or 0x7a.

This is simply because the manufacturer has (mistakenly) added the read/write bit to the end of the 7-bit address in the least-significant position, making it 8 bits. This bit is not really part of the address. If the address given by the manufacturer falls outside of the 0x08 to 0x77 range, then the correct address for use in the configuration file can be found by shifting this value one bit to the right (e.g. in a programmer's calculator).

To use our examples above:

• (0x78 >> 1) == 0x3c
• (0x7a >> 1) == 0x3d

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	1.3" OLED	type = sh1106_i2c, width = 128, height = 64, i2c_lcd_address = 3c	Small 128x64 OLED. Widely available on AliExpress and eBay. 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 VCC via a 10K pull-up resistor and to GND through a 1uF cap [2]. Tested by @flynnsbit and @callanbrown [3].
Generic	0.91" 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	0.96" 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.
Generic	0.96" 128x64 OLED (SSD1312)	type = ssd1306_i2c, width = 128, height = 64, i2c_lcd_address = 3c, mirror = mirrored	Similar to the 0.96" display above, except with a low vertical profile. Requires "mirrored" option to be set. Tested by @nikitalita.
Raystar	REC002004B	type = hd44780_4bit, width = 20, height = 4	High-contrast 20x4 OLED display. Tested by @dwhinham.
Waveshare	Waveshare 1.3" OLED HAT	type = sh1106_i2c, width = 128, height = 64, i2c_lcd_address = 3c	Requires changes to the resistors to enable I²C as well as tying RST to VCC. To enable the buttons, traces should be cut and replaced (the original button pinout conflicts with the I²S signals for audio). Tested by @ahmadexp.
Waveshare	Waveshare 2.23" OLED HAT	type = ssd1306_i2c, width = 132, height = 32 , i2c_lcd_address = 3c	Requires changes to the resistors to enable I²C. Uses the magic width value of 132 to enable the SSD1305 using the ssd1306_i2c driver. Tested by @ahmadexp.