Built-in project · Raspberry Pi 4 Model B

SSD1306 OLED on a Pi with smbus2, on a Raspberry Pi 4

A Raspberry Pi 4 draws text on an SSD1306 OLED over I2C bus 1 with smbus2: an uptime counter each second, and how long each frame takes at 100 kHz. The whole build, a Raspberry Pi 4 and 1 more part, runs here in your browser on the Python below; open it in the editor to change the wiring or the code and run it again.

Open in the editor Read the code

Teaching? Assign it to your class in one click.

Intermediate Runs in your browser. Free, and no account needed.

The parts retail for about $59. On Mokxi they're free.

SSD1306 OLED on a Pi with smbus2 · Raspberry Pi 4 Model Blive0.000 s 0.00x

Click to open it in the editor

The circuit itself, running here on the simulator. Press what can be pressed; click anything else to open it in the editor.

The code

The Python exactly as the editor opens it. Change a line there and press Run: the board runs main.py in a Python engine in the page, with gpiozero and RPi.GPIO, and nothing to compile.

main.py · Raspberry Pi 4 Model B

# An SSD1306 OLED on a Raspberry Pi 4, over smbus2.
# SDA to GPIO2 (pin 3), SCL to GPIO3 (pin 5), VCC to 3V3 (pin 1), GND (pin 9).
# ssd1306_smbus.py is a small driver in its own tab.
import time
from ssd1306_smbus import SSD1306

oled = SSD1306(bus=1, address=0x3C)   # /dev/i2c-1, the header's I2C bus
start = time.monotonic()

while True:
    seconds = int(time.monotonic() - start)
    oled.fill(0)
    oled.text("Hello, Pi!", 0, 0)
    oled.text("smbus2 on i2c-1", 0, 16)
    oled.text("up %d s" % seconds, 0, 40)
    t = time.monotonic()
    oled.show()                       # 1 KB at 100 kHz: about a tenth of a second
    print("frame", seconds, "took %.0f ms" % ((time.monotonic() - t) * 1000))
    time.sleep(1)

ssd1306_smbus.py · Raspberry Pi 4 Model B

# ssd1306_smbus.py: a small SSD1306 OLED driver for a Raspberry Pi, over
# smbus2 on /dev/i2c-1, the way the classic Raspberry Pi tutorials drive the
# 0.96 inch module: commands with control byte 0x00, the picture in 16-byte
# blocks with control byte 0x40. Runs unchanged on a real Pi with
# "pip install smbus2". Text is MicroPython's 8x8 font (font_petme128_8x8,
# MIT licensed, Copyright (c) 2013, 2014 Damien P. George).

from smbus2 import SMBus

FONT = bytes.fromhex(
    '00000000000000000000004f4f0000000007070000070700147f7f14147f7f14'
    '00242e6b6b3a1200006333180c66630000327f4d4d7772500000000406030100'
    '00001c3e63410000000041633e1c0000082a3e1c1c3e2a080008083e3e080800'
    '000080e0600000000008080808080800000000606000000000406030180c0602'
    '003e7f49457f3e000040447f7f40400000627351494f460000226349497f3600'
    '00181814167f7f1000276745457d3900003e7f49497b3200000303797d070300'
    '00367f49497f360000266f49497f3e000000002424000000000080e464000000'
    '00081c3663414100001414141414140000414163361c080000020351590f0600'
    '003e7f414d4f2e00007c7e0b0b7e7c00007f7f49497f3600003e7f4141632200'
    '007f7f41633e1c00007f7f4949414100007f7f0909010100003e7f41497b3a00'
    '007f7f08087f7f000000417f7f410000002060417f3f0100007f7f1c36634100'
    '007f7f4040404000007f7f060c067f7f007f7f0e1c7f7f00003e7f41417f3e00'
    '007f7f09090f0600001e3f21617f5e00007f7f19396f460000266f49497b3200'
    '0001017f7f010100003f7f40407f3f00001f3f60603f1f00007f7f3018307f7f'
    '0063771c1c77630000070f78780f0700006171594d47430000007f7f41410000'
    '0002060c18306040000041417f7f000000080c06060c0800c0c0c0c0c0c0c0c0'
    '000001030604000000207454547c7800007f7f44447c380000387c44446c2800'
    '00387c44447f7f0000387c54545c580000087e7f090302000098bca4a4fc7c00'
    '007f7f04047c78000000007d7d0000000040c08080fd7d00007f7f30386c4400'
    '0000417f7f400000007c7c1830187c7c007c7c04047c780000387c44447c3800'
    '00fcfc24243c180000183c2424fcfc00007c7c04040c080000485c5454742000'
    '04043f7f44642000003c7c40407c3c00001c3c60603c1c00001c7c3018307c1c'
    '00446c38386c4400009cbca0a0fc7c00004464745c4c44000008083e77414100'
    '000000ffff000000004141773e0808000002030103020301aa55aa55aa55aa55'
)


class SSD1306:
    def __init__(self, bus=1, address=0x3C, width=128, height=64):
        self.i2c = SMBus(bus) if isinstance(bus, int) else bus
        self.address = address
        self.width = width
        self.height = height
        self.pages = height // 8
        self.buffer = bytearray(width * self.pages)
        self.command(
            0xAE,                    # display off
            0xD5, 0x80,              # clock divide
            0xA8, height - 1,        # multiplex ratio
            0xD3, 0x00,              # display offset
            0x40,                    # start line 0
            0x8D, 0x14,              # charge pump on
            0x20, 0x00,              # horizontal addressing
            0xA1, 0xC8,              # the module's orientation
            0xDA, 0x12 if height == 64 else 0x02,
            0x81, 0xCF,              # contrast
            0xD9, 0xF1,              # pre-charge
            0xDB, 0x40,              # VCOMH
            0xA4, 0xA6,              # show RAM, not inverted
            0xAF,                    # display on
        )

    def command(self, *cmds):
        for c in cmds:
            self.i2c.write_byte_data(self.address, 0x00, c)

    def fill(self, color):
        value = 0xFF if color else 0x00
        for i in range(len(self.buffer)):
            self.buffer[i] = value

    def pixel(self, x, y, color=1):
        if 0 <= x < self.width and 0 <= y < self.height:
            i = (y // 8) * self.width + x
            if color:
                self.buffer[i] |= 1 << (y % 8)
            else:
                self.buffer[i] &= ~(1 << (y % 8)) & 0xFF

    def text(self, string, x, y, color=1):
        for n, ch in enumerate(string):
            code = ord(ch)
            if not 32 <= code <= 127:
                code = 127
            glyph = FONT[(code - 32) * 8:(code - 32) * 8 + 8]
            for col in range(8):
                bits = glyph[col]
                for row in range(8):
                    if bits >> row & 1:
                        self.pixel(x + n * 8 + col, y + row, color)

    def show(self):
        self.command(0x21, 0, self.width - 1, 0x22, 0, self.pages - 1)
        for i in range(0, len(self.buffer), 16):
            self.i2c.write_i2c_block_data(self.address, 0x40, list(self.buffer[i:i + 16]))