Source code for luma.led_matrix.device

# -*- coding: utf-8 -*-
# Copyright (c) 2017-2022 Richard Hull and contributors
# See LICENSE.rst for details.

"""
Collection of serial interfaces to LED matrix devices.
"""

# Example usage:
#
#   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, width=8, height=8)
#
#   with canvas(device) as draw:
#      draw.rectangle(device.bounding_box, outline="white", fill="black")
#
# As soon as the with-block scope level is complete, the graphics primitives
# will be flushed to the device.
#
# Creating a new canvas is effectively 'carte blanche': If you want to retain
# an existing canvas, then make a reference like:
#
#    c = canvas(device)
#    for X in ...:
#        with c as draw:
#            draw.rectangle(...)
#
# As before, as soon as the with block completes, the canvas buffer is flushed
# to the device

import luma.core.error
import luma.led_matrix.const
from luma.core.interface.serial import noop
from luma.core.device import device
from luma.core.render import canvas
from luma.core.util import observable
from luma.core.virtual import sevensegment
from luma.led_matrix.segment_mapper import dot_muncher, regular


__all__ = ["max7219", "ws2812", "neopixel", "neosegment", "apa102", "unicornhathd"]


[docs] class max7219(device): """ Serial interface to a series of 8x8 LED matrixes daisychained together with MAX7219 chips. On creation, an initialization sequence is pumped to the display to properly configure it. Further control commands can then be called to affect the brightness and other settings. """ 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, **kwargs): super(max7219, self).__init__(luma.led_matrix.const.max7219, serial_interface) # Derive (override) the width and height if a cascaded param supplied if cascaded is not None: width = cascaded * 8 height = 8 self.blocks_arranged_in_reverse_order = blocks_arranged_in_reverse_order self.capabilities(width, height, rotate) self.segment_mapper = dot_muncher if width <= 0 or width % 8 != 0 or height <= 0 or height % 8 != 0: raise luma.core.error.DeviceDisplayModeError( f"Unsupported display mode: {width} x {height}") assert block_orientation in [0, 90, -90, 180] self._correction_angle = block_orientation self.cascaded = cascaded or (width * height) // 64 self._offsets = [(y * self._w) + x for y in range(self._h - 8, -8, -8) for x in range(self._w - 8, -8, -8)] self._rows = list(range(8)) self.data([self._const.SCANLIMIT, 7] * self.cascaded) self.data([self._const.DECODEMODE, 0] * self.cascaded) self.data([self._const.DISPLAYTEST, 0] * self.cascaded) self.contrast(contrast) self.clear() self.show()
[docs] def preprocess(self, image): """ Performs the inherited behviour (if any), and if the LED matrix orientation is declared to need correction, each 8x8 block of pixels is rotated 90° clockwise or counter-clockwise. """ image = super(max7219, self).preprocess(image) if self._correction_angle != 0: image = image.copy() for y in range(0, self._h, 8): for x in range(0, self._w, 8): box = (x, y, x + 8, y + 8) rotated_block = image.crop(box).rotate(self._correction_angle) image.paste(rotated_block, box) if self.blocks_arranged_in_reverse_order: old_image = image.copy() for y in range(8): for x in range(8): for i in range(self.cascaded): image.putpixel((8 * (self.cascaded - 1) - i * 8 + x, y), old_image.getpixel((i * 8 + x, y))) return image
[docs] def display(self, image): """ Takes a 1-bit :py:mod:`PIL.Image` and dumps it to the LED matrix display via the MAX7219 serializers. """ assert image.mode == self.mode assert image.size == self.size image = self.preprocess(image) i = 0 d0 = self._const.DIGIT_0 step = 2 * self.cascaded offsets = self._offsets rows = self._rows buf = bytearray(8 * step) pix = list(image.getdata()) for digit in range(8): for daisychained_device in offsets: byte = 0 idx = daisychained_device + digit for y in rows: if pix[idx] > 0: byte |= 1 << y idx += self._w buf[i] = digit + d0 buf[i + 1] = byte i += 2 buf = list(buf) for i in range(0, len(buf), step): self.data(buf[i:i + step])
[docs] def contrast(self, value): """ Sets the LED intensity to the desired level, in the range 0-255. :param level: Desired contrast level in the range of 0-255. :type level: int """ assert 0x00 <= value <= 0xFF self.data([self._const.INTENSITY, value >> 4] * self.cascaded)
[docs] def show(self): """ Sets the display mode ON, waking the device out of a prior low-power sleep mode. """ self.data([self._const.SHUTDOWN, 1] * self.cascaded)
[docs] def hide(self): """ Switches the display mode OFF, putting the device in low-power sleep mode. """ self.data([self._const.SHUTDOWN, 0] * self.cascaded)
[docs] class ws2812(device): """ Serial interface to a series of RGB neopixels daisy-chained together with WS281x chips. On creation, the array is initialized with the correct number of cascaded devices. Further control commands can then be called to affect the brightness and other settings. :param dma_interface: The WS2812 interface to write to (usually omit this parameter and it will default to the correct value - it is only needed for testing whereby a mock implementation is supplied). :param width: The number of pixels laid out horizontally. :type width: int :param height: The number of pixels laid out vertically. :type width: int :param cascaded: The number of pixels in a single strip - if supplied, this will override ``width`` and ``height``. :type cascaded: int :param rotate: Whether the device dimensions should be rotated in-situ: A value of: 0=0°, 1=90°, 2=180°, 3=270°. If not supplied, zero is assumed. :type rotate: int :param mapping: An (optional) array of integer values that translate the pixel to physical offsets. If supplied, should be the same size as ``width * height``. :type mapping: int[] .. versionadded:: 0.4.0 """ def __init__(self, dma_interface=None, width=8, height=4, cascaded=None, rotate=0, mapping=None, **kwargs): super(ws2812, self).__init__(const=None, serial_interface=noop) # Derive (override) the width and height if a cascaded param supplied if cascaded is not None: width = cascaded height = 1 self.cascaded = width * height self.capabilities(width, height, rotate, mode="RGB") self._mapping = list(mapping or range(self.cascaded)) assert self.cascaded == len(self._mapping) self._contrast = None self._prev_contrast = 0x70 ws = self._ws = dma_interface or self.__ws281x__() # Create ws2811_t structure and fill in parameters. self._leds = ws.new_ws2811_t() pin = 18 channel = 0 dma = 10 freq_hz = 800000 brightness = 255 strip_type = ws.WS2811_STRIP_GRB invert = False # Initialize the channels to zero for channum in range(2): chan = ws.ws2811_channel_get(self._leds, channum) ws.ws2811_channel_t_count_set(chan, 0) ws.ws2811_channel_t_gpionum_set(chan, 0) ws.ws2811_channel_t_invert_set(chan, 0) ws.ws2811_channel_t_brightness_set(chan, 0) # Initialize the channel in use self._channel = ws.ws2811_channel_get(self._leds, channel) ws.ws2811_channel_t_count_set(self._channel, self.cascaded) ws.ws2811_channel_t_gpionum_set(self._channel, pin) ws.ws2811_channel_t_invert_set(self._channel, 0 if not invert else 1) ws.ws2811_channel_t_brightness_set(self._channel, brightness) ws.ws2811_channel_t_strip_type_set(self._channel, strip_type) # Initialize the controller ws.ws2811_t_freq_set(self._leds, freq_hz) ws.ws2811_t_dmanum_set(self._leds, dma) resp = ws.ws2811_init(self._leds) if resp != 0: raise RuntimeError(f'ws2811_init failed with code {resp}') self.clear() self.show() def __ws281x__(self): import _rpi_ws281x return _rpi_ws281x
[docs] def display(self, image): """ Takes a 24-bit RGB :py:mod:`PIL.Image` and dumps it to the daisy-chained WS2812 neopixels. """ assert image.mode == self.mode assert image.size == self.size ws = self._ws m = self._mapping for idx, (red, green, blue) in enumerate(image.getdata()): color = (red << 16) | (green << 8) | blue ws.ws2811_led_set(self._channel, m[idx], color) self._flush()
[docs] def show(self): """ Simulates switching the display mode ON; this is achieved by restoring the contrast to the level prior to the last time hide() was called. """ if self._prev_contrast is not None: self.contrast(self._prev_contrast) self._prev_contrast = None
[docs] def hide(self): """ Simulates switching the display mode OFF; this is achieved by setting the contrast level to zero. """ if self._prev_contrast is None: self._prev_contrast = self._contrast self.contrast(0x00)
[docs] def contrast(self, value): """ Sets the LED intensity to the desired level, in the range 0-255. :param level: Desired contrast level in the range of 0-255. :type level: int """ assert 0x00 <= value <= 0xFF self._contrast = value self._ws.ws2811_channel_t_brightness_set(self._channel, value) self._flush()
def _flush(self): resp = self._ws.ws2811_render(self._leds) if resp != 0: raise RuntimeError(f'ws2811_render failed with code {resp}') def __del__(self): # Required because Python will complain about memory leaks # However there's no guarantee that "ws" will even be set # when the __del__ method for this class is reached. if self._ws is not None: self.cleanup()
[docs] def cleanup(self): """ Attempt to reset the device & switching it off prior to exiting the python process. """ self.hide() self.clear() if self._leds is not None: self._ws.ws2811_fini(self._leds) self._ws.delete_ws2811_t(self._leds) self._leds = None self._channel = None
# Alias for ws2812 neopixel = ws2812 # 8x8 Unicorn HAT has a 'snake-like' layout, so this translation # mapper linearizes that arrangement into a 'scan-like' layout. UNICORN_HAT = [ 7, 6, 5, 4, 3, 2, 1, 0, 8, 9, 10, 11, 12, 13, 14, 15, 23, 22, 21, 20, 19, 18, 17, 16, 24, 25, 26, 27, 28, 29, 30, 31, 39, 38, 37, 36, 35, 34, 33, 32, 40, 41, 42, 43, 44, 45, 46, 47, 55, 54, 53, 52, 51, 50, 49, 48, 56, 57, 58, 59, 60, 61, 62, 63 ]
[docs] class apa102(device): """ Serial interface to a series of 'next-gen' RGB DotStar daisy-chained together with APA102 chips. On creation, the array is initialized with the correct number of cascaded devices. Further control commands can then be called to affect the brightness and other settings. Note that the brightness of individual pixels can be set by altering the alpha channel of the RGBA image that is being displayed. :param serial_interface: The serial interface to write to (usually omit this parameter and it will default to the correct value - it is only needed for testing whereby a mock implementation is supplied). :param width: The number of pixels laid out horizontally. :type width: int :param height: The number of pixels laid out vertically. :type width: int :param cascaded: The number of pixels in a single strip - if supplied, this will override ``width`` and ``height``. :type cascaded: int :param rotate: Whether the device dimensions should be rotated in-situ: A value of: 0=0°, 1=90°, 2=180°, 3=270°. If not supplied, zero is assumed. :type rotate: int :param mapping: An (optional) array of integer values that translate the pixel to physical offsets. If supplied, should be the same size as ``width * height``. :type mapping: int[] .. versionadded:: 0.9.0 """ def __init__(self, serial_interface=None, width=8, height=1, cascaded=None, rotate=0, mapping=None, **kwargs): super(apa102, self).__init__(luma.core.const.common, serial_interface or self.__bitbang__()) # Derive (override) the width and height if a cascaded param supplied if cascaded is not None: width = cascaded height = 1 self.cascaded = width * height self.capabilities(width, height, rotate, mode="RGBA") self._mapping = list(mapping or range(self.cascaded)) assert self.cascaded == len(self._mapping) self._last_image = None self.contrast(0x70) self.clear() self.show() def __bitbang__(self): from luma.core.interface.serial import bitbang return bitbang(SCLK=24, SDA=23)
[docs] def display(self, image): """ Takes a 32-bit RGBA :py:mod:`PIL.Image` and dumps it to the daisy-chained APA102 neopixels. If a pixel is not fully opaque, the alpha channel value is used to set the brightness of the respective RGB LED. """ assert image.mode == self.mode assert image.size == self.size self._last_image = image.copy() # Send zeros to reset, then pixel values then zeros at end sz = image.width * image.height * 4 buf = bytearray(sz * 3) m = self._mapping for idx, (r, g, b, a) in enumerate(image.getdata()): offset = sz + m[idx] * 4 brightness = (a >> 4) if a != 0xFF else self._brightness buf[offset] = (0xE0 | brightness) buf[offset + 1] = b buf[offset + 2] = g buf[offset + 3] = r self._serial_interface.data(list(buf))
[docs] def show(self): """ Not supported """ pass
[docs] def hide(self): """ Not supported """ pass
[docs] def contrast(self, value): """ Sets the LED intensity to the desired level, in the range 0-255. :param level: Desired contrast level in the range of 0-255. :type level: int """ assert 0x00 <= value <= 0xFF self._brightness = value >> 4 if self._last_image is not None: self.display(self._last_image)
[docs] class neosegment(sevensegment): """ Extends the :py:class:`~luma.core.virtual.sevensegment` class specifically for @msurguy's modular NeoSegments. It uses the same underlying render techniques as the base class, but provides additional functionality to be able to adddress individual characters colors. :param width: The number of 7-segment elements that are cascaded. :type width: int :param undefined: The default character to substitute when an unrenderable character is supplied to the text property. :type undefined: char .. versionadded:: 0.11.0 """ def __init__(self, width, undefined="_", **kwargs): if width <= 0 or width % 2 == 1: raise luma.core.error.DeviceDisplayModeError( f"Unsupported display mode: width={width}") height = 7 mapping = [(i % width) * height + (i // width) for i in range(width * height)] self.device = kwargs.get("device") or ws2812(width=width, height=height, mapping=mapping) self.undefined = undefined self._text_buffer = "" self.color = "white" @property def color(self): return self._colors @color.setter def color(self, value): if not isinstance(value, list): value = [value] * self.device.width assert len(value) == self.device.width self._colors = observable(value, observer=self._color_chg) def _color_chg(self, color): self._flush(self.text, color) def _flush(self, text, color=None): data = bytearray(self.segment_mapper(text, notfound=self.undefined)).ljust(self.device.width, b'\0') color = color or self.color if len(data) > self.device.width: raise OverflowError( "Device's capabilities insufficient for value '{0}'".format(text)) with canvas(self.device) as draw: for x, byte in enumerate(data): for y in range(self.device.height): if byte & 0x01: draw.point((x, y), fill=color[x]) byte >>= 1
[docs] def segment_mapper(self, text, notfound="_"): for char in regular(text, notfound): # Convert from std MAX7219 segment mappings a = char >> 6 & 0x01 b = char >> 5 & 0x01 c = char >> 4 & 0x01 d = char >> 3 & 0x01 e = char >> 2 & 0x01 f = char >> 1 & 0x01 g = char >> 0 & 0x01 # To NeoSegment positions yield \ b << 6 | \ a << 5 | \ f << 4 | \ g << 3 | \ c << 2 | \ d << 1 | \ e << 0
[docs] class unicornhathd(device): """ Display adapter for Pimoroni's Unicorn Hat HD - a dense 16x16 array of high intensity RGB LEDs. Since the board contains a small ARM chip to manage the LEDs, interfacing is very straightforward using SPI. This has the side-effect that the board appears not to be daisy-chainable though. However there a number of undocumented contact pads on the underside of the board which _may_ allow this behaviour. Note that the brightness of individual pixels can be set by altering the alpha channel of the RGBA image that is being displayed. :param serial_interface: The serial interface to write to. :param rotate: Whether the device dimensions should be rotated in-situ: A value of: 0=0°, 1=90°, 2=180°, 3=270°. If not supplied, zero is assumed. :type rotate: int .. versionadded:: 1.3.0 """ def __init__(self, serial_interface=None, rotate=0, **kwargs): super(unicornhathd, self).__init__(luma.core.const.common, serial_interface) self.capabilities(16, 16, rotate, mode="RGBA") self._last_image = None self._prev_brightness = None self.contrast(0x70) self.clear() self.show()
[docs] def display(self, image): """ Takes a 32-bit RGBA :py:mod:`PIL.Image` and dumps it to the Unicorn HAT HD. If a pixel is not fully opaque, the alpha channel value is used to set the brightness of the respective RGB LED. """ assert image.mode == self.mode assert image.size == self.size self._last_image = image.copy() # Send zeros to reset, then pixel values then zeros at end sz = image.width * image.height * 3 buf = bytearray(sz) normalized_brightness = self._brightness / 255.0 for idx, (r, g, b, a) in enumerate(image.getdata()): offset = idx * 3 brightness = a / 255.0 if a != 255 else normalized_brightness buf[offset] = int(r * brightness) buf[offset + 1] = int(g * brightness) buf[offset + 2] = int(b * brightness) self._serial_interface.data([0x72] + list(buf)) # 0x72 == SOF ... start of frame?
[docs] def show(self): """ Simulates switching the display mode ON; this is achieved by restoring the contrast to the level prior to the last time hide() was called. """ if self._prev_brightness is not None: self.contrast(self._prev_brightness) self._prev_brightness = None
[docs] def hide(self): """ Simulates switching the display mode OFF; this is achieved by setting the contrast level to zero. """ if self._prev_brightness is None: self._prev_brightness = self._brightness self.contrast(0x00)
[docs] def contrast(self, value): """ Sets the LED intensity to the desired level, in the range 0-255. :param level: Desired contrast level in the range of 0-255. :type level: int """ assert 0x00 <= value <= 0xFF self._brightness = value if self._last_image is not None: self.display(self._last_image)