MicroPython driver for SH1107-based OLED displays with support for I2C and SPI connections. This driver works with 128x128 and 128x64 pixel displays. (For a list of tested displays, see: tested displays, below.)
This driver was derived from the SH1106 driver made by @robert-hh and others. It has been adapted for the SH1107 and incorporates several enhancements.
The large text, triangle and circle methods in the MicroPython FrameBuffer extension framebuf2 are supported, as are the ellipse and poly methods added to the FrameBuffer class in MicroPython version 1.20.0.
Note: from version release v1.3.0 (build v317) which added support for 128x64 displays, the use of the rotate parameter has changed. Thus, for a previous setting of 90 (degrees), 0 should now be used and similarly for 0, 180, and 270, values of 270, 90 and 180 respectively should be used instead.
This driver offers screen rotation: the screen can be initialised at 0, 90, 180 or 270 degrees rotation. The rotation can be changed by 180 degrees after initialisation, but not by 90 degrees clock-wise or anti-clockwise. This is because 90 and 270 degrees use a different framebuffer mode and screen updating method which are set on initialisation.
The driver includes some optimisation for partial screen updates which typically reduce the amount of data written to the screen and increase the speed of updates and display responsiveness. With an I2C connection at 400,000 bps a 128x128 display will achieve about 16 frames per second when orientated at 90 or 270 degrees and 10 frames per second at 0 or 180 degrees. Partial updates are faster, for example, 1 row of text can be updated in around 5 milliseconds (tested values using a Raspberry Pi pico at standard clock speed). Faster updates can be achieved by running the I2C connection at 1,000,000 bps (although this is faster than the rated speed for the SH1107).
An SPI connection at 40 MHz can achieve full screen updates in around 5ms when orientated at 90 or 270 degrees and about 20ms at 0 or 180 degrees. Updates for 128x64 displays are faster.
The driver builds in the facility to use the large_text(), triangle() and circle() methods in the MicroPython FrameBuffer extension framebuf2. Moreover, some limited hardware scrolling functionality can be used with the display_start_line() method.
SCL and SDA have to be connected as minimum. The driver can reset the device with the reset PIN (this is not required for some displays, for example those tested).
SCLK, MOSI, D/C are always required. If the display is the only SPI device, CS may be tied to GND. Reset has also to be connected, unless it is driven by an external circuit.
The sh1107.py module code should be uploaded to the Raspberry Pico Pi (or other Microcontroller running MicroPython). The large font, triangle and circles extension is added by additionally uploading the framebuf2.py module code. (See framebuf2.)
The module includes the class SH1107 and the derived classes SH1107_I2C and SH1107_SPI. The I2C and SPI classes provide equivalent methods.
display = sh1107.SH1107_I2C(width,
height,
i2c,
res=None,
address=0x3d,
rotate=0,
external_vcc=False,
delay_ms=200)display = sh1107.SH1107_SPI(width,
height,
spi,
dc,
res=None,
cs=None,
rotate=0,
external_vcc=False,
delay_ms=100)The following methods and properties are available for controlling the display
poweron()
poweroff() - the display memory is retained in this state, power consumption is reduced to a <5uA for the display (other components on a board may increase this, of course)
sleep(value) - sleep(0) calls poweron(); sleep() or sleep(1) calls poweroff()
is_awake() this property returns the sleep (False) / wake (True) status of the display
show(full_update=False) - this method updates the display from the framebuffer. It has some optimisation to to update only areas of the screen with changes. To force a complete update of the screen, set the optional full_update parameter to True
contrast() - this command effectively sets the screen brightness. segment power consumption is proportional to screen contrast. valid values are in the range 0 to 255. the SH1107 default power on value is 128, however this module initialises the display with the contrast set to zero
invert(invert) - this method inverts the display to black on white, instead of black on white. the parameter invert takes the values True or False
flip(flag=None, update=True) - if no value is provided for the flag parameter the screen is rotated by 180 degrees from its current orientation, otherwise if the flag parameter is set to True, the screen rotation is set to 180 degrees, or 0 degrees for False. A full screen update is performed unless update is set to False
display_start_line() - provides some limited scrolling
The driver works with all MicroPython FrameBuffer drawing methods (as at MicroPython 1.20.0). The syntax of the fill_rect method available in versions 1.19.1 and earlier (but not 1.20.0) is also supported.
from machine import Pin, I2C
import sh1107
i2c0 = I2C(0, scl=Pin(5), sda=Pin(4), freq=400000)
display = sh1107.SH1107_I2C(128, 128, i2c0, address=0x3d, rotate=90)
display.sleep(False)
display.fill(0)
display.text('SH1107', 0, 0, 1)
display.text('driver', 0, 8, 1)
display.show()See example code for further details and usage demonstrations of other methods. (The example code was written for 128x128 displays and has only been partially adapted for 64x128 displays.)
Example code for SPI is included in the repository. (The code was written for 128x128 displays and has only been partially adapted for 64x128 displays.)
This driver has been tested with a Raspberry Pi Pico and the displays listed below. It should work with other 128x128 and 128x64 size displays. (Whilst the code works with the tested displays, other 128x64 displays might need changes to some setup/control parameters, depending on how the display panel is connected to the driver IC.)
This code has been tested with MicroPython versions 1.18, 1.19.1 and 1.20.0.
The MicroPython FrameBuffer extension framebuf2 is recommended for its large text, triangle and circle methods.
0xad81 from 0xad8d is_awake property addedSH1107_SPI.write_command() and SH1107_SPI.write_data()fill_rect() method for compatibility with the "latest" MicroPython releaseset_start_line() method which implements scrolling in one direction (whether x or y depends on display orientation)_SET_DISPLAY_OFFSET constant and included display offset command in start-up sequence.