or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

apa102.mdconstants.mdindex.mdmax7219.mdneopixel.mdsevensegment.mdunicornhathd.md
tile.json

tessl/pypi-luma--led-matrix

A Python library to drive MAX7219 LED matrices, WS2812 NeoPixels, and APA102 DotStar LEDs on Raspberry Pi

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/luma.led-matrix@1.7.x

To install, run

npx @tessl/cli install tessl/pypi-luma--led-matrix@1.7.0

index.mddocs/

Luma LED Matrix

A Python library for interfacing with LED matrix displays, specifically targeting MAX7219 driver-based LED matrices, WS2812 NeoPixels, and APA102 DotStar LEDs on Raspberry Pi and other Linux-based single board computers. The library provides a Pillow-compatible drawing canvas with support for multiple cascaded devices, various display types, and advanced features like scrolling and terminal-style printing.

Package Information

  • Package Name: luma.led_matrix
  • Language: Python
  • Installation: pip install luma.led_matrix
  • Dependencies: luma.core, rpi_ws281x (for NeoPixel support)

Core Imports

from luma.led_matrix.device import max7219, neopixel, ws2812, apa102, neosegment, unicornhathd

Device constants:

from luma.led_matrix.const import max7219 as max7219_const

Segment mapping functions:

from luma.led_matrix.segment_mapper import regular, dot_muncher

Required core imports for basic usage:

from luma.core.interface.serial import spi, noop
from luma.core.render import canvas

Basic Usage

MAX7219 LED Matrix

from luma.core.interface.serial import spi, noop
from luma.led_matrix.device import max7219
from luma.core.render import canvas

# Create serial interface and device
serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial, width=8, height=8)

# Draw on the device
with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")
    draw.text((1, 1), "Hi", fill="white")

NeoPixel (WS2812) LEDs

from luma.led_matrix.device import neopixel
from luma.core.render import canvas

# Create device (auto-detects interface)
device = neopixel(width=8, height=4)

# Draw colorful patterns
with canvas(device) as draw:
    draw.point((0, 0), fill="red")
    draw.point((1, 0), fill="green")
    draw.point((2, 0), fill="blue")

Seven-Segment Display

from luma.led_matrix.device import neosegment

# Create 4-digit seven-segment display
device = neosegment(width=4)
device.text = "1234"

Architecture

The library follows the luma.core architecture pattern:

  • Device Classes: Hardware-specific display drivers (max7219, ws2812, apa102, etc.)
  • Serial Interfaces: Communication protocols (SPI, bitbang, DMA) from luma.core
  • Canvas Rendering: Pillow-compatible drawing context for cross-device compatibility
  • Virtual Devices: Higher-level abstractions like seven-segment displays built on top of basic devices

Each device inherits from luma.core.device.device and implements the standard display interface, allowing consistent usage patterns across different hardware types.

Capabilities

MAX7219 LED Matrix Driver

LED matrix display driver for MAX7219 chips supporting cascaded displays, rotation, block orientation, and brightness control.

class max7219:
    def __init__(
        self,
        serial_interface=None,
        width=8,
        height=8,
        cascaded=None,
        rotate=0,
        block_orientation=0,
        blocks_arranged_in_reverse_order=False,
        contrast=0x70
    ): ...
    
    def display(self, image): ...
    def contrast(self, value): ...
    def show(self): ...
    def hide(self): ...
    def clear(self): ...
    def data(self, values): ...
    def preprocess(self, image): ...

MAX7219 LED Matrix

NeoPixel (WS2812) RGB LEDs

RGB LED strip and matrix driver supporting WS281x chips with DMA interface for smooth animations and color control.

class neopixel:
    def __init__(
        self,
        dma_interface=None,
        width=8,
        height=4,
        cascaded=None,
        rotate=0,
        mapping=None
    ): ...
    
    def display(self, image): ...
    def contrast(self, value): ...
    def show(self): ...
    def hide(self): ...
    def clear(self): ...
    def cleanup(self): ...
# ws2812 is the same as neopixel
ws2812 = neopixel

NeoPixel RGB LEDs

APA102 DotStar LEDs

APA102/DotStar LED driver supporting SPI and bitbang interfaces with individual brightness control via alpha channel.

class apa102:
    def __init__(
        self,
        serial_interface=None,
        width=8,
        height=1,
        cascaded=None,
        rotate=0,
        mapping=None
    ): ...
    
    def display(self, image): ...
    def contrast(self, value): ...
    def show(self): ...
    def hide(self): ...
    def clear(self): ...

APA102 DotStar LEDs

Seven-Segment Display

Virtual seven-segment display device built on top of NeoPixel hardware for displaying text and numbers.

class neosegment:
    def __init__(
        self,
        width,
        undefined="_",
        device=None
    ): ...
    
    @property
    def text(self): ...
    
    @text.setter
    def text(self, value): ...
    
    @property
    def color(self): ...
    
    @color.setter  
    def color(self, value): ...
    
    def segment_mapper(self, text, notfound): ...

Seven-Segment Display

Unicorn HAT HD

Specialized driver for Pimoroni's Unicorn HAT HD (16x16 RGB LED matrix) with SPI interface.

class unicornhathd:
    def __init__(
        self,
        serial_interface,
        rotate=0
    ): ...
    
    def display(self, image): ...
    def contrast(self, value): ...
    def show(self): ...
    def hide(self): ...

Unicorn HAT HD

Hardware Constants and Segment Mapping

Hardware register constants for MAX7219 and character-to-segment mapping utilities for seven-segment displays.

class max7219:
    NOOP = 0x00
    DIGIT_0 = 0x01
    DECODEMODE = 0x09
    INTENSITY = 0x0A
    SCANLIMIT = 0x0B
    SHUTDOWN = 0x0C
    DISPLAYTEST = 0x0F
def regular(text, notfound="_"): ...
def dot_muncher(text, notfound="_"): ...

Constants and Utilities

Types

# Pixel mapping type for non-standard layouts
PixelMapping = list[int]

# Color specification (RGB tuple or color name)
Color = tuple[int, int, int] | str

# Device rotation angles
Rotation = 0 | 1 | 2 | 3  # 0°, 90°, 180°, 270°

# Block orientation for MAX7219
BlockOrientation = 0 | 90 | -90 | 180

# Image modes supported by different devices
ImageMode = "1" | "RGB" | "RGBA"  # 1-bit monochrome, 24-bit RGB, 32-bit RGBA

# Serial interface types (from luma.core)
SerialInterface = object  # SPI, bitbang, or noop interface objects

# DMA interface for WS281x devices
DMAInterface = object  # WS281x DMA interface object

# Exception types that can be raised
DeviceDisplayModeError = Exception  # Invalid display dimensions or mode