API Documentation

Display drivers for LED Matrices & 7-segment displays (MAX7219) and RGB NeoPixels (WS2812 / APA102).

digraph inheritancec1a2fc222d { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "luma.core.device.device" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Base class for display driver classes"]; "luma.core.mixin.capabilities" -> "luma.core.device.device" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.device.dummy" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Pseudo-device that acts like a physical display, except that it does nothing"]; "luma.core.device.device" -> "luma.core.device.dummy" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.device.linux_framebuffer" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Pseudo-device that acts like a physical display, except that it renders"]; "luma.core.device.device" -> "luma.core.device.linux_framebuffer" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.device.parallel_device" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Wrapper class to manage communications with devices that can operate in"]; "luma.core.device.device" -> "luma.core.device.parallel_device" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.mixin.capabilities" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="This class should be 'mixed-in' to any :py:class:`luma.core.device.device`"]; "luma.core.virtual.character" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Abstraction that wraps a device, this class provides a ``text`` property"]; "luma.core.virtual.history" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Wraps a device (or emulator) to provide a facility to be able to make a"]; "luma.core.mixin.capabilities" -> "luma.core.virtual.history" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.hotspot" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A hotspot (`a place of more than usual interest, activity, or popularity`)"]; "luma.core.mixin.capabilities" -> "luma.core.virtual.hotspot" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.sevensegment" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Abstraction that wraps a device, this class provides a ``text`` property"]; "luma.core.virtual.snapshot" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A snapshot is a `type of` hotspot, but only updates once in a given"]; "luma.core.virtual.hotspot" -> "luma.core.virtual.snapshot" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.terminal" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Provides a terminal-like interface to a device (or a device-like object"]; "luma.core.virtual.viewport" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="The viewport offers a positionable window into a larger resolution pseudo-display,"]; "luma.core.mixin.capabilities" -> "luma.core.virtual.viewport" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.led_matrix.device.apa102" [URL="#luma.led_matrix.device.apa102",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a series of 'next-gen' RGB DotStar daisy-chained"]; "luma.core.device.device" -> "luma.led_matrix.device.apa102" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.led_matrix.device.max7219" [URL="#luma.led_matrix.device.max7219",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a series of 8x8 LED matrixes daisychained together with"]; "luma.core.device.device" -> "luma.led_matrix.device.max7219" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.led_matrix.device.neosegment" [URL="#luma.led_matrix.device.neosegment",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Extends the :py:class:`~luma.core.virtual.sevensegment` class specifically"]; "luma.core.virtual.sevensegment" -> "luma.led_matrix.device.neosegment" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.led_matrix.device.unicornhathd" [URL="#luma.led_matrix.device.unicornhathd",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Display adapter for Pimoroni's Unicorn Hat HD - a dense 16x16 array of"]; "luma.core.device.device" -> "luma.led_matrix.device.unicornhathd" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.led_matrix.device.ws2812" [URL="#luma.led_matrix.device.ws2812",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a series of RGB neopixels daisy-chained together with"]; "luma.core.device.device" -> "luma.led_matrix.device.ws2812" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

Upgrading

Warning

Version 0.3.0 was released on 19 January 2017: this came with a rename of the project in github from max7219 to luma.led_matrix to reflect the changing nature of the codebase. It introduces a complete rewrite of the codebase to bring it in line with other ‘luma’ implementations.

There is no direct migration path, but the old documentation and PyPi packages will remain available indefinitely, but that deprecated codebase will no longer recieve updates or fixes.

This breaking change was necessary to be able to add different classes of devices, so that they could reuse core components.

luma.led_matrix.device

Collection of serial interfaces to LED matrix devices.

class luma.led_matrix.device.apa102(serial_interface=None, width=8, height=1, cascaded=None, rotate=0, mapping=None, **kwargs)

Bases: 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.

Parameters:

• 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).

• width (int) – The number of pixels laid out horizontally.

• height – The number of pixels laid out vertically.

• cascaded (int) – The number of pixels in a single strip - if supplied, this will override width and height.

• rotate (int) – 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.

• mapping (int[]) – An (optional) array of integer values that translate the pixel to physical offsets. If supplied, should be the same size as width * height.

Added in version 0.9.0.

capabilities(width, height, rotate, mode='1')

Assigns attributes such as width, height, size and bounding_box correctly oriented from the supplied parameters.

Parameters:

• width (int) – The device width.

• height (int) – The device height.

• rotate (int) – An integer value of 0 (default), 1, 2 or 3 only, where 0 is no rotation, 1 is rotate 90° clockwise, 2 is 180° rotation and 3 represents 270° rotation.

• mode (str) – The supported color model, one of "1", "RGB" or "RGBA" only.

cleanup()

Attempt to switch the device off or put into low power mode (this helps prolong the life of the device), clear the screen and close resources associated with the underlying serial interface.

If persist is True, the device will not be switched off.

This is a managed function, which is called when the python processs is being shutdown, so shouldn’t usually need be called directly in application code.

clear()

Initializes the device memory with an empty (blank) image.

command(*cmd)

Sends a command or sequence of commands through to the delegated serial interface.

contrast(value)

Sets the LED intensity to the desired level, in the range 0-255.

Parameters:

level (int) – Desired contrast level in the range of 0-255.

data(data)

Sends a data byte or sequence of data bytes through to the delegated serial interface.

display(image)

Takes a 32-bit RGBA 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.

hide()

Not supported

preprocess(image)

Provides a preprocessing facility (which may be overridden) whereby the supplied image is rotated according to the device’s rotate capability. If this method is overridden, it is important to call the super method.

Parameters:

image (PIL.Image.Image) – An image to pre-process.

Returns:

A new processed image.

Return type:

PIL.Image.Image

show()

Not supported

class luma.led_matrix.device.max7219(serial_interface=None, width=8, height=8, cascaded=None, rotate=0, block_orientation=0, blocks_arranged_in_reverse_order=False, contrast=112, **kwargs)

Bases: 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.

capabilities(width, height, rotate, mode='1')

Assigns attributes such as width, height, size and bounding_box correctly oriented from the supplied parameters.

Parameters:

• width (int) – The device width.

• height (int) – The device height.

• rotate (int) – An integer value of 0 (default), 1, 2 or 3 only, where 0 is no rotation, 1 is rotate 90° clockwise, 2 is 180° rotation and 3 represents 270° rotation.

• mode (str) – The supported color model, one of "1", "RGB" or "RGBA" only.

cleanup()

Attempt to switch the device off or put into low power mode (this helps prolong the life of the device), clear the screen and close resources associated with the underlying serial interface.

If persist is True, the device will not be switched off.

This is a managed function, which is called when the python processs is being shutdown, so shouldn’t usually need be called directly in application code.

clear()

Initializes the device memory with an empty (blank) image.

command(*cmd)

Sends a command or sequence of commands through to the delegated serial interface.

contrast(value)

Sets the LED intensity to the desired level, in the range 0-255.

Parameters:

level (int) – Desired contrast level in the range of 0-255.

data(data)

Sends a data byte or sequence of data bytes through to the delegated serial interface.

display(image)

Takes a 1-bit PIL.Image and dumps it to the LED matrix display via the MAX7219 serializers.

hide()

Switches the display mode OFF, putting the device in low-power sleep mode.

preprocess(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.

show()

Sets the display mode ON, waking the device out of a prior low-power sleep mode.

luma.led_matrix.device.neopixel

alias of ws2812

class luma.led_matrix.device.neosegment(width, undefined='_', **kwargs)

Bases: sevensegment

Extends the 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.

Parameters:

• width (int) – The number of 7-segment elements that are cascaded.

• undefined (char) – The default character to substitute when an unrenderable character is supplied to the text property.

Added in version 0.11.0.

property color

segment_mapper(text, notfound='_')

property text

Returns the current state of the text buffer. This may not reflect accurately what is displayed on the seven-segment device, as certain alpha-numerics and most punctuation cannot be rendered on the limited display.

class luma.led_matrix.device.unicornhathd(serial_interface=None, rotate=0, **kwargs)

Bases: 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.

Parameters:

• serial_interface – The serial interface to write to.

• rotate (int) – 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.

Added in version 1.3.0.

capabilities(width, height, rotate, mode='1')

Assigns attributes such as width, height, size and bounding_box correctly oriented from the supplied parameters.

Parameters:

• width (int) – The device width.

• height (int) – The device height.

• rotate (int) – An integer value of 0 (default), 1, 2 or 3 only, where 0 is no rotation, 1 is rotate 90° clockwise, 2 is 180° rotation and 3 represents 270° rotation.

• mode (str) – The supported color model, one of "1", "RGB" or "RGBA" only.

cleanup()

Attempt to switch the device off or put into low power mode (this helps prolong the life of the device), clear the screen and close resources associated with the underlying serial interface.

If persist is True, the device will not be switched off.

This is a managed function, which is called when the python processs is being shutdown, so shouldn’t usually need be called directly in application code.

clear()

Initializes the device memory with an empty (blank) image.

command(*cmd)

Sends a command or sequence of commands through to the delegated serial interface.

contrast(value)

Sets the LED intensity to the desired level, in the range 0-255.

Parameters:

level (int) – Desired contrast level in the range of 0-255.

data(data)

Sends a data byte or sequence of data bytes through to the delegated serial interface.

display(image)

Takes a 32-bit RGBA 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.

hide()

Simulates switching the display mode OFF; this is achieved by setting the contrast level to zero.

preprocess(image)

Provides a preprocessing facility (which may be overridden) whereby the supplied image is rotated according to the device’s rotate capability. If this method is overridden, it is important to call the super method.

Parameters:

image (PIL.Image.Image) – An image to pre-process.

Returns:

A new processed image.

Return type:

PIL.Image.Image

show()

Simulates switching the display mode ON; this is achieved by restoring the contrast to the level prior to the last time hide() was called.

class luma.led_matrix.device.ws2812(dma_interface=None, width=8, height=4, cascaded=None, rotate=0, mapping=None, **kwargs)

Bases: 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.

Parameters:

• 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).

• width (int) – The number of pixels laid out horizontally.

• height – The number of pixels laid out vertically.

• cascaded (int) – The number of pixels in a single strip - if supplied, this will override width and height.

• rotate (int) – 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.

• mapping (int[]) – An (optional) array of integer values that translate the pixel to physical offsets. If supplied, should be the same size as width * height.

Added in version 0.4.0.

capabilities(width, height, rotate, mode='1')

Assigns attributes such as width, height, size and bounding_box correctly oriented from the supplied parameters.

Parameters:

• width (int) – The device width.

• height (int) – The device height.

• rotate (int) – An integer value of 0 (default), 1, 2 or 3 only, where 0 is no rotation, 1 is rotate 90° clockwise, 2 is 180° rotation and 3 represents 270° rotation.

• mode (str) – The supported color model, one of "1", "RGB" or "RGBA" only.

cleanup()

Attempt to reset the device & switching it off prior to exiting the python process.

clear()

Initializes the device memory with an empty (blank) image.

command(*cmd)

Sends a command or sequence of commands through to the delegated serial interface.

contrast(value)

Sets the LED intensity to the desired level, in the range 0-255.

Parameters:

level (int) – Desired contrast level in the range of 0-255.

data(data)

Sends a data byte or sequence of data bytes through to the delegated serial interface.

display(image)

Takes a 24-bit RGB PIL.Image and dumps it to the daisy-chained WS2812 neopixels.

hide()

Simulates switching the display mode OFF; this is achieved by setting the contrast level to zero.

preprocess(image)

Provides a preprocessing facility (which may be overridden) whereby the supplied image is rotated according to the device’s rotate capability. If this method is overridden, it is important to call the super method.

Parameters:

image (PIL.Image.Image) – An image to pre-process.

Returns:

A new processed image.

Return type:

PIL.Image.Image

show()

Simulates switching the display mode ON; this is achieved by restoring the contrast to the level prior to the last time hide() was called.