-
-
Notifications
You must be signed in to change notification settings - Fork 76
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.
There are currently three different LCD drivers, which are detailed in the following sections.
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.
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.
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.
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
.
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
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. |
Β© Dale Whinham 2020-2022. Released under the GNU General Public License v3.0.