API Documentation

LED matrix display driver for max7219 devices.

Inheritance diagram of luma.core.device, luma.core.mixin, luma.core.virtual, luma.led_matrix.device, luma.led_matrix.virtual

Breaking changes

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

class luma.led_matrix.device.max7219(serial_interface=None, width=8, height=8, cascaded=None, rotate=0, block_orientation='horizontal', **kwargs)[source]

Bases: luma.core.device.device

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

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)[source]

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)[source]

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

hide()[source]

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

preprocess(image)[source]

Performs the inherited behviour (if any), and if the LED matrix is declared to being a common row cathode, each 8x8 block of pixels is rotated 90° clockwise.

show()[source]

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

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

Bases: luma.core.device.device

Encapsulates the 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 – The number of pixels in a single strip - if supplied, this will override width and height.
  • rotate (int) – Whether the device dimenstions 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
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()[source]

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)[source]

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)[source]

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

hide()[source]

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

Parameters:image (PIL.Image.Image) – An image to pre-process
Returns:A new processed image
Return type:PIL.Image.Image
show()[source]

Not supported

luma.led_matrix.virtual

class luma.led_matrix.virtual.sevensegment(device, undefined='_', mapper=<function dot_muncher>)[source]

Bases: object

Abstraction that wraps a MAX7219 device, this class provides a text property which can be used to set and get a value, which is propagated onto the underlying device.

Parameters:
  • device – A MAX7219 device instance
  • undefined (char) – The default character to substitute when an unrenderable character is supplied to the text property.
  • mapper – A function that maps strings into the correct representation for the 7-segment physical layout. By default, a “dot” muncher implementation is used which places dots inline with the preceeding character.
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