DIYables-MicroPython-OLED-SSD1309 1.0.0

MicroPython library for SSD1309-based monochrome OLED displays (I2C). Supports ESP32, Raspberry Pi Pico.

DIYables_MicroPython_OLED_SSD1309

MicroPython library for SSD1309-based monochrome OLED displays using the I2C interface.

Product Link: DIYables 2.4-inch OLED Display Module SSD1309 128×64

Features

• Supports 128×64, 128×32, 96×16, 64×48, and 64×32 display sizes
• Extends framebuf.FrameBuffer – all MicroPython drawing primitives available out of the box (pixel, fill, fill_rect, rect, line, hline, vline, text, blit, ellipse, poly, …)
• Hardware scrolling: right, left, diagonal right, diagonal left
• Contrast control and dim mode
• Power-off / power-on (sleep mode)
• Zero-copy show() – no temporary buffer allocation on each refresh
• Compatible with SoftI2C and hardware I2C
• Optional hardware reset pin support

Tested Hardware

Board	Tested
ESP32	✅
Raspberry Pi Pico	✅
DIYables ESP32 Development Board	✅
DIYables ESP32 S3, Uno-form factor	✅
Arduino Nano ESP32	Not yet, expected to work
Arduino Giga R1 WiFi	Not yet, expected to work
Other MicroPython boards	Not yet, expected to work

Tutorials

• ESP32 MicroPython – SSD1309 OLED
• Raspberry Pi Pico – SSD1309 OLED

References

• DIYables_MicroPython_OLED_SSD1309 Library Reference

Installation

Install via mpremote (recommended for MicroPython boards):

mpremote mip install DIYables-MicroPython-OLED-SSD1309

Or install via pip and copy to your board manually:

pip install DIYables-MicroPython-OLED-SSD1309

Quick Start

from machine import I2C, Pin
from DIYables_MicroPython_OLED_SSD1309 import OLED_SSD1309

# ESP32 – SDA=GPIO21, SCL=GPIO22
# Pico  – SDA=GP0,    SCL=GP1
i2c  = I2C(0, scl=Pin(22), sda=Pin(21), freq=400_000)
oled = OLED_SSD1309(128, 64, i2c)

oled.fill(0)
oled.text("Hello, World!", 0, 0)
oled.show()

Documentation

See DIYables_MicroPython_OLED_SSD1309 Library Reference for the complete API documentation including all constructors, methods, and constants.

Examples

Example	Description
hello_world.py	Display text using the built-in 8×8 font
draw_shapes.py	Draw pixels, lines, rectangles, and ellipses
scroll_text.py	Hardware scrolling (right, left, diagonal)
contrast_dim.py	Animate contrast level and use dim mode
bitmap.py	Display a monochrome bitmap image using blit()