API Documentation

OLED display driver for SSD1306, SSD1325, SSD1331 and SH1106 devices.

Inheritance diagram of oled.device, oled.emulator, oled.mixin, oled.virtual

oled.device

class oled.device.device(const=None, serial_interface=None)[source]

Bases: oled.mixin.capabilities

Base class for OLED driver classes

Warning

Direct use of the command() and data() methods are discouraged: Screen updates should be effected through the display() method, or preferably with the oled.render.canvas context manager.

cleanup()[source]
command(*cmd)[source]

Sends a command or sequence of commands through to the delegated serial interface.

contrast(level)[source]

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.

hide()[source]

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

show()[source]

Sets the display mode ON, waking the device out of a prior low-power sleep mode.

class oled.device.sh1106(serial_interface=None, width=128, height=64, rotate=0)[source]

Bases: oled.device.device

Encapsulates the serial interface to the monochrome SH1106 OLED display hardware. 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.

display(image)[source]

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

class oled.device.ssd1306(serial_interface=None, width=128, height=64, rotate=0)[source]

Bases: oled.device.device

Encapsulates the serial interface to the monochrome SSD1306 OLED display hardware. 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.

display(image)[source]

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

class oled.device.ssd1325(serial_interface=None, width=128, height=64, rotate=0)[source]

Bases: oled.device.device

Encapsulates the serial interface to the 4-bit greyscale SSD1325 OLED display hardware. 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.

display(image)[source]

Takes a 24-bit RGB PIL.Image and dumps it to the SSD1325 OLED display, converting the image pixels to 4-bit greyscale using a simplified Luma calculation, based on Y’=0.299R’+0.587G’+0.114B’.

class oled.device.ssd1331(serial_interface=None, width=96, height=64, rotate=0)[source]

Bases: oled.device.device

Encapsulates the serial interface to the 16-bit color (5-6-5 RGB) SSD1331 OLED display hardware. 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.

contrast(level)[source]

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.
display(image)[source]

Takes a 24-bit RGB PIL.Image and dumps it to the SSD1331 OLED display.

oled.emulator

class oled.emulator.capture(width=128, height=64, rotate=0, mode='RGB', transform='scale2x', scale=2, file_template='oled_{0:06}.png', **kwargs)[source]

Bases: oled.emulator.emulator

Pseudo-device that acts like an OLED display, except that it writes the image to a numbered PNG file when the display() method is called.

While the capability of an OLED device is monochrome, there is no limitation here, and hence supports 24-bit color depth.

display(image)[source]

Takes a PIL.Image and dumps it to a numbered PNG file.

class oled.emulator.dummy(width=128, height=64, rotate=0, mode='RGB', transform='scale2x', scale=2, **kwargs)[source]

Bases: oled.emulator.emulator

Pseudo-device that acts like an OLED display, except that it does nothing other than retain a copy of the displayed image. It is mostly useful for testing. While the capability of an OLED device is monochrome, there is no limitation here, and hence supports 24-bit color depth.

display(image)[source]

Takes a PIL.Image and makes a copy of it for later use/inspection.

class oled.emulator.emulator(width, height, rotate, mode, transform, scale)[source]

Bases: oled.device.device

Base class for emulated OLED driver classes

cleanup()[source]
to_surface(image)[source]

Converts a PIL.Image into a pygame.Surface, transforming it according to the transform and scale constructor arguments.

class oled.emulator.gifanim(width=128, height=64, rotate=0, mode='RGB', transform='scale2x', scale=2, filename='oled_anim.gif', duration=0.01, loop=0, max_frames=None, **kwargs)[source]

Bases: oled.emulator.emulator

Pseudo-device that acts like an OLED display, except that it collects the images when the display() method is called, and on exit, assembles them into an animated GIF image.

While the capability of an OLED device is monochrome, there is no limitation here, and hence supports 24-bit color depth, albeit with an indexed color palette.

display(image)[source]

Takes an image, scales it according to the nominated transform, and stores it for later building into an animated GIF.

write_animation()[source]
class oled.emulator.pygame(width=128, height=64, rotate=0, mode='RGB', transform='scale2x', scale=2, frame_rate=60, **kwargs)[source]

Bases: oled.emulator.emulator

Pseudo-device that acts like an OLED display, except that it renders to an displayed window. The frame rate is limited to 60FPS (much faster than a Raspberry Pi can acheive, but this can be overridden as necessary).

While the capability of an OLED device is monochrome, there is no limitation here, and hence supports 24-bit color depth.

pygame is used to render the emulated display window, and it’s event loop is checked to see if the ESC key was pressed or the window was dismissed: if so sys.exit() is called.

display(image)[source]

Takes a PIL.Image and renders it to a pygame display surface.

class oled.emulator.transformer(pygame, width, height, scale)[source]

Bases: object

Helper class used to dispatch transformation operations.

identity(surface)[source]

Fast scale operation that does not sample the results

none(surface)[source]

No-op transform - used when scale = 1

scale2x(surface)[source]

Scales using the AdvanceMAME Scale2X algorithm which does a ‘jaggie-less’ scale of bitmap graphics.

smoothscale(surface)[source]

Smooth scaling using MMX or SSE extensions if available

oled.error

Exceptions for this library.

exception oled.error.DeviceAddressError[source]

Bases: oled.error.Error

Exception raised when an invalid device address is detected.

exception oled.error.DeviceDisplayModeError[source]

Bases: oled.error.Error

Exception raised when an invalid device display mode is detected.

exception oled.error.DeviceNotFoundError[source]

Bases: oled.error.Error

Exception raised when a device cannot be found.

exception oled.error.DevicePermissionError[source]

Bases: oled.error.Error

Exception raised when permission to access the device is denied.

exception oled.error.Error[source]

Bases: exceptions.Exception

Base class for exceptions in this library.

oled.mixin

class oled.mixin.capabilities[source]

Bases: object

capabilities(width, height, rotate, mode='1')[source]
clear()[source]

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

display(image)[source]
preprocess(image)[source]

oled.render

class oled.render.canvas(device, dither=False)[source]

A canvas returns a properly-sized PIL.ImageDraw object onto which the caller can draw upon. As soon as the with-block completes, the resultant image is flushed onto the device.

By default, any color (other than black) will be treated as white and displayed on the device. However, this behaviour can be changed by adding dither=True and the image will be converted from RGB space into a 1-bit monochrome image where dithering is employed to differentiate colors at the expense of resolution.

oled.serial

class oled.serial.i2c(bus=None, port=1, address=60)[source]

Bases: object

Wrap an I2C interface to provide data and command methods.

Parameters:
  • bus – I2C bus instance.
  • port (int) – I2C port number.
  • address – I2C address.
Raises:

Note

  1. Only one of bus OR port arguments should be supplied; if both are, then bus takes precedence.
  2. If bus is provided, there is an implicit expectation that it has already been opened.
cleanup()[source]

Clean up I2C resources

command(*cmd)[source]

Sends a command or sequence of commands through to the I2C address - maximum allowed is 32 bytes in one go.

data(data)[source]

Sends a data byte or sequence of data bytes through to the I2C address - maximum allowed in one transaction is 32 bytes, so if data is larger than this, it is sent in chunks.

class oled.serial.noop[source]

Bases: object

Does nothing, used for pseudo-devices / emulators, which dont have a serial interface.

cleanup()[source]
command(*cmd)[source]
data(data)[source]
class oled.serial.spi(spi=None, gpio=None, port=0, device=0, bus_speed_hz=8000000, bcm_DC=24, bcm_RST=25)[source]

Bases: object

Wraps an SPI interface to provide data and command methods.

  • The DC pin (Data/Command select) defaults to GPIO 24 (BCM).
  • The RST pin (Reset) defaults to GPIO 25 (BCM).
Raises:oled.error.DeviceNotFoundError – SPI device could not be found.
cleanup()[source]

Clean up SPI & GPIO resources

command(*cmd)[source]

Sends a command or sequence of commands through to the SPI device.

data(data)[source]

Sends a data byte or sequence of data bytes through to the SPI device. If the data is more than 4Kb in size, it is sent in chunks.

oled.threadpool

class oled.threadpool.threadpool(num_threads)[source]

Pool of threads consuming tasks from a queue

add_task(func, *args, **kargs)[source]

Add a task to the queue

wait_completion()[source]

Wait for completion of all the tasks in the queue

class oled.threadpool.worker(tasks)[source]

Bases: threading.Thread

Thread executing tasks from a given tasks queue

run()[source]

oled.virtual

oled.virtual.calc_bounds(xy, entity)[source]

For an entity with width and height attributes, determine the bounding box if were positioned at (x, y).

class oled.virtual.history(device)[source]

Bases: oled.mixin.capabilities

Wraps a device (or emulator) to provide a facility to be able to make a savepoint (a point at which the screen display can be “rolled-back” to).

This is mostly useful for displaying transient error/dialog messages which could be subsequently dismissed, reverting back to the previous display.

display(image)[source]
restore(drop=0)[source]

Restores the last savepoint. If drop is supplied and greater than zero, then that many savepoints are dropped, and the next savepoint is restored.

savepoint()[source]

Copies the last displayed image.

class oled.virtual.hotspot(width, height, draw_fn=None)[source]

Bases: oled.mixin.capabilities

A hotspot (a place of more than usual interest, activity, or popularity) is a live display which may be added to a virtual viewport - if the hotspot and the viewport are overlapping, then the update() method will be automatically invoked when the viewport is being refreshed or its position moved (such that an overlap occurs).

You would either:

  • create a hotspot instance, suppling a render function (taking an PIL.ImageDraw object, width & height dimensions. The render function should draw within a bounding box of (0, 0, width, height), and render a full frame.
  • sub-class hotspot and override the :func:should_redraw and update() methods. This might be more useful for slow-changing values where it is not necessary to update every refresh cycle, or your implementation is stateful.
paste_into(image, xy)[source]
should_redraw()[source]

Override this method to return true or false on some condition (possibly on last updated member variable) so that for slow changing hotspots they are not updated too frequently.

update(draw)[source]
oled.virtual.range_overlap(a_min, a_max, b_min, b_max)[source]

Neither range is completely greater than the other

class oled.virtual.snapshot(width, height, draw_fn=None, interval=1.0)[source]

Bases: oled.virtual.hotspot

A snapshot is a type of hotspot, but only updates once in a given interval, usually much less frequently than the viewport requests refresh updates.

paste_into(image, xy)[source]
should_redraw()[source]

Only requests a redraw after interval seconds have elapsed

class oled.virtual.terminal(device, font=None, color='white', bgcolor='black', tabstop=4, line_height=None, animate=True)[source]

Bases: object

Provides a terminal-like interface to a device (or a device-like object that has mixin.capabilities characteristics).

backspace()[source]

Moves the cursor one place to the left, erasing the character at the current position. Cannot move beyound column zero, nor onto the previous line

carriage_return()[source]

Returns the cursor position to the left-hand side without advancing downwards.

clear()[source]

Clears the display and resets the cursor position to (0, 0).

erase()[source]

Erase the contents of the cursor’s current postion without moving the cursor’s position.

flush()[source]

Cause the current backing store to be rendered on the nominated device.

newline()[source]

Advances the cursor position ot the left hand side, and to the next line. If the cursor is on the lowest line, the displayed contents are scrolled, causing the top line to be lost.

println(text='')[source]

Prints the supplied text to the device, scrolling where necessary. The text is always followed by a newline.

putch(ch, flush=True)[source]

Prints the specific character, which must be a valid printable ASCII value in the range 32..127 only.

puts(text)[source]

Prints the supplied text, handling special character codes for carriage return (r), newline (n), backspace (b) and tab (t).

If the animate flag was set to True (default), then each character is flushed to the device, giving the effect of 1970’s teletype device.

tab()[source]

Advances the cursor position to the next (soft) tabstop.

class oled.virtual.viewport(device, width, height)[source]

Bases: oled.mixin.capabilities

add_hotspot(hotspot, xy)[source]

Add the hotspot at (x, y). The hotspot must fit inside the bounds of the virtual device. If it does not then an AssertError is raised.

display(image)[source]
is_overlapping_viewport(hotspot, xy)[source]

Checks to see if the hotspot at position (x, y) is (at least partially) visible according to the position of the viewport

refresh()[source]
remove_hotspot(hotspot, xy)[source]

Remove the hotspot at (x, y): Any previously rendered image where the hotspot was placed is erased from the backing image, and will be “undrawn” the next time the virtual device is refreshed. If the specified hotspot is not found (x, y), a ValueError is raised.

set_position(xy)[source]