API Documentation¶
OLED display driver for SSD1306, SSD1325, SSD1331 and SH1106 devices.
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()
anddata()
methods are discouraged: Screen updates should be effected through thedisplay()
method, or preferably with theoled.render.canvas
context manager.-
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.
-
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
class
oled.emulator.
emulator
(width, height, rotate, mode, transform, scale)[source]¶ Bases:
oled.device.device
Base class for emulated OLED driver classes
-
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.
-
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 sosys.exit()
is called.
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.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: - oled.error.DeviceAddressError – I2C device address is invalid.
- oled.error.DeviceNotFoundError – I2C device could not be found.
- oled.error.DevicePermissionError – Permission to access I2C device denied.
Note
- Only one of
bus
ORport
arguments should be supplied; if both are, thenbus
takes precedence. - If
bus
is provided, there is an implicit expectation that it has already been opened.
-
class
oled.serial.
noop
[source]¶ Bases:
object
Does nothing, used for pseudo-devices / emulators, which dont have a serial interface.
-
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.
oled.threadpool
¶
-
class
oled.threadpool.
worker
(tasks)[source]¶ Bases:
threading.Thread
Thread executing tasks from a given tasks queue
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.
-
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 anPIL.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
andupdate()
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.
- create a
-
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.
-
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.
-
erase
()[source]¶ Erase the contents of the cursor’s current postion without moving the cursor’s position.
-
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.
-
-
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.
-
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
-