API Documentation

OLED display driver for SSD1306, SSD1309, SSD1322, SSD1325, SSD1327, SSD1331, SSD1351 and SH1106 devices.

luma.oled.device

Collection of serial interfaces to OLED devices.

class luma.oled.device.ssd1306(serial_interface=None, width=128, height=64, rotate=0, **kwargs)

Bases: luma.core.device.device

Serial interface to a monochrome SSD1306 OLED 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.i2c instance) to delegate sending data and commands through.
• width (int) – the number of horizontal pixels (optional, defaults to 128).
• height (int) – the number of vertical pixels (optional, defaults to 64).
• 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 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(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)

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 OLED 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

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.oled.device.ssd1309(serial_interface=None, width=128, height=64, rotate=0, **kwargs)

Bases: luma.oled.device.ssd1306

Serial interface to a monochrome SSD1309 OLED 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 horizontal pixels (optional, defaults to 128).
• height (int) – the number of vertical pixels (optional, defaults to 64).
• 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 3.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 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(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)

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 OLED 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

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.oled.device.ssd1322(serial_interface=None, width=256, height=64, rotate=0, mode='RGB', framebuffer='diff_to_previous', **kwargs)

Bases: luma.oled.device.greyscale.greyscale_device

Serial interface to a 4-bit greyscale SSD1322 OLED 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 horizontal pixels (optional, defaults to 96).
• height (int) – the number of vertical pixels (optional, defaults to 64).
• 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) – Supplying “1” or “RGB” effects a different rendering mechanism, either to monochrome or 4-bit greyscale.
• framebuffer (str) – Framebuffering strategy, currently values of diff_to_previous or full_frame are only supported

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, *args)

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)

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)

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

display(image)

Takes a 1-bit monochrome or 24-bit RGB image and renders it to the greyscale OLED display. RGB pixels are converted to 4-bit greyscale values using a simplified Luma calculation, based on Y’=0.299R’+0.587G’+0.114B’.

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

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.oled.device.ssd1325(serial_interface=None, width=128, height=64, rotate=0, mode='RGB', framebuffer='full_frame', **kwargs)

Bases: luma.oled.device.greyscale.greyscale_device

Serial interface to a 4-bit greyscale SSD1325 OLED 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.

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

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

display(image)

Takes a 1-bit monochrome or 24-bit RGB image and renders it to the greyscale OLED display. RGB pixels are converted to 4-bit greyscale values using a simplified Luma calculation, based on Y’=0.299R’+0.587G’+0.114B’.

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

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.oled.device.ssd1327(serial_interface=None, width=128, height=128, rotate=0, mode='RGB', framebuffer='full_frame', **kwargs)

Bases: luma.oled.device.greyscale.greyscale_device

Serial interface to a 4-bit greyscale SSD1327 OLED 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.

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

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

display(image)

Takes a 1-bit monochrome or 24-bit RGB image and renders it to the greyscale OLED display. RGB pixels are converted to 4-bit greyscale values using a simplified Luma calculation, based on Y’=0.299R’+0.587G’+0.114B’.

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

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.oled.device.ssd1331(serial_interface=None, width=96, height=64, rotate=0, framebuffer='diff_to_previous', **kwargs)

Bases: luma.oled.device.color.color_device

Serial interface to a 16-bit color (5-6-5 RGB) SSD1331 OLED 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 horizontal pixels (optional, defaults to 96).
• height (int) – the number of vertical pixels (optional, defaults to 64).
• 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.

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

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

display(image)

Renders a 24-bit RGB image to the Color OLED 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

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.oled.device.ssd1351(serial_interface=None, width=128, height=128, rotate=0, framebuffer='diff_to_previous', h_offset=0, v_offset=0, bgr=False, **kwargs)

Bases: luma.oled.device.color.color_device

Serial interface to the 16-bit color (5-6-5 RGB) SSD1351 OLED 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 horizontal pixels (optional, defaults to 128).
• height (int) – the number of vertical pixels (optional, defaults to 128).
• 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 – vertical offset (in pixels) of screen to device memory (default: 0)

New in version 2.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, *args)

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)

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)

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

display(image)

Renders a 24-bit RGB image to the Color OLED 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

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.oled.device.sh1106(serial_interface=None, width=128, height=64, rotate=0, **kwargs)

Bases: luma.core.device.device

Serial interface to a monochrome SH1106 OLED 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.

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

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 SH1106 OLED 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

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.