API Documentation¶

LCD display drivers.

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

Upgrading¶

Warning

Version 2.0.0 was released on 2 June 2019: this came with the removal of the luma.lcd.aux.backlight class. The equivalent functionality has now been subsumed into the device classes that have a backlight capability.

`luma.lcd.device`¶

Collection of serial interfaces to LCD devices.

class luma.lcd.device.ht1621(gpio=None, width=6, rotate=0, WR=11, DAT=10, CS=8, **kwargs)[source]¶

Bases: luma.lcd.device.backlit_device

Serial interface to a seven segment HT1621 monochrome LCD display.

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.

Parameters

gpio – The GPIO library to use (usually RPi.GPIO) to delegate sending data and commands through.
width (int) – The number of 7 segment characters laid out horizontally.
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.
WR (int) – The write (SPI clock) pin to connect to, default BCM 11.
DAT (int) – The data pin to connect to, default BCM 10.
CS (int) – The chip select pin to connect to, default BCM 8.

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)[source]¶: Sends a command or sequence of commands through to the delegated serial interface.

contrast(level)¶

Switches the display contrast to the desired level, in the range 0-255. Note that setting the level to a low (or zero) value will not necessarily dim the display to nearly off. In other words, this method is NOT suitable for fade-in/out animation.

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

data(data)[source]¶: 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 PCD8544 LCD display.

hide()¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class luma.lcd.device.ili9341(serial_interface=None, width=320, height=240, rotate=0, framebuffer='diff_to_previous', h_offset=0, v_offset=0, bgr=False, **kwargs)[source]¶

Bases: luma.lcd.device.backlit_device

Serial interface to a 262k color (6-6-6 RGB) ILI9341 LCD display.

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.

Parameters

serial_interface – the serial interface (usually a luma.core.interface.serial.spi instance) to delegate sending data and commands through.
width (int) – The number of pixels laid out horizontally.
height – The number of pixels laid out vertically.
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.
framebuffer (str) – Framebuffering strategy, currently values of diff_to_previous or full_frame are only supported.
bgr (bool) – Set to True if device pixels are BGR order (rather than RGB).
h_offset (int) – Horizontal offset (in pixels) of screen to device memory (default: 0).
v_offset (int) – Vertical offset (in pixels) of screen to device memory (default: 0).

New in version 2.2.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, *args)[source]¶: Sends a command and an (optional) sequence of arguments through to the delegated serial interface. Note that the arguments are passed through as data.

contrast(level)[source]¶

NOT SUPPORTED

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]¶

Renders a 24-bit RGB image to the ILI9341 LCD display. The 8-bit RGB values are passed directly to the devices internal storage, but only the 6 most-significant bits are used by the display.

Parameters: image (PIL.Image.Image) – The image to render.

hide()¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class luma.lcd.device.pcd8544(serial_interface=None, rotate=0, **kwargs)[source]¶

Bases: luma.lcd.device.backlit_device

Serial interface to a monochrome PCD8544 LCD display.

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.

Parameters

serial_interface – The serial interface (usually a luma.core.interface.serial.spi instance) to delegate sending data and commands through.
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.

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)[source]¶: Sets the LCD contrast

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 PCD8544 LCD display.

hide()¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class luma.lcd.device.st7567(serial_interface=None, rotate=0, **kwargs)[source]¶

Bases: luma.lcd.device.backlit_device

Serial interface to a monochrome ST7567 128x64 pixel LCD display.

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.

Parameters

serial_interface – The serial interface (usually a luma.core.interface.serial.spi instance) to delegate sending data and commands through.
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.

New in version 1.1.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)[source]¶: Sets the LCD contrast

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 ST7567 LCD display

hide()¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class luma.lcd.device.st7735(serial_interface=None, width=160, height=128, rotate=0, framebuffer='diff_to_previous', h_offset=0, v_offset=0, bgr=False, **kwargs)[source]¶

Bases: luma.lcd.device.backlit_device

Serial interface to a 262K color (6-6-6 RGB) ST7735 LCD display.

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.

Parameters

serial_interface – the serial interface (usually a luma.core.interface.serial.spi instance) to delegate sending data and commands through.
width (int) – The number of pixels laid out horizontally.
height – The number of pixels laid out vertically.
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.
framebuffer (str) – Framebuffering strategy, currently values of diff_to_previous or full_frame are only supported.
bgr (bool) – Set to True if device pixels are BGR order (rather than RGB).
h_offset (int) – Horizontal offset (in pixels) of screen to device memory (default: 0).
v_offset (int) – Vertical offset (in pixels) of screen to device memory (default: 0).

New in version 0.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 reset the device & switching it off prior to exiting the python process.

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

command(cmd, *args)[source]¶: Sends a command and an (optional) sequence of arguments through to the delegated serial interface. Note that the arguments are passed through as data.

contrast(level)[source]¶

NOT SUPPORTED

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]¶

Renders a 24-bit RGB image to the ST7735 LCD display. The 8-bit RGB values are passed directly to the devices internal storage, but only the 6 most-significant bits are used by the display.

Parameters: image (PIL.Image.Image) – The image to render.

hide()¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class luma.lcd.device.st7920(serial_interface=None, width=128, height=64, rotate=0, framebuffer='diff_to_previous', **kwargs)[source]¶

Bases: luma.core.device.device

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)[source]¶: Sends a command or sequence of commands through to the delegated serial interface.

contrast(level)[source]¶

NOT SUPPORTED

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

data(data)[source]¶: Sends a data byte or sequence of data bytes through to the delegated serial interface.

display(image)[source]¶

Should be overridden in sub-classed implementations.

Parameters: image (PIL.Image.Image) – An image to display.
Raises: NotImplementedError –

hide()[source]¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()[source]¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class luma.lcd.device.uc1701x(serial_interface=None, rotate=0, **kwargs)[source]¶

Bases: luma.lcd.device.backlit_device

Serial interface to a monochrome UC1701X LCD display.

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.

Parameters

serial_interface – The serial interface (usually a luma.core.interface.serial.spi instance) to delegate sending data and commands through.
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.

New in version 0.5.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)[source]¶: Sets the LCD contrast

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 UC1701X LCD display.

hide()¶: Switches the display mode OFF, putting the device in low-power sleep mode.

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()¶: Sets the display mode ON, waking the device out of a prior low-power sleep mode.

API Documentation¶

Upgrading¶

luma.lcd.device¶

`luma.lcd.device`¶