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.
Different OLED controllers support different color depths. luma.oled handles the conversion automatically — you draw with standard Pillow color values and the library downsizes the image to match what the hardware can display. The behavior depends on which device class you are using.
Monochrome
Color (RGB)
Greyscale
Monochrome displays
Supported devices: SSD1305, SSD1306, SSD1309, SSD1315, SSD1316, SH1106, SH1107, WS0010, CH1115These displays are strictly black and white. Any color value other than black is treated as white. Use the HTML color names "black" and "white" for clarity.with canvas(device) as draw:
draw.rectangle(device.bounding_box, outline="white", fill="black")
draw.text((30, 40), "Hello World", fill="white")
Dithering
If you want to render a color image on a monochrome display, set dither=True on the canvas. luma.oled will convert the color drawing to a dithered monochrome effect:with canvas(device, dither=True) as draw:
draw.rectangle((10, 10, 30, 30), outline="white", fill="red")
Any PIL.ImageColor format is accepted — but on monochrome hardware, only black vs. non-black is meaningful unless you enable dithering.
Color displays
Supported devices: SSD1331, SSD1351These controllers support 16-bit RGB color in a 5-6-5 format (5 bits red, 6 bits green, 5 bits blue). When you draw with 24-bit RGB values, luma.oled automatically downsizes them to 16-bit using the 565 scheme:# color.py — display() method (simplified)
buf[i] = r & 0xF8 | g >> 5
buf[i + 1] = g << 3 & 0xE0 | b >> 3
with canvas(device) as draw:
draw.rectangle((0, 0, 47, 63), fill="navy")
draw.rectangle((48, 0, 95, 63), fill="firebrick")
draw.text((10, 28), "Color!", fill="yellow")
PIL.ImageColor formats — including hex codes ("#FF8800"), RGB tuples, and named colors — are all valid.Greyscale displays
Supported devices: SSD1322, SSD1325, SSD1327, SSD1362These controllers support 4-bit greyscale, giving 16 distinct shades from black to white. When you supply a 24-bit RGB image, luma.oled converts it to greyscale using the standard luma formula:Y' = 0.299 R' + 0.587 G' + 0.114 B'
Rendering modes
Pass a mode parameter when creating the device to choose the rendering strategy:from luma.oled.device import ssd1322
# Default: 4-bit greyscale rendering from RGB input
device = ssd1322(serial, mode="RGB")
# Monochrome rendering: treats image as strictly black/white
device = ssd1322(serial, mode="1")
mode="RGB" (the default), draw with any color and the device will render the luminance equivalent as a shade of grey. With mode="1", the device behaves like a monochrome display.All PIL.ImageColor standard color formats are accepted. On greyscale displays, color values are mapped to their luminance equivalent using the Y’ formula above.