MojoScale Studio Docs
API Reference

ssd1306

SSD1306 monochrome OLED display module.

All modules Open Studio
Studio Docs Displays

import ssd1306

The ssd1306 module controls 128 x 64 monochrome OLED displays over I2C or SPI. Use ``ssd1306.Display(...)`` to create an independent display object. Each object owns its own framebuffer, so two displays can be drawn and flushed separately.

Quick example

import ssd1306

oled = ssd1306.Display("i2c", 21, 22, 0x3c)
oled.clear()
oled.text(0, 0, "MojoScale", 1)
oled.rect(0, 14, 128, 18)
oled.text(4, 18, "READY", 2)
oled.end_frame()

left = ssd1306.Display("i2c", 21, 22, 0x3c)
right = ssd1306.Display("i2c", 21, 22, 0x3d)
left.text(0, 0, "LEFT", 1)
right.text(0, 0, "RIGHT", 1)
left.end_frame()
right.end_frame()

spi_oled = ssd1306.Display("spi", 23, 18, 5, 16, 17)

importssd1306

SSD1306 monochrome OLED display module.

The ssd1306 module controls 128 x 64 monochrome OLED displays over I2C or SPI. Use ``ssd1306.Display(...)`` to create an independent display object. Each object owns its own framebuffer, so two displays can be drawn and flushed separately.

API 18 available

ssd1306.Display(mode: int, sda_or_mosi: int, scl_or_sclk: int, address_or_cs: int = None, dc: int = None, rst: int = None) -> ssd1306_display

Create an independent SSD1306 display object.

Constructor forms: ``ssd1306.Display("i2c", sda, scl, address)`` ``ssd1306.Display("spi", mosi, sclk, cs, dc, rst)``

Parameters
Name Type Pass as Required Description
mode int positional Yes Positional string. Use "i2c" or "spi".
sda_or_mosi int positional Yes Positional integer. I2C SDA pin, or SPI MOSI pin.
scl_or_sclk int positional Yes Positional integer. I2C SCL pin, or SPI SCLK pin.
address_or_cs int positional or keyword No Positional integer. I2C address such as 0x3c, or SPI CS pin.
dc int positional or keyword No Positional integer. SPI data/command pin. Required for SPI.
rst int positional or keyword No Positional integer. SPI reset pin. Use -1 when reset is not connected.
Returns

ssd1306_display ssd1306_display object with drawing and display-control methods. Notes: Multiple I2C displays can share the same SDA/SCL pins when each display has a different I2C address.

ssd1306.begin(mode: int, sda_or_mosi: int, scl_or_sclk: int, address_or_cs: int = None, dc: int = None, rst: int = None) -> None

Legacy: initialize one module-level default SSD1306 display.

Prefer ``oled = ssd1306.Display(...)`` for new code. The legacy default display exists for older scripts that call drawing methods on the module.

Parameters
Name Type Pass as Required Description
mode int positional Yes Positional string. Use "i2c" or "spi".
sda_or_mosi int positional Yes Positional integer. I2C SDA pin, or SPI MOSI pin.
scl_or_sclk int positional Yes Positional integer. I2C SCL pin, or SPI SCLK pin.
address_or_cs int positional or keyword No Positional integer. I2C address such as 0x3c, or SPI CS pin.
dc int positional or keyword No Positional integer. SPI data/command pin. Required for SPI.
rst int positional or keyword No Positional integer. SPI reset pin. Use -1 when reset is not connected.
Returns

None None.

ssd1306.width() -> int

Legacy: return the default display width.

Returns

int int. Width in pixels.

ssd1306.height() -> int

Legacy: return the default display height.

Returns

int int. Height in pixels.

ssd1306.begin_frame() -> None

Legacy: start a drawing frame on the default display.

Returns

None None.

ssd1306.end_frame() -> None

Legacy: flush the default display framebuffer.

Returns

None None.

ssd1306.clear(color: any = None) -> None

Legacy: clear the default display framebuffer.

Parameters
Name Type Pass as Required Description
color any positional or keyword No Optional keyword integer. Pixel value used to clear. Defaults to 0.
Returns

None None.

ssd1306.pixel(x: int, y: int, color: any) -> None

Legacy: draw one pixel on the default display.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Positional or keyword integer. Pixel x coordinate.
y int positional or keyword Yes Positional or keyword integer. Pixel y coordinate.
color any positional or keyword Yes Positional or keyword integer. Pixel value, usually 0 or 1.
Returns

