API Documentation

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

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

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.max7219(serial_interface=None, width=8, height=8, cascaded=None, rotate=0, block_orientation=0, **kwargs)[source]

Bases: luma.core.device.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)[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 orientation is declared to need correction, each 8x8 block of pixels is rotated 90° clockwise or counter-clockwise.

show()[source]

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

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

Bases: luma.core.device.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 – 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.

New 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()[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]

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

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

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

luma.led_matrix.device.neopixel

alias of luma.led_matrix.device.ws2812

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

Bases: luma.core.virtual.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.

New in version 0.11.0.

color
segment_mapper(text, notfound='_')[source]
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.apa102(serial_interface=None, width=8, height=1, cascaded=None, rotate=0, mapping=None, **kwargs)[source]

Bases: luma.core.device.device

Serial interface to a series of ‘next-gen’ RGB neopixels 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 – 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.

New 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)[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 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()[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