Metadata-Version: 2.4
Name: DIYables-MicroPython-OLED-SSD1309
Version: 1.0.0
Summary: MicroPython library for SSD1309-based monochrome OLED displays (I2C). Supports ESP32, Raspberry Pi Pico.
Home-page: https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64
Author: DIYables
Author-email: DIYables <DIYables.io@gmail.com>
License: MIT
Project-URL: Homepage, https://diyables.io
Project-URL: Repository, https://github.com/DIYables/DIYables_MicroPython_OLED_SSD1309
Keywords: micropython,oled,ssd1309,i2c,display,DIYables,ESP32,Raspberry Pi Pico,framebuf
Classifier: Programming Language :: Python :: Implementation :: MicroPython
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.4
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

## DIYables_MicroPython_OLED_SSD1309

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

![SSD1309 OLED Display](https://diyables.io/images/products/2.4-inch-oled-display-module-ssd1309-128x64-1.jpg)

Product Link: [DIYables 2.4-inch OLED Display Module SSD1309 128×64](https://diyables.io/products/2.4-inch-oled-display-module-ssd1309-128x64)


## 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](https://diyables.io/esp32-board) | ✅ |
| [DIYables ESP32 S3, Uno-form factor](https://diyables.io/products/esp32-s3-development-board-with-esp32-s3-wroom-1-n16r8-wifi-bluetooth-uno-compatible-form-factor-works-with-arduino-ide) | ✅ |
| 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](https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-ssd1309-oled-display)
- [Raspberry Pi Pico – SSD1309 OLED](https://newbiely.com/tutorials/raspberry-pico/raspberry-pi-pico-ssd1309-oled-display)


## References

- [DIYables_MicroPython_OLED_SSD1309 Library Reference](https://newbiely.com/library-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

```python
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](https://newbiely.com/library-references/diyables-micropython-oled-ssd1309-library-reference) for the complete API documentation including all constructors, methods, and constants.


## Examples

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