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.hd44780(serial_interface=None, width=16, height=2, undefined='_', selected_font=0, exec_time=1e-06, framebuffer=None, **kwargs)[source]

Bases: luma.lcd.device.backlit_device, luma.core.device.parallel_device, luma.core.virtual.character, luma.lcd.device.__framebuffer_mixin

Driver for a HD44780 style LCD display. This class provides a text property which can be used to set and get a text value, which will be rendered to the display’s screen using the display’s built-in font.

Parameters
  • serial_interface – The serial interface (usually a luma.core.interface.serial.parallel instance) to delegate sending data and commands through.

  • width (int) – The number of characters that can be displayed on a line.

  • height (int) – The number of lines the display supports.

  • undefined (str) – character to use if a requested character is not in the font tables

  • selected_font (int or str) – the font table appropriate for the model of display you are using. The hd44780 normally comes in a version with font A00 (ENGLISH_JAPANESE) or A02 (ENGLISH_EUROPEAN). You can provide either the name (‘A00’ or ‘A02’) or the number (0 for ‘A00’, 1 for ‘A02’) for the font your display contains.

  • exec_time (float) – Time in seconds to wait for a command to complete. Default is 50 μs (1e-6 * 50) which typically is long enough for commands to finish. If your display is not working correctly, you may want to try increasing the exec_time delay.

  • gpio_LIGHT (int) – The GPIO pin to use for the backlight if it is controlled by one of the GPIO pins.

  • active_low (bool) – Set to true if backlight is active low (default), false otherwise.

  • pwm_frequency (float) – Use PWM for backlight brightness control with the specified frequency when provided.

  • framebuffer (luma.core.framebuffer.framebuffer) – Framebuffering strategy, currently instances of diff_to_previous() or full_frame() are only supported.

To place text on the display, simply assign the text to the text instance variable:

p = parallel(RS=7, E=8, PINS=[25,24,23,18])
my_display = hd44780(p, selected_font='A00')
my_display.text = 'HD44780 Display\nFont A00 Eng/Jap'

For more details on how to use the ‘text’ interface see luma.core.virtual.character

..note:

This driver currently only supports the hd44780 5x8 display mode.

New in version 2.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, exec_time=None, only_low_bits=False)

Sends a command or sequence of commands through to the serial interface. If operating in four bit mode, expands each command from one byte values (8 bits) to two nibble values (4 bits each)

Parameters
  • cmd (int) – A spread of commands.

  • exec_time (float) – Amount of time to wait for the command to finish execution. If not provided, the device default will be used instead

  • only_low_bits (bool) – If True, only the lowest four bits of the command will be sent. This is necessary on some devices during initialization

contrast(*args)[source]

Not support on this device. Ignore.

data(data)

Sends a sequence of bytes through to the serial interface. If operating in four bit mode, expands each byte from a single value (8 bits) to two nibble values (4 bits each)

Parameters

data (list) – a sequence of bytes to send to the display

display(image)[source]

Takes a 1-bit PIL.Image and converts it to text data by reversing from glyphs from the image back to the correct value from the displays font table.

Parameters

image (PIL.Image.Image) – the image to place on the display

If needed, it will create custom characters if a glyph is not found within the font table.

get_font(ft)[source]

Return one of the devices built-in fonts as a PIL.ImageFont object

Parameters

ft (int or str) – name or number of the font to return (0 - A00, 1 - A02)

hide()

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

init_framebuffer(framebuffer, default_num_segments)
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.

property text

Returns the current state of the text buffer. This may not reflect accurately what is displayed on the device if the font does not have a symbol for a requested text value.

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=None, h_offset=0, v_offset=0, bgr=False, **kwargs)[source]

Bases: luma.lcd.device.backlit_device, luma.lcd.device.__framebuffer_mixin

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 (int) – 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 (luma.core.framebuffer.framebuffer) – Framebuffering strategy, currently instances 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.

init_framebuffer(framebuffer, default_num_segments)
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.ili9486(serial_interface=None, width=320, height=480, rotate=0, framebuffer=None, h_offset=0, v_offset=0, bgr=False, **kwargs)[source]

Bases: luma.lcd.device.backlit_device, luma.lcd.device.__framebuffer_mixin

Serial interface to a 262k color (6-6-6 RGB) ILI9486 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 (if implemented) and other settings.

Note that the ILI9486 display used for development – a Waveshare 3.5-inch IPS LCD(B) – used a portrait orientation. Images were rendered correctly only when specifying that height was 480 pixels and the width was 320.

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 (int) – 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 (luma.core.framebuffer.framebuffer) – Framebuffering strategy, currently instances 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.8.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 ILI9486 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.

init_framebuffer(framebuffer, default_num_segments)
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=None, h_offset=0, v_offset=0, bgr=False, inverse=False, **kwargs)[source]

Bases: luma.lcd.device.backlit_device, luma.lcd.device.__framebuffer_mixin

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 (int) – 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 (luma.core.framebuffer.framebuffer) – Framebuffering strategy, currently instances of diff_to_previous() or full_frame() are only supported.

  • bgr (bool) – Set to True if device pixels are BGR order (rather than RGB).

  • inverse (bool) – Set to True if device pixels are inversed.

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

init_framebuffer(framebuffer, default_num_segments)
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.st7789(serial_interface=None, width=240, height=240, rotate=0, **kwargs)[source]

Bases: luma.lcd.device.backlit_device

Serial interface to a colour ST7789 240x240 pixel LCD display.

New in version 2.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 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]

Send a command to the display, with optional arguments. The arguments are sent as data bytes, in accordance with the ST7789 datasheet.

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]

Should be overridden in sub-classed implementations.

Parameters

image (PIL.Image.Image) – An image to display.

Raises

NotImplementedError

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

set_window(x1, y1, x2, y2)[source]
show()

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.