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.

You do not need physical hardware to develop with luma.oled. The luma.emulator package provides drop-in replacements for real device classes, so you can write and test your display code on any machine with a screen or filesystem.

​
Available emulators

The package ships three emulator backends:
  • pygame — opens a real-time window that mirrors what the OLED would show, refreshed at a configurable frame rate
  • capture — saves each frame as a PNG screenshot to disk
  • gifanim — records frames and writes an animated GIF when the program exits

​
Installation

pip install luma.emulator

​
Using an emulator

Emulator devices expose the exact same API as physical devices. Swap the import and constructor call — everything else in your code stays the same: 
from luma.emulator.device import pygame

# Use pygame() instead of ssd1306(serial)
device = pygame(width=128, height=64, rotate=0, mode="RGB", transform="scale2x", scale=2, frame_rate=60)
Then draw to device exactly as you would with real hardware: 
from luma.core.render import canvas

with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")
    draw.text((30, 40), "Hello World", fill="white")
No serial interface, no I2C address, no GPIO — the emulator handles everything internally.
The luma.examples repository contains many working demonstration scripts. Each example runs against real hardware or any emulator backend without modification — it is the fastest way to see luma.oled in action.

Build docs developers (and LLMs) love

Get started for freeTalk to us