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.
Interface classes act as the communication layer between luma.oled device drivers and physical hardware. Each interface wraps the underlying bus protocol and exposes a uniform command() and data() API consumed by all device classes. The interfaces themselves live in luma.core rather than luma.oled, so they are shared across the entire luma ecosystem.
All interface classes shown here are provided by the luma.core package (luma.core.interface.serial and luma.core.interface.parallel), not by luma.oled itself. Install luma.core>=2.4.1 to use them.
i2c
spi
pcf8574
bitbang_6800
The I2C interface connects to an OLED display over the two-wire I2C bus. This is the simplest setup and requires no chip-select or data/command pin. Most SSD1306, SH1106, and similar displays default to I2C address 0x3C.The I2C bus number. Use port=0 on original Raspberry Pi rev.1 boards; port=1 on all others.
The 7-bit I2C address of the display. Common values are 0x3C and 0x3D.
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306
serial = i2c(port=1, address=0x3C)
device = ssd1306(serial)
The SPI interface connects to an OLED display over a four-wire SPI bus. SPI is required for higher-speed or larger displays (e.g. SSD1322, SSD1331, SSD1351). The gpio_DC and gpio_RST pins must be connected to the display’s D/C and RST lines respectively.The SPI chip-select device number (CE0 = 0, CE1 = 1).
BCM GPIO pin number connected to the display’s data/command (D/C) line.
BCM GPIO pin number connected to the display’s reset (RST) line.
from luma.core.interface.serial import spi
from luma.oled.device import ssd1331
serial = spi(device=0, port=0, gpio_DC=24, gpio_RST=25)
device = ssd1331(serial)
The PCF8574 interface drives an OLED (or other display) through a PCF8574 I2C GPIO expander. This is useful when direct I2C connections to the display are not available but an I2C expander is present on the bus.The I2C bus number the PCF8574 expander is connected to.
The 7-bit I2C address of the PCF8574 expander chip.
from luma.core.interface.serial import pcf8574
from luma.oled.device import ssd1306
serial = pcf8574(i2c_port=1, address=0x27)
device = ssd1306(serial)
The bitbang_6800 parallel interface implements the Motorola 6800-style parallel bus in software (bit-banging). It is required for parallel-interface displays such as the ws0010 and winstar_weh. The PINS list provides the 4- or 8-bit data bus GPIO pin numbers.BCM GPIO pin number for the Register Select (RS) line.
BCM GPIO pin number for the Enable (E) strobe line.
PINS
list
default:"[25, 24, 23, 27]"
List of BCM GPIO pin numbers for the data bus (D4–D7 in 4-bit mode, or D0–D7 in 8-bit mode).
from luma.core.interface.parallel import bitbang_6800
from luma.oled.device import ws0010
serial = bitbang_6800(RS=7, E=8, PINS=[25, 24, 23, 27])
device = ws0010(serial)
device.text = 'Hello World\nLine 2'