rpi-display-core

rpi-display-core is a Python display framework for Raspberry Pi projects.

Today it supports SSD1306 and SH1106 OLED displays through dedicated backends under rpi_display.displays, while keeping the shared drawing and widget framework generic.

Install

From the repository

git clone https://github.com/andremmfaria/rpi-display-core.git
cd rpi-display-core
uv sync

From PyPI

uv add rpi-display-core

Import it as:

from rpi_display import Runner, canvas
from rpi_display.displays.ssd1306 import SSD1306Display

What it provides

• rpi_display.displays.ssd1306.SSD1306Display — SSD1306 display wrapper for Raspberry Pi
• rpi_display.displays.sh1106.SH1106Display — SH1106 display wrapper for Raspberry Pi
• canvas(display) — context manager that creates a fresh PIL image and flushes it on exit
• Runner — simple fixed-FPS render loop
• MockDisplay — hardware-free test helper
• Built-in widgets for text, progress bars, clocks, network info, system stats, and spinners

Quick example

from rpi_display import Runner
from rpi_display.displays.ssd1306 import SSD1306Display
from rpi_display.widgets.clock import ClockWidget

Runner(SSD1306Display(), ClockWidget(), fps=1).run()

Display integrations

from rpi_display.displays.ssd1306 import SSD1306Display
from rpi_display.displays.sh1106 import SH1106Display

Other display chips can follow the same pattern under rpi_display.displays.

Widget modules

from rpi_display.widgets.text import Text, MultiLineText, ScrollingText
from rpi_display.widgets.shapes import ProgressBar
from rpi_display.widgets.clock import ClockWidget
from rpi_display.widgets.system import SystemStatsWidget
from rpi_display.widgets.network import NetworkWidget
from rpi_display.widgets.spinner import Spinner

Examples

The repository includes ready-to-run examples in examples/:

• 01_hello_world.py
• 02_system_stats.py
• 05_animation.py
• 07_clock.py
• 09_systemd_service.py
• 10_sh1106_system_stats.py

Raspberry Pi setup

For wiring, I2C enablement, uv-based setup, and systemd instructions, see SETUP.md.

Development workflow

uv sync
uv run pytest
uv run ruff check .
uv run black --check .
uv run isort --check-only .
uv run mypy

Build and validate for PyPI

uv build
uvx twine check dist/*

Publish

uv publish

Current scope

• Raspberry Pi focused
• SSD1306 and SH1106 support implemented today
• Architecture intended to grow to more display types later