None None.

ssd1306.line(x1: any, y1: any, x2: any, y2: any, color: any = None) -> None

Legacy: draw a straight line on the default display.

Parameters
Name Type Pass as Required Description
x1 any positional or keyword Yes Positional or keyword integer. Start pixel x coordinate.
y1 any positional or keyword Yes Positional or keyword integer. Start pixel y coordinate.
x2 any positional or keyword Yes Positional or keyword integer. End pixel x coordinate.
y2 any positional or keyword Yes Positional or keyword integer. End pixel y coordinate.
color any positional or keyword No Optional keyword integer. Pixel value, usually 0 or 1. Defaults to 1.
Returns

None None.

ssd1306.rect(x: int, y: int, width: int, height: int, color: any = None) -> None

Legacy: draw a rectangle outline on the default display.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Positional or keyword integer. Left pixel coordinate.
y int positional or keyword Yes Positional or keyword integer. Top pixel coordinate.
width int positional or keyword Yes Positional or keyword integer. Rectangle width in pixels.
height int positional or keyword Yes Positional or keyword integer. Rectangle height in pixels.
color any positional or keyword No Optional keyword integer. Pixel value, usually 0 or 1. Defaults to 1.
Returns

None None.

ssd1306.fill_rect(x: int, y: int, width: int, height: int, color: any = None) -> None

Legacy: fill a rectangle on the default display.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Positional or keyword integer. Left pixel coordinate.
y int positional or keyword Yes Positional or keyword integer. Top pixel coordinate.
width int positional or keyword Yes Positional or keyword integer. Rectangle width in pixels.
height int positional or keyword Yes Positional or keyword integer. Rectangle height in pixels.
color any positional or keyword No Optional keyword integer. Pixel value, usually 0 or 1. Defaults to 1.
Returns

None None.

ssd1306.text(x: int, y: int, text: str, size: any = None, color: any = None) -> None

Legacy: draw text on the default display.

Text is drawn into the framebuffer. Call ``end_frame()`` to show it on the OLED.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Positional or keyword integer. Left pixel coordinate.
y int positional or keyword Yes Positional or keyword integer. Top pixel coordinate.
text str positional or keyword Yes Positional or keyword string. ASCII text to draw.
size any positional or keyword No Optional keyword integer. Font scale. Defaults to 1.
color any positional or keyword No Optional keyword integer. Pixel value, usually 0 or 1. Defaults to 1.
Returns

None None.

ssd1306.text_width(text: str, size: any = None) -> int

Legacy: measure text width for the default display font.

Parameters
Name Type Pass as Required Description
text str positional or keyword Yes Positional or keyword string. Text to measure.
size any positional or keyword No Optional keyword integer. Font scale. Defaults to 1.
Returns

int int. Width in pixels.

ssd1306.bitmap(x: int, y: int, data: any, width: int, height: int, color: any = None) -> None

Legacy: draw a monochrome bitmap on the default display.

The data payload is row-major, one bit per pixel, MSB first in each byte. Set bits are drawn with ``color``; unset bits are transparent.

Parameters
Name Type Pass as Required Description
x int positional or keyword Yes Positional or keyword integer. Left pixel coordinate.
y int positional or keyword Yes Positional or keyword integer. Top pixel coordinate.
data any positional or keyword Yes Positional or keyword bytes. Bitmap bit payload.
width int positional or keyword Yes Positional or keyword integer. Bitmap width in pixels.
height int positional or keyword Yes Positional or keyword integer. Bitmap height in pixels.
color any positional or keyword No Optional keyword integer. Pixel value, usually 0 or 1. Defaults to 1.
Returns

None None.

ssd1306.invert(enabled: bool = None) -> None

Legacy: invert or restore the default physical OLED output.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword No Optional keyword bool. True inverts output; False restores normal output.
Returns

None None.

ssd1306.contrast(value: any) -> None

Legacy: set contrast on the default display.

Parameters
Name Type Pass as Required Description
value any positional or keyword Yes Positional or keyword integer. Contrast value from 0 to 255.
Returns

None None.

ssd1306.power(enabled: bool) -> None

Legacy: turn the default OLED panel on or off.

Parameters
Name Type Pass as Required Description
enabled bool positional or keyword Yes Positional or keyword bool. True turns the panel on; False turns it off.
Returns

None None.

ssd1306.caps() -> int

Legacy: return default display capability flags.

Returns

int int. Native capability bitmask.