ssd1306 — OLED Driver

This module provides a driver for SSD1306-based OLED displays. Two transport variants are supported: I2C (SSD1306_I2C) and SPI (SSD1306_SPI). Both inherit the drawing API from SSD1306, which wraps a framebuf.FrameBuffer1.

Example:

from machine import I2C, Pin
import ssd1306

i2c = I2C(0, scl=Pin(22), sda=Pin(21))
oled = ssd1306.SSD1306_I2C(128, 64, i2c)
oled.fill(0)
oled.text("Hello", 0, 0)
oled.show()

Classes

class ssd1306.SSD1306(width: int, height: int, external_vcc: bool)

Base class for SSD1306 OLED displays. Subclasses must initialize self.framebuf and provide write_cmd, write_data, write_framebuf and poweron methods.

Arguments:

  • width – Display width in pixels.

  • height – Display height in pixels (must be a multiple of 8).

  • external_vcc – True if an external VCC source is used, False to enable the internal charge pump.

Instance attributes:

  • width – Display width in pixels.

  • height – Display height in pixels.

  • external_vcc – External VCC flag.

  • pages – Number of 8-pixel-tall pages (height // 8).

init_display() → None

Send the initialization command sequence to the display, clear the framebuffer, and refresh. Called automatically by __init__.

poweroff() → None

Turn the display off (sleep mode).

contrast(contrast: int) → None

Set the display contrast.

  • contrast – Contrast value in the range 0–255.

invert(invert: int) → None

Invert the display colors.

  • invert – 0 for normal output, 1 for inverted output. Only the least significant bit is used.

show() → None

Flush the internal framebuffer to the display.

fill(col: int) → None

Fill the entire framebuffer with a single color.

  • col – Color value (0 for off, 1 for on).

pixel(x: int, y: int, col: int) → None

Set the color of a single pixel.

  • x – Column coordinate.

  • y – Row coordinate.

  • col – Color value (0 or 1).

scroll(dx: int, dy: int) → None

Shift the framebuffer contents by the given offsets. Pixels shifted out of bounds are lost; vacated pixels are left untouched.

  • dx – Horizontal shift in pixels.

  • dy – Vertical shift in pixels.

text(string: str, x: int, y: int, col: int = 1) → None

Draw a string using the built-in 8x8 font.

  • string – Text to draw.

  • x – Starting column coordinate.

  • y – Starting row coordinate.

  • col – Foreground color (default 1).

class ssd1306.SSD1306_I2C(width: int, height: int, i2c: machine.I2C, addr: int = 0x3C, external_vcc: bool = False)

I2C-connected SSD1306 driver. Inherits from SSD1306.

Arguments:

  • width – Display width in pixels.

  • height – Display height in pixels.

  • i2c – An initialized machine.I2C (or compatible) object.

  • addr – 7-bit I2C device address (default 0x3C).

  • external_vcc – True for external VCC, False to use the internal charge pump.

write_cmd(cmd: int) → None

Send a single command byte to the display over I2C.

write_data(buf: bytes) → None

Send a buffer of pixel data to the display over I2C.

class ssd1306.SSD1306_SPI(width: int, height: int, spi: machine.SPI, dc: machine.Pin, res: machine.Pin, cs: machine.Pin, external_vcc: bool = False)

SPI-connected SSD1306 driver. Inherits from SSD1306. Uses a fixed SPI clock rate of 10 MHz.

Arguments:

  • width – Display width in pixels.

  • height – Display height in pixels.

  • spi – A pyb.SPI (or compatible) object.

  • dc – Data/command select pin.

  • res – Reset pin.

  • cs – Chip-select pin.

  • external_vcc – True for external VCC, False to use the internal charge pump.

write_cmd(cmd: int) → None

Send a single command byte to the display over SPI.

write_framebuf() → None

Transmit the entire framebuffer to the display over SPI.

poweron() → None

Toggle the reset line to power the display on.

Constants

ssd1306.SET_CONTRAST: int

Command 0x81 – set display contrast.

ssd1306.SET_ENTIRE_ON: int

Command 0xA4 – resume display from RAM contents.

ssd1306.SET_NORM_INV: int

Command 0xA6 – normal/inverse display select.

ssd1306.SET_DISP: int

Command 0xAE – display on/off.

ssd1306.SET_MEM_ADDR: int

Command 0x20 – memory addressing mode.

ssd1306.SET_COL_ADDR: int

Command 0x21 – column address range.

ssd1306.SET_PAGE_ADDR: int

Command 0x22 – page address range.

ssd1306.SET_DISP_START_LINE: int

Command 0x40 – display start line.

ssd1306.SET_SEG_REMAP: int

Command 0xA0 – segment remap.

ssd1306.SET_MUX_RATIO: int

Command 0xA8 – multiplex ratio.

ssd1306.SET_COM_OUT_DIR: int

Command 0xC0 – COM output scan direction.

ssd1306.SET_DISP_OFFSET: int

Command 0xD3 – display offset.

ssd1306.SET_COM_PIN_CFG: int

Command 0xDA – COM pins hardware configuration.

ssd1306.SET_DISP_CLK_DIV: int

Command 0xD5 – display clock divide ratio / oscillator frequency.

ssd1306.SET_PRECHARGE: int

Command 0xD9 – pre-charge period.

ssd1306.SET_VCOM_DESEL: int

Command 0xDB – VCOMH deselect level.

ssd1306.SET_CHARGE_PUMP: int

Command 0x8D – charge pump configuration.