tessl/pypi-luma-oled

Display drivers for SSD1306/SSD1309/SSD1322/SSD1325/SSD1327/SSD1331/SSD1351/SSD1362/SH1106/SH1107/WS0010 OLED matrix displays

—

Pending

Overview

Eval results

Files

Monochrome Displays

Name: tessl/pypi-luma-oled
Author: tessl

Single-color OLED displays that support 1-bit monochrome rendering. These displays typically show white, blue, or yellow pixels on a black background, providing crisp text and graphics with high contrast.

Capabilities

SSD1306 Display

Serial interface to a monochrome SSD1306 OLED display, one of the most common OLED controllers supporting multiple resolution configurations.

class ssd1306:
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, **kwargs):
        """
        Initialize SSD1306 OLED display.

        Parameters:
        - serial_interface: Serial interface (usually luma.core.interface.serial.i2c)
        - width: Number of horizontal pixels (default: 128)
        - height: Number of vertical pixels (default: 64)
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
        """

    def display(self, image):
        """
        Display a 1-bit PIL Image on the OLED.

        Parameters:
        - image: PIL.Image in mode "1" (1-bit monochrome)
        
        The image size must exactly match the display dimensions.
        """

Supported Resolutions: (128,64), (128,32), (96,16), (64,48), (64,32)

Usage example:

from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306
from luma.core.render import canvas

# Initialize device
serial = i2c(port=1, address=0x3C)
device = ssd1306(serial, width=128, height=64)

# Draw content
with canvas(device) as draw:
    draw.text((0, 0), "SSD1306 Display", fill="white")
    draw.rectangle((10, 20, 50, 40), outline="white")

SSD1309 Display

Serial interface to a monochrome SSD1309 OLED display, compatible with SSD1306 but optimized for SPI communication.

class ssd1309(ssd1306):
    """
    Inherits all functionality from ssd1306.
    
    Optimized for SPI communication but maintains full API compatibility.
    Constructor parameters and methods identical to ssd1306.
    """

Supported Resolutions: Same as SSD1306

Usage example:

from luma.core.interface.serial import spi
from luma.oled.device import ssd1309

# Initialize with SPI interface
serial = spi(port=0, device=0, bus_speed_hz=8000000)
device = ssd1309(serial, width=128, height=64)

SH1106 Display

Serial interface to a monochrome SH1106 OLED display with different memory organization than SSD1306, requiring specialized display logic.

class sh1106:
    def __init__(self, serial_interface=None, width=128, height=64, rotate=0, **kwargs):
        """
        Initialize SH1106 OLED display.

        Parameters:
        - serial_interface: Serial interface (usually luma.core.interface.serial.i2c)
        - width: Number of horizontal pixels (default: 128)
        - height: Number of vertical pixels (default: 64)
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
        """

    def display(self, image):
        """
        Display a 1-bit PIL Image on the SH1106 OLED.

        Parameters:
        - image: PIL.Image in mode "1" (1-bit monochrome)
        """

Supported Resolutions: (128,128), (128,64), (128,32)

Usage example:

from luma.core.interface.serial import i2c
from luma.oled.device import sh1106

# Initialize device - note different default resolution
serial = i2c(port=1, address=0x3C)
device = sh1106(serial, width=128, height=128)

with canvas(device) as draw:
    draw.ellipse((10, 10, 118, 118), outline="white")

SH1107 Display

Serial interface to a monochrome SH1107 OLED display with portrait orientation as default and specialized memory mapping.

class sh1107:
    def __init__(self, serial_interface=None, width=64, height=128, rotate=0, **kwargs):
        """
        Initialize SH1107 OLED display.

        Parameters:
        - serial_interface: Serial interface (usually luma.core.interface.serial.i2c)
        - width: Number of horizontal pixels (default: 64)
        - height: Number of vertical pixels (default: 128)
        - rotate: Rotation value 0-3 (0°, 90°, 180°, 270°) (default: 0)
        
        Note: Default orientation is portrait (64x128)
        """

    def display(self, image):
        """
        Display a 1-bit PIL Image on the SH1107 OLED.

        Parameters:
        - image: PIL.Image in mode "1" (1-bit monochrome)
        """

Supported Resolutions: (64,128), (80,128), (128,128)

Usage example:

from luma.core.interface.serial import i2c
from luma.oled.device import sh1107

# Initialize with portrait orientation
serial = i2c(port=1, address=0x3C)
device = sh1107(serial)  # Uses default 64x128

with canvas(device) as draw:
    # Portrait-oriented content
    draw.text((5, 10), "Portrait", fill="white")
    draw.text((5, 30), "Display", fill="white")
    draw.rectangle((5, 50, 59, 100), outline="white")

Common Patterns

Error Handling

All monochrome displays will raise luma.core.error.DeviceDisplayModeError if an unsupported resolution is specified:

from luma.oled.device import ssd1306
import luma.core.error

try:
    device = ssd1306(serial, width=200, height=200)  # Unsupported
except luma.core.error.DeviceDisplayModeError as e:
    print(f"Unsupported display mode: {e}")

Image Requirements

All monochrome displays require 1-bit PIL Images:

from PIL import Image

# Create compatible image
img = Image.new("1", (128, 64), color=0)  # Black background
# Draw to image...
device.display(img)

Memory and Performance

Use luma.core.framebuffer.diff_to_previous() (default) for efficient updates
Use luma.core.framebuffer.full_frame() for guaranteed complete refreshes
Canvas context manager automatically handles framebuffer optimization

Install with Tessl CLI

npx tessl i tessl/pypi-luma-oled

docs

character-displays.md

color-displays.md

greyscale-displays.md

index.md

interfaces.md

monochrome-displays.md

tile.json

tessl/pypi-luma-oled