Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rm-hull/luma.oled/llms.txt

Use this file to discover all available pages before exploring further.

SPI is faster than I2C because it runs at a higher frequency and has less protocol overhead. It requires six or seven pins depending on your module. If your application needs fast display refresh rates — for animations or real-time data — SPI is the better choice over I2C.
There are varying pin-out configurations on different display modules. Always verify the pin labels on your specific device, especially VCC and GND, before applying power.

​
Pin connections

The GPIO pins used for SPI are the same across all Raspberry Pi versions. Connect the display to the P1 header as follows:
Device PinNameRemarksRPi PinRPi Function
1VCC+3.3V PowerP01-173V3
2GNDGroundP01-20GND
3D0ClockP01-23GPIO 11 (SCLK)
4D1MOSIP01-19GPIO 10 (MOSI)
5RSTResetP01-22GPIO 25
6DCData/CommandP01-18GPIO 24
7CSChip SelectP01-24GPIO 8 (CE0)

​
Enable SPI on Raspberry Pi OS

1

Run raspi-config

sudo raspi-config
2

Enable SPI

Navigate to Interface Options > SPI and enable it.
3

Reboot

Exit raspi-config and reboot your Pi.
If raspi-config is not available, the SPI port can be enabled manually by editing the device tree configuration.

​
Verify SPI is enabled

Check that the SPI device files exist: 
ls -l /dev/spi*
Expected output: 
crw-rw---- 1 root spi 153, 0 Nov 25 08:32 /dev/spidev0.0
crw-rw---- 1 root spi 153, 1 Nov 25 08:32 /dev/spidev0.1
Or check with lsmod: 
lsmod | grep spi
Expected output: 
spi_bcm2835             6678  0

​
Add user to spi and gpio groups

sudo usermod -a -G spi,gpio pi
Log out and back in to apply the group permissions.

​
Notes on alternate GPIO pins and ports

If the default GPIO 24 (DC) or GPIO 25 (RST) pins are already in use, you can choose different pins and pass gpio_DC and/or gpio_RST arguments with the new BCM pin numbers when creating the serial interface. This applies to PCD8544, ST7567, and ST7735 controllers.
Because CS is connected to CE0, the display is available on SPI port 0 by default. Connect CS to CE1 to use port 1 instead, then pass port=1 in your interface call.

​
4-wire vs 3-wire SPI

The terms “4-wire” and “3-wire” SPI can be confusing in this context. In standard SPI documentation they refer to whether MOSI and MISO are separate or combined. For OLED controllers, the meaning is different:
  • 4-wire SPI: MOSI carries data, and the Data/Command signal is sent out-of-band on a separate GPIO pin (DC). This is the mode supported by luma.oled.
  • 3-wire SPI: The Data/Command signal is sent as an extra bit over MOSI, requiring no separate DC pin.

​
Initialize the interface in Python

from luma.core.interface.serial import spi

serial = spi(device=0, port=0)

Build docs developers (and LLMs) love

Get started for freeTalk to us