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.

Once luma.oled is installed and your display is wired up, you can have content on screen in fewer than ten lines of Python. This guide walks through connecting to a display over I2C, initializing the ssd1306 device driver, and drawing a rectangle and text using the Pillow-compatible canvas.
1

Import the required modules

Import the interface class for your connection type, the canvas renderer, and the device class that matches your display’s controller chip.
from luma.core.interface.serial import i2c, spi, pcf8574
from luma.core.interface.parallel import bitbang_6800
from luma.core.render import canvas
from luma.oled.device import ssd1306, ssd1309, ssd1325, ssd1331, sh1106, sh1107, ws0010
You only need to import the interface and device classes you actually use. The example above imports all available options for reference.
2

Create the serial interface

Instantiate the interface class that matches how your display is connected to the board. This example uses I2C on port 1 at the default address 0x3C.
# rev.1 Raspberry Pi users set port=0
serial = i2c(port=1, address=0x3C)
If your display uses SPI instead, pass spi(device=0, port=0) to the device constructor in the next step. For 6800-style parallel, use bitbang_6800(RS=7, E=8, PINS=[25,24,23,27]).
3

Initialize the device

Pass the serial interface to the device constructor for your controller chip. This sends the required initialization sequence to the display.
device = ssd1306(serial)
Substitute ssd1331, sh1106, ssd1309, or another class if you are using a different controller. See the device reference for the full list.
4

Draw with the canvas

Use the canvas context manager to open a drawing surface. Inside the with block, call Pillow’s ImageDraw methods to render content.
with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")
    draw.text((30, 40), "Hello World", fill="white")
When the with block exits, the canvas is automatically flushed to the display’s memory. You do not need to call a separate display() or show() method.

​
Complete example

Here is the full working script combining all of the steps above: 
from luma.core.interface.serial import i2c
from luma.core.render import canvas
from luma.oled.device import ssd1306

# rev.1 users set port=0
serial = i2c(port=1, address=0x3C)
device = ssd1306(serial)

with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")
    draw.text((30, 40), "Hello World", fill="white")
When your program ends, the display is cleared automatically. If your script runs very quickly, the image may not be visible long enough to see. Add a time.sleep() call after the with block to keep the content on screen.
The luma.examples repository contains a large collection of ready-to-run scripts covering clocks, animations, system stats, and more. Clone it and run the examples directly after your installation is working.

​
Next steps

  • Drawing guide — render text, images, and shapes using the full canvas API
  • Color and greyscale — use color on SSD1331/SSD1351 or greyscale on SSD1322/SSD1325
  • Orientation — rotate the display output in software

Build docs developers (and LLMs) love

Get started for freeTalk to us