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.

Device classes in luma.oled wrap a serial interface and translate high-level drawing operations into the command sequences required by each OLED controller. Every class accepts a serial interface instance as its first argument, along with optional parameters for display dimensions and rotation. Once instantiated, the device exposes a display() method and integrates with luma.core.render.canvas for drawing.
Serial interface to a monochrome SSD1305 OLED display. The SSD1305 does not include an internal charge pump, so an external VCC supply must be provided. Supported resolutions are 128×64 and 128×32, with a column start offset of 4 in 128×32 mode.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"32"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×64, 128×32
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1305

serial = i2c(port=1, address=0x3C)
device = ssd1305(serial, width=128, height=32)
Serial interface to a monochrome SSD1306 OLED display. This is the most widely used OLED controller and supports five distinct display resolutions. The initialization sequence configures charge pump, memory mode, segment remap, and contrast automatically.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×64, 128×32, 96×16, 64×48, 64×32
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306

serial = i2c(port=1, address=0x3C)
device = ssd1306(serial)
Serial interface to a monochrome SSD1309 OLED display. The SSD1309 is command-set compatible with the SSD1306 and inherits its initialization logic. SPI is the preferred interface for this controller.
​
serial_interface
object
required
The serial interface instance (spi preferred) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×64, 128×32, 96×16, 64×48, 64×32
from luma.core.interface.serial import spi
from luma.oled.device import ssd1309

serial = spi(device=0, port=0)
device = ssd1309(serial)
Serial interface to a monochrome SSD1315 OLED display. The SSD1315 is command-set compatible with the SSD1306 and reuses its initialization sequence. Added in version 3.15.0.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×64, 128×32, 96×16, 64×48, 64×32
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1315

serial = i2c(port=1, address=0x3C)
device = ssd1315(serial)
Serial interface to a monochrome SSD1316 OLED display. Defaults to a 128×32 resolution. Added in version 3.15.0.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"32"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×32
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1316

serial = i2c(port=1, address=0x3C)
device = ssd1316(serial)
Serial interface to a 4-bit greyscale SSD1322 OLED display. Accepts either "1" (monochrome) or "RGB" mode; RGB images are converted to 4-bit greyscale using the luma formula Y' = 0.299R' + 0.587G' + 0.114B'. The framebuffer parameter controls rendering strategy.
​
serial_interface
object
required
The serial interface instance (spi) used to send data and commands to the display.
​
width
int
default:"256"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
mode
str
default:"\"RGB\""
Rendering mode. "RGB" enables 4-bit greyscale; "1" renders as monochrome.
​
framebuffer
object
default:"None"
Framebuffering strategy. Supports diff_to_previous or full_frame instances.
Supported dimensions: 256×64, 256×48, 256×32, 128×64, 128×48, 128×32, 64×64, 64×48, 64×32
from luma.core.interface.serial import spi
from luma.oled.device import ssd1322

serial = spi(device=0, port=0)
device = ssd1322(serial, width=256, height=64)
NHD variant of the SSD1322 controller. Width, height, and framebuffer are fixed at 128×64 with full_frame() — these values cannot be overridden. Rendering and command protocol are adapted for the NHD module’s dual-SEG layout.
​
serial_interface
object
required
The serial interface instance (spi) used to send data and commands to the display.
​
width
int
default:"128"
Fixed at 128; other values are ignored.
​
height
int
default:"64"
Fixed at 64; other values are ignored.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
mode
str
default:"\"RGB\""
Rendering mode. "RGB" enables 4-bit greyscale; "1" renders as monochrome.
Supported dimensions: 128×64 (fixed)
from luma.core.interface.serial import spi
from luma.oled.device import ssd1322_nhd

serial = spi(device=0, port=0)
device = ssd1322_nhd(serial)
Serial interface to a 4-bit greyscale SSD1325 OLED display. Supports monochrome or greyscale rendering controlled by the mode parameter. Only the 128×64 resolution is supported.
​
serial_interface
object
required
The serial interface instance (spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
mode
str
default:"\"RGB\""
Rendering mode. "RGB" enables 4-bit greyscale; "1" renders as monochrome.
​
framebuffer
object
default:"None"
Framebuffering strategy. Supports diff_to_previous or full_frame instances.
Supported dimensions: 128×64
from luma.core.interface.serial import spi
from luma.oled.device import ssd1325

serial = spi(device=0, port=0)
device = ssd1325(serial)
Serial interface to a 4-bit greyscale SSD1327 OLED display. The SSD1327 produces a square 128×128 display with 16 greyscale levels. Added in version 2.4.0.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"128"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
mode
str
default:"\"RGB\""
Rendering mode. "RGB" enables 4-bit greyscale; "1" renders as monochrome.
​
framebuffer
object
default:"None"
Framebuffering strategy. Supports diff_to_previous or full_frame instances.
Supported dimensions: 128×128
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1327

serial = i2c(port=1, address=0x3C)
device = ssd1327(serial)
Serial interface to a 16-bit color (5-6-5 RGB) SSD1331 OLED display. 24-bit RGB images are downsampled to 16-bit 565 format before transmission. Only the 96×64 resolution is supported.
​
serial_interface
object
required
The serial interface instance (spi) used to send data and commands to the display.
​
width
int
default:"96"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
framebuffer
object
default:"None"
Framebuffering strategy. Supports diff_to_previous or full_frame instances.
Supported dimensions: 96×64
from luma.core.interface.serial import spi
from luma.oled.device import ssd1331

serial = spi(device=0, port=0)
device = ssd1331(serial)
Serial interface to the 16-bit color (5-6-5 RGB) SSD1351 OLED display. Supports optional BGR pixel order and horizontal/vertical memory offsets to compensate for panel-to-controller misalignment. Added in version 2.3.0.
​
serial_interface
object
required
The serial interface instance (spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"128"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
framebuffer
object
default:"None"
Framebuffering strategy. Supports diff_to_previous or full_frame instances.
​
h_offset
int
default:"0"
Horizontal pixel offset from screen coordinates to device memory.
​
v_offset
int
default:"0"
Vertical pixel offset from screen coordinates to device memory.
​
bgr
bool
default:"False"
Set to True if the device panel uses BGR pixel order instead of RGB.
Supported dimensions: 128×128, 128×96, 96×96
from luma.core.interface.serial import spi
from luma.oled.device import ssd1351

serial = spi(device=0, port=0)
device = ssd1351(serial)
Serial interface to a 4-bit greyscale SSD1362 OLED display. Supports monochrome or greyscale rendering. Only the 256×64 resolution is supported. Added in version 3.4.0.
​
serial_interface
object
required
The serial interface instance (spi) used to send data and commands to the display.
​
width
int
default:"256"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
mode
str
default:"\"RGB\""
Rendering mode. "RGB" enables 4-bit greyscale; "1" renders as monochrome.
​
framebuffer
object
default:"None"
Framebuffering strategy. Supports diff_to_previous or full_frame instances.
Supported dimensions: 256×64
from luma.core.interface.serial import spi
from luma.oled.device import ssd1362

serial = spi(device=0, port=0)
device = ssd1362(serial)
Serial interface to a monochrome SH1106 OLED display. The SH1106 uses page-addressing mode rather than horizontal addressing, so each page is written independently. If you use the ssd1306 driver on a display with an SH1106 controller, you will see corrupted output — always use this class when your display is SH1106-based.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels.
​
height
int
default:"64"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×128, 128×64, 128×32
from luma.core.interface.serial import i2c
from luma.oled.device import sh1106

serial = i2c(port=1, address=0x3C)
device = sh1106(serial)
Serial interface to a monochrome SH1107 OLED display. This controller is typically used in portrait-oriented modules where the height exceeds the width. The SH1107 uses page-addressing mode and supports 64×128, 80×128, and 128×128 pixel configurations. Added in version 3.11.0.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"64"
Number of horizontal pixels.
​
height
int
default:"128"
Number of vertical pixels.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 64×128, 80×128, 128×128
from luma.core.interface.serial import i2c
from luma.oled.device import sh1107

serial = i2c(port=1, address=0x3C)
device = sh1107(serial)
Serial interface to a monochrome Winstar WS0010 OLED display. This is a fully graphical device that also supports character-based operations via the text property. It includes four embedded font tables (FT00–FT11) in two sizes (5×8 and 5×10 pixels) and requires a parallel interface. Added in version 3.6.0.
​
serial_interface
object
required
The serial interface instance (bitbang_6800 parallel) used to send data and commands to the display.
​
width
int
default:"100"
Number of horizontal pixels. Supported widths: 40, 60, 80, 100.
​
height
int
default:"16"
Number of vertical pixels. Supported heights: 8, 16.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
​
selected_font
int or str
default:"0"
Select one of the embedded font tables by index (0–7) or name (e.g. 'FT00', 'FT01').
​
font
object
default:"None"
Override the internal font by providing a PIL.ImageFont object.
​
exec_time
float
default:"50e-6"
Time in seconds to wait after each command. Default is 50 µs.
Supported dimensions: 40×8, 40×16, 60×8, 60×16, 80×8, 80×16, 100×8, 100×16
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, selected_font='FT01')
device.text = 'Hello World\nLine 2'
Character-mode variant of the WS0010 driver for Winstar WEH displays. Width and height are given in characters (columns × lines), not pixels — internally each character cell is 5 pixels wide and 8 pixels tall. The text property accepts newline-separated strings. Added in version 3.6.0.
​
serial_interface
object
required
The serial interface instance (bitbang_6800 parallel) used to send data and commands to the display.
​
width
int
default:"16"
Number of character columns (e.g. 16 for the WEH001602A).
​
height
int
default:"2"
Number of character lines (e.g. 2 for the WEH001602A).
Supported dimensions: 16×2 characters (WEH001602A), and other WS0010-based character modules
from luma.core.interface.parallel import bitbang_6800
from luma.oled.device import winstar_weh

serial = bitbang_6800(RS=7, E=8, PINS=[25, 24, 23, 27])
device = winstar_weh(serial, width=16, height=2)
device.text = 'Hello\nWorld'
Serial interface to a monochrome CH1115 OLED display (128×64 only). The CH1115 is largely command-compatible with the SSD1306 but includes a built-in DC-DC converter enabled via a CH1115-specific control byte (0xAD, 0x8B). Only 128×64 is supported. Added in version 3.15.0.
​
serial_interface
object
required
The serial interface instance (i2c or spi) used to send data and commands to the display.
​
width
int
default:"128"
Number of horizontal pixels. Only 128 is supported.
​
height
int
default:"64"
Number of vertical pixels. Only 64 is supported.
​
rotate
int
default:"0"
Rotation: 0 = none, 1 = 90° CW, 2 = 180°, 3 = 270°.
Supported dimensions: 128×64
from luma.core.interface.serial import i2c
from luma.oled.device import ch1115

serial = i2c(port=1, address=0x3C)
device = ch1115(serial)

Build docs developers (and LLMs) love

Get started for freeTalk to us