SH1122 2.08 Inch OLED 256x64 Python Driver

This repository contains a driver for the SH1122 display controller, which is commonly used in various LCD and OLED displays. The driver supports basic operations such as drawing pixels, lines, and shapes, as well as displaying text and images.

Currently working and tested with CircuitPython and KMK firmware, this driver is designed to be easy to integrate into your projects.

SH1122 OLED Model

First of all, check the display model you have.

I bought the SH1122 2.08 Inch OLED display from HERE (AliExpress).

Specifications (copied from the product page):

• Screen Size: 2.08 inch
• Display Color: Monochrome (White or Blue)
• Operating Temperature: -20°C to 70°C
• Resolution: 256 × 64
• Power Supply: 2.8V to 3.3V
• Connection Method: COG
• Driver IC: SH1122
• Interface: 4-Wire SPI
• Module Dimensions: 75.50 × 20.60 × 5.60 mm
• Screen Dimensions: 62.50 × 20.60 × 1.63 mm
• Display Area: 51.18 × 12.78 mm

Driver

Requirements

• Obv, the SH1122 display module itself (connected via SPI).
• CircuitPython installed on your microcontroller.
• adafruit_framebuf library (check the "Install adafruit_framebuf library" section).

Installation

1. Download the sh1122.py and font5x8.bin files from this repository.
2. Copy the sh1122.py file to the lib folder on your CircuitPython device.
3. Copy the font5x8.bin file to the root directory of your CircuitPython device (needed from the library, idk if exists a way to avoid this).
4. Ensure you have the adafruit_framebuf library correctly installed on your CircuitPython device. If not, follow the instructions below.

Install adafruit_framebuf library

1. To install adafruit_framebuf, you have to download this bundle: https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases This is a collection of libraries designed specifically for CircuitPython.
2. Then unzip it and look inside the "lib" folder;
3. Then copy the 'adafruit_framebuf.py' (or "adafruit_framebuf.mpy" or similar) file into the 'lib' folder of your CircuitPython device.
4. Then you can import the library in your code as follows (or similar):

from lib import adafruit_framebuf as framebuf

Functionalities

• poweroff(): Turns the physical display OFF
• poweron(): Turns the physical display ON
• invert(): Inverts the display colors (white becomes black, and vice versa).
• show(): Transfers the internal 1-bit framebuffer to the display. Must be called after any drawing command.

As a inheritance of the native CircuitPython framebuf module, this driver supports a variety of drawing functions, including:

• pixel(x, y, color): Draw a single pixel at (x, y) with the specified color.
• line(x1, y1, x2, y2, color): Draw a line from (x1, y1) to (x2, y2) with the specified color. Also supports horizontal and vertical lines (hline and vline).
• rect(x, y, w, h, color): Draw a rectangle at (x, y) with width w and height h.
• fill_rect(x, y, w, h, color): Draw a filled rectangle
• fill(color): Fill the entire screen with the specified color.
• circle(x, y, r, color): Draw a circle centered at (x, y) with radius r.
• text(string, x, y, color): Draw text at (x, y) with the specified color.
• image(x, y, img): Draw an image at (x, y).
• ...and more.

Usage

Here is a simple example of how to initialize and use the SH1122 driver in your CircuitPython project:

import board
import digitalio
import bitbangio
from sh1122 import SH1122_SPI

#---------- DRIVER SH1122 INITIALIZATION ----------#

displayio.release_displays()

WIDTH  = 256
HEIGHT = 64

# Pins based on *MY* layout. Change them according to your wiring!
spi_sck_text = board.GP9
spi_mosi_text = board.GP10
display_res_text_pin = board.GP6
display_dc_text_pin = board.GP7
display_cs_text_pin = board.GP8

dc_text = digitalio.DigitalInOut(display_dc_text_pin)
dc_text.direction = digitalio.Direction.OUTPUT

res_text = digitalio.DigitalInOut(display_res_text_pin)
res_text.direction = digitalio.Direction.OUTPUT

cs_text = digitalio.DigitalInOut(display_cs_text_pin)
cs_text.direction = digitalio.Direction.OUTPUT

print("Control pins initialized.")

spi_text = bitbangio.SPI(clock=spi_sck_text, MOSI=spi_mosi_text)
print("SPI bus initialized.")

sh1122_display = SH1122_SPI(
    WIDTH, 
    HEIGHT,
    spi_text, 
    dc_text,  
    res_text, 
    cs_text   
)
#---------- DRIVER SH1122 INITIALIZED ----------#

# Now you can use the display object to draw on the screen
sh1122_display.text("Hello world!", 0, 0, 1)
sh1122_display.show()

Short-story-reason for creating this driver

I was creating a custom board for my desktop setup and needed a reliable way to interface with my SH1122 display using CircuitPython. After searching for existing solutions, I found that there were no python drivers available for the SH1122 controller. To fill this gap, I decided to develop my own driver, which I am now sharing.

I lost many days trying to figure out how to make it work (thanks to a lot of different online sources and Gemini AI, my best friend in last months hahaha), so I hope this driver will save you some time.

Thanks to

While looking for references, existing drivers and inspiration, I found this repo extremely helpful and I started from its code:

https://github.com/fdufnews/pico_examples/blob/main/drivers/sh1122.py from fdufnews.