Python Usage¶

8x8 LED Matrices¶

For the matrix device, initialize the luma.led_matrix.device.max7219 class, as follows:

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

serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial)

The display device should now be configured for use. The specific max7219 class exposes a display() method which takes an image with attributes consistent with the capabilities of the configured device’s capabilities. However, for most cases, for drawing text and graphics primitives, the canvas class should be used as follows:

from PIL import ImageFont

font = ImageFont.truetype("examples/pixelmix.ttf", 8)

with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")

The luma.core.render.canvas class automatically creates an PIL.ImageDraw object of the correct dimensions and bit depth suitable for the device, so you may then call the usual Pillow methods to draw onto the canvas.

As soon as the with scope is ended, the resultant image is automatically flushed to the device’s display memory and the PIL.ImageDraw object is garbage collected.

Note

The default Pillow font is too big for 8px high devices like the LED matrices here, so the luma.examples repo inclues a small TTF pixel font called pixelmix.ttf (attribution: http://www.dafont.com/) which just fits.

Alternatively, a set of “legacy” fixed-width bitmap fonts are included in the luma.core codebase and may be used as follows:

from luma.core.legacy import text
from luma.core.legacy.font import proportional, CP437_FONT, LCD_FONT

with canvas(device) as draw:
    text(draw, (0, 0), "A", fill="white", font=proportional(CP437_FONT))

The fixed-width fonts can be “converted” on-the-fly to proportionally spaced by wrapping them with the luma.core.legacy.font.proportional class.

Scrolling / Virtual viewports¶

A single 8x8 LED matrix clearly hasn’t got a lot of area for displaying useful information. Obviously they can be daisy-chained together to provide a longer line of text, but as this library extends luma.core, then we can use the luma.core.virtual.viewport class to allow scrolling support:

import time

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

serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial)

virtual = viewport(device, width=200, height=100)

with canvas(virtual) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")
    draw.text((3, 3), "Hello world", fill="white")

for offset in range(8):
    virtual.set_position((offset, offset))
    time.sleep(0.1)

Calling set_position() on a virtual viewport, causes the device to render what is visible at that specific position; altering the position in a loop refreshes every time it is called, and gives an animated scrolling effect.

By altering both the X and Y co-ordinates allows scrolling in any direction, not just horizontally.

Color Model¶

Any of the standard PIL.ImageColor color formats may be used, but since the 8x8 LED Matrices are monochrome, only the HTML color names "black" and "white" values should really be used; in fact, by default, any value other than black is treated as white. The luma.core.render.canvas constructor does have a dither flag which if set to True, will convert color drawings to a dithered monochrome effect.

with canvas(device, dither=True) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="red")

Landscape / Portrait Orientation¶

By default, cascaded matrices will be oriented in landscape mode. Should you have an application that requires the display to be mounted in a portrait aspect, then add a rotate=N parameter when creating the device:

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

serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial, rotate=1)

# Box and text rendered in portrait mode
with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")

N should be a value of 0, 1, 2 or 3 only, where 0 is no rotation, 1 is rotate 90° clockwise, 2 is 180° rotation and 3 represents 270° rotation.

The device.size, device.width and device.height properties reflect the rotated dimensions rather than the physical dimensions.

Daisy-chaining¶

The MAX7219 chipset supports a serial 16-bit register/data buffer which is clocked in on pin DIN every time the clock edge falls, and clocked out on DOUT 16.5 clock cycles later. This allows multiple devices to be chained together.

If you have more than one device and they are daisy-chained together, you can initialize the library in one of two ways, either using cascaded=N to indicate the number of daisychained devices:

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

serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial, cascaded=3)

with canvas(device) as draw:
   draw.rectangle(device.bounding_box, outline="white", fill="black")

Using cascaded=N implies there are N devices arranged linearly and horizontally, running left to right.

Alternatively, the device configuration may configured with width=W and height=H. These dimensions denote the number of LEDs in the all the daisychained devices. The width and height must both be multiples of 8: this has scope for arranging in blocks in, say 3x3 or 5x2 matrices (24x24 or 40x16 pixels, respectively).

