API Documentation

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

digraph inheritancec2ddb0719e { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "luma.core.device.device" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Base class for display driver classes"]; "luma.core.mixin.capabilities" -> "luma.core.device.device" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.device.dummy" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Pseudo-device that acts like a physical display, except that it does nothing"]; "luma.core.device.device" -> "luma.core.device.dummy" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.device.linux_framebuffer" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Pseudo-device that acts like a physical display, except that it renders"]; "luma.core.device.device" -> "luma.core.device.linux_framebuffer" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.device.parallel_device" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Wrapper class to manage communications with devices that can operate in"]; "luma.core.device.device" -> "luma.core.device.parallel_device" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.mixin.capabilities" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="This class should be 'mixed-in' to any :py:class:`luma.core.device.device`"]; "luma.core.virtual.character" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Abstraction that wraps a device, this class provides a ``text`` property"]; "luma.core.virtual.history" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Wraps a device (or emulator) to provide a facility to be able to make a"]; "luma.core.mixin.capabilities" -> "luma.core.virtual.history" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.hotspot" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A hotspot (`a place of more than usual interest, activity, or popularity`)"]; "luma.core.mixin.capabilities" -> "luma.core.virtual.hotspot" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.sevensegment" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Abstraction that wraps a device, this class provides a ``text`` property"]; "luma.core.virtual.snapshot" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="A snapshot is a `type of` hotspot, but only updates once in a given"]; "luma.core.virtual.hotspot" -> "luma.core.virtual.snapshot" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.terminal" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="Provides a terminal-like interface to a device (or a device-like object"]; "luma.core.virtual.viewport" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",tooltip="The viewport offers a positionable window into a larger resolution pseudo-display,"]; "luma.core.mixin.capabilities" -> "luma.core.virtual.viewport" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.color.color_device" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "luma.core.device.device" -> "luma.oled.device.color.color_device" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.greyscale.greyscale_device" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled"]; "luma.core.device.device" -> "luma.oled.device.greyscale.greyscale_device" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.sh1106" [URL="#luma.oled.device.sh1106",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a monochrome SH1106 OLED display."]; "luma.core.device.device" -> "luma.oled.device.sh1106" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1306" [URL="#luma.oled.device.ssd1306",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a monochrome SSD1306 OLED display."]; "luma.core.device.device" -> "luma.oled.device.ssd1306" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1309" [URL="#luma.oled.device.ssd1309",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a monochrome SSD1309 OLED display."]; "luma.oled.device.ssd1306" -> "luma.oled.device.ssd1309" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1322" [URL="#luma.oled.device.ssd1322",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a 4-bit greyscale SSD1322 OLED display."]; "luma.oled.device.greyscale.greyscale_device" -> "luma.oled.device.ssd1322" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1322_nhd" [URL="#luma.oled.device.ssd1322_nhd",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Similar to ssd1322 but several options are hard coded: width, height and"]; "luma.oled.device.greyscale.greyscale_device" -> "luma.oled.device.ssd1322_nhd" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1325" [URL="#luma.oled.device.ssd1325",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a 4-bit greyscale SSD1325 OLED display."]; "luma.oled.device.greyscale.greyscale_device" -> "luma.oled.device.ssd1325" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1327" [URL="#luma.oled.device.ssd1327",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a 4-bit greyscale SSD1327 OLED display."]; "luma.oled.device.greyscale.greyscale_device" -> "luma.oled.device.ssd1327" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1331" [URL="#luma.oled.device.ssd1331",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a 16-bit color (5-6-5 RGB) SSD1331 OLED display."]; "luma.oled.device.color.color_device" -> "luma.oled.device.ssd1331" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1351" [URL="#luma.oled.device.ssd1351",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to the 16-bit color (5-6-5 RGB) SSD1351 OLED display."]; "luma.oled.device.color.color_device" -> "luma.oled.device.ssd1351" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ssd1362" [URL="#luma.oled.device.ssd1362",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a 4-bit greyscale SSD1362 OLED display."]; "luma.oled.device.greyscale.greyscale_device" -> "luma.oled.device.ssd1362" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.winstar_weh" [URL="#luma.oled.device.winstar_weh",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a monochrome Winstar WEH OLED display. This is the"]; "luma.oled.device.ws0010" -> "luma.oled.device.winstar_weh" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.oled.device.ws0010" [URL="#luma.oled.device.ws0010",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="Serial interface to a monochrome Winstar WS0010 OLED display. This"]; "luma.core.device.parallel_device" -> "luma.oled.device.ws0010" [arrowsize=0.5,style="setlinewidth(0.5)"]; "luma.core.virtual.character" -> "luma.oled.device.ws0010" [arrowsize=0.5,style="setlinewidth(0.5)"]; }

luma.oled.device

Collection of serial interfaces to OLED devices.

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

Bases: 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.

Parameters

image (PIL.Image) – Image to 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.oled.device.ssd1306(serial_interface=None, width=128, height=64, rotate=0, **kwargs)

Bases: 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.

Parameters

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

Bases: 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.

Parameters

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

Bases: 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 instances 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.

init_framebuffer(framebuffer)

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

Bases: greyscale_device

Similar to ssd1322 but several options are hard coded: width, height and frame buffer

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

init_framebuffer(framebuffer)

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

Bases: 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.

init_framebuffer(framebuffer)

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

Bases: 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.

init_framebuffer(framebuffer)

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

Bases: 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 instances 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.

init_framebuffer(framebuffer)

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

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

init_framebuffer(framebuffer)

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

Bases: greyscale_device

Serial interface to a 4-bit greyscale SSD1362 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 instances of diff_to_previous or full_frame are only supported

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

init_framebuffer(framebuffer)

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.oled.device.winstar_weh(serial_interface=None, width=16, height=2, **kwargs)

Bases: ws0010

Serial interface to a monochrome Winstar WEH OLED display. This is the character version of the display using the ws0010 controller. This class provides the same text property as the ws0010 interface so you can set the text value which will be rendered to the display’s screen. This interface uses a variant of the ws0010 controller’s built-in font that is designed to match the grid structure of the weh displays (see note below).

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 single line. Example: the weh001602a has a width of 16 characters.

• height (int) – The number of lines the display has. Example: the weh001602a has a height of 2 lines.

• undefined (str) – The character to display if the font doesn’t contain the requested character

• font (PIL.ImageFont) – Allows you to override the internal font by passing in an alternate

• default_table (int) – Select one of the ws0010’s four embedded font tables (see ws0010 documentation)

• embedded_font (str '5x8' or '5x10') – Select the size of the embedded font to use. Allowed sizes are 5x8 (default) and 5x10

• exec_time (float) – Time in seconds to wait for a command to complete. Default is 50 μs (1e-6 * 50)

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

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

Takes a 1-bit PIL.Image and dumps it to the ws0010 OLED display.

get_font(ft)

Load one of the devices embedded fonts by its index value or name and return it

Parameters

val (int or str) – The index or the name of the font to return

hide()

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

init_framebuffer(framebuffer)

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.oled.device.ws0010(serial_interface=None, width=100, height=16, undefined='_', font=None, selected_font=0, exec_time=4.9999999999999996e-05, rotate=0, framebuffer=None, const=<class 'luma.oled.const.ws0010'>, **kwargs)

Bases: parallel_device, character, __framebuffer_mixin

Serial interface to a monochrome Winstar WS0010 OLED display. This interface will work with most ws0010 powered devices including the weg010016.

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 pixels laid out horizontally.

• height (int) – The number of pixels laid out vertically.

• undefined (str) – The character to display if the font doesn’t contain the requested character

• font (PIL.ImageFont) – Allows you to override the internal font by passing in an alternate

• selected_font (int or str) – Select one of the ws0010’s embedded font tables (see note). Can be selected by number or name. Default is ‘FT00’ (English Japanese).

• exec_time (float) – Time in seconds to wait for a command to complete. Default is 50 μs (1e-6 * 50) which is enough for all ws0010 commands.

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

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 = ws0010(p, selected_font='FT01')
my_display.text = 'WS0010 Display\nFont FT01 5x8'

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

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

Takes a 1-bit PIL.Image and dumps it to the ws0010 OLED display.

get_font(ft)

Load one of the devices embedded fonts by its index value or name and return it

Parameters

val (int or str) – The index or the name of the font to return

hide()

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

init_framebuffer(framebuffer)

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.