Given 12 daisychained MAX7219’s arranged in a 4x3 layout, the simple example below,

from luma.core.interface.serial import spi, noop
from luma.core.render import canvas
from luma.core.legacy import text
from luma.core.legacy.font import proportional, LCD_FONT
from luma.led_matrix.device import max7219

serial = spi(port=0, device=0, gpio=noop(), block_orientation=-90)
device = max7219(serial, width=32, height=24)

with canvas(device) as draw:
   draw.rectangle(device.bounding_box, outline="white")
   text(draw, (2, 2), "Hello", fill="white", font=proportional(LCD_FONT))
   text(draw, (2, 10), "World", fill="white", font=proportional(LCD_FONT))

displays as:

Trouble-shooting / common problems¶

Some online retailers are selling pre-assembled ‘4-in-1’ LED matrix displays, but they appear to be wired 90° out-of-phase such that horizontal scrolling appears as below:

This can be rectified by initializing the max7219 device with a parameter of block_orientation=-90 (or +90, if your device is aligned the other way):

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

serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial, cascaded=4, block_orientation=-90)

Every time a display render is subsequenly requested, the underlying image representation is corrected to reverse the 90° phase shift.

Similarly, in other pre-assembled configurations, the 4-in-1 blocks arrange the 8x8 blocks in reverse order. In that case, you need to pass a True value to parameter blocks_arranged_in_reverse_order, requesting an additional pre-processing step that fixes this:

...
device = max7219(serial, cascaded=4, block_orientation=-90,
                 blocks_arranged_in_reverse_order=True)

7-Segment LED Displays¶

For the 7-segment device, initialize the luma.core.virtual.sevensegment class, and wrap it around a previously created max7219 device:

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

serial = spi(port=0, device=0, gpio=noop())
device = max7219(serial, cascaded=2)
seg = sevensegment(device)

The seg instance now has a text property which may be assigned, and when it does will update all digits according to the limited alphabet the 7-segment displays support. For example, assuming there are 2 cascaded modules, we have 16 character available, and so can write:

seg.text = "Hello world"

Rather than updating the whole display buffer, it is possible to update ‘slices’, as per the below example:

seg.text[0:5] = "Goodbye"

This replaces Hello in the previous example, replacing it with Gooobye. The usual python idioms for slicing (inserting / replacing / deleteing) can be used here, but note if inserted text exceeds the underlying buffer size, a ValueError is raised.

Floating point numbers (or text with ‘.’) are handled slightly differently - the decimal-place is fused in place on the character immediately preceding it. This means that it is technically possible to get more characters displayed than the buffer allows, but only because dots are folded into their host character

WS2812 NeoPixels¶

For a strip of neopixels, initialize the luma.led_matrix.device.ws2812 class (also aliased to luma.led_matrix.device.neopixel), supplying a parameter cascaded=N where N is the number of daisy-chained LEDs.

This script creates a drawing surface 100 pixels long, and lights up three specific pixels, and a contiguous block:

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

device = ws2812(cascaded=100)

with canvas(device) as draw:
    draw.point((0,0), fill="white")
    draw.point((4,0), fill="blue")
    draw.point((11,0), fill="orange")
    draw.rectange((20, 0, 40, 0), fill="red")

If you have a device like Pimoroni’s Unicorn pHat, initialize the device with width=N and height=N attributes instead:

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

# Pimoroni's Unicorn pHat is 8x4 neopixels
device = ws2812(width=8, height=4)

with canvas(device) as draw:
    draw.line((0, 0, 0, device.height), fill="red")
    draw.line((1, 0, 1, device.height), fill="orange")
    draw.line((2, 0, 2, device.height), fill="yellow")
    draw.line((3, 0, 3, device.height), fill="green")
    draw.line((4, 0, 4, device.height), fill="blue")
    draw.line((5, 0, 5, device.height), fill="indigo")
    draw.line((6, 0, 6, device.height), fill="violet")
    draw.line((7, 0, 7, device.height), fill="white")

Note

The ws2812 driver uses the ws2812 PyPi package to interface to the daisychained LEDs. It uses DMA (direct memory access) via /dev/mem which means that it has to run in privileged mode (via sudo root access).

The same viewport, scroll support, portrait/landscape orientation and color model idioms provided in luma.core are equally applicable to the ws2812 implementation.

Pimoroni Unicorn HAT¶

Pimoroni sells the Unicorn HAT, comprising 64 WS2812b NeoPixels in an 8x8 arrangement. The pixels are cascaded, but arranged in a ‘snake’ layout, rather than a ‘scan’ layout. In order to accomodate this, a translation mapping is required, as follows:

import time

from luma.led_matrix.device import ws2812, UNICORN_HAT
from luma.core.render import canvas

device = ws2812(width=8, height=8, mapping=UNICORN_HAT)

for y in range(device.height):
    for x in range(device.width):
        with canvas(device) as draw:
            draw.point((x, y), fill="green")
        time.sleep(0.5)

This should animate a green dot moving left-to-right down each line.

Pimoroni Unicorn HAT HD¶

Pimoroni sells the Unicorn HAT HD, comprising 256 high-intensity RGB LEDs in a 16x16 arrangement. The pixels are driven by an ARM STM32F making the display appear as an SPI device:

import time

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

serial = spi(port=0, device=0, gpio=noop())
device = unicornhathd(serial)

for y in range(device.height):
    for x in range(device.width):
        with canvas(device) as draw:
            draw.point((x, y), fill="green")
        time.sleep(0.5)

This should animate a green dot moving left-to-right down each line.

NeoSegments (WS2812)¶

@msurguy has crowdsourced some WS2812 neopixels into a modular 3D-printed seven-segment unit. To program these devices:

import time

from luma.led_matrix_device import neosegment

neoseg = neosegment(width=6)

# Defaults to "white" color initially
neoseg.text = "NEOSEG"
time.sleep(1)

# Set the first char ('N') to red
neoseg.color[0] = "red"
time.sleep(1)

# Set fourth and fifth chars ('S','E') accordingly
neoseg.color[3:5] = ["cyan", "blue"]
time.sleep(1)

# Set the entire string to green
neoseg.color = "green"

The neosegment class extends sevensegment, so the same text assignment (Python slicing paradigms) can be used here as well - see the earlier section for further details.

The underlying device is exposed as attribute device, so methods such as show, hide and contrast are available.

Next-generation APA102 NeoPixels¶

APA102 RGB neopixels are easier to control that WS2812 devices - they are driven using SPI rather than precise timings that the WS2812 devices need. Initialize the luma.led_matrix.device.apa102 class, supplying a parameter cascaded=N where N is the number of daisy-chained LEDs.

The following script creates a drawing surface 8 pixels long, and lights up three specific pixels:

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

device = apa102(cascaded=8)

with canvas(device) as draw:
    draw.point((0,0), fill="white")
    draw.point((0,1), fill="blue")
    draw.point((0,2), fill=(0xFF, 0x00, 0x00, 0x80))  # RGBA tuple, alpha controls brightness

APA102 RGB pixels can have their brightness individually controlled: by setting the alpha chanel to a translucent value (as per the above example) will set the brightness accordingly.

Emulators¶

There are various display emulators available for running code against, for debugging and screen capture functionality:

The luma.emulator.device.capture device will persist a numbered PNG file to disk every time its display() method is called.
The luma.emulator.device.gifanim device will record every image when its display() method is called, and on program exit (or Ctrl-C), will assemble the images into an animated GIF.
The luma.emulator.device.pygame device uses the pygame library to render the displayed image to a pygame display surface.

Invoke the demos with:

$ python examples/clock.py -d capture --transform=led_matrix

or:

$ python examples/clock.py -d pygame --transform=led_matrix

Note

Pygame is required to use any of the emulated devices, but it is NOT installed as a dependency by default, and so must be manually installed before using any of these emulation devices (e.g. pip install pygame). See the install instructions in luma.emulator for further details.