Raspberry Pi y el Display OLED SH1106 o SSD1306

Las pantallas OLED pequeñas de 128×64 píxeles se conectan a la Raspberry con cuatro cables y se manejan con la biblioteca luma.oled. Lo que no ha cambiado es el montaje; lo que sí, la forma de instalar la biblioteca.

También te puede interesar

Cómo se ha comprobado esta página. No tenemos el montaje físico en el banco de pruebas, así que el dibujo se ha generado con el dispositivo simulado que trae la propia biblioteca, que produce exactamente la imagen que se enviaría a la pantalla. Las salidas que aparecen son de esas ejecuciones.
Una pantalla OLED pequeña conectada a la Raspberry Pi mostrando texto
La pantalla conectada a la Raspberry, de la versión anterior de esta página.

Conexión

PantallaRaspberry Pi
VCC3,3 V (pin 1)
GNDGND (pin 6)
SDAGPIO 2, SDA (pin 3)
SCLGPIO 3, SCL (pin 5)

Antes, activa I2C: sudo raspi-config, Interface Options, I2C. Para comprobar que la pantalla responde, i2cdetect -y 1 debería mostrar su dirección, casi siempre 3c.

Instalar

En Raspberry Pi OS Bookworm y posteriores, pip install fuera de un entorno virtual da el error externally-managed-environment. Es a propósito: protege el Python del sistema. Hay dos caminos, que son los que recomienda la documentación oficial: instalar con apt el paquete python3-… si existe, o crear un entorno virtual e instalar ahí con pip. La versión anterior de esta página usaba sudo pip3 install, que en las versiones actuales ya no funciona y en las antiguas podía estropear el sistema.
python3 -m venv ~/oled
~/oled/bin/pip install luma.oled

Escribir en la pantalla

from luma.core.interface.serial import i2c
from luma.core.render import canvas
from luma.oled.device import sh1106          # o ssd1306, según tu pantalla
from PIL import ImageFont

serial = i2c(port=1, address=0x3C)
device = sh1106(serial, width=128, height=64)

with canvas(device) as draw:
    draw.rectangle(device.bounding_box, outline="white", fill="black")
    draw.text((10, 10), "Hola Mundo!", fill="white")
    draw.text((10, 24), "decodigo.com", fill="white")
    fuente = ImageFont.truetype("DejaVuSans.ttf", 13)
    draw.text((10, 40), "Año: 2026", font=fuente, fill="white")
Simulación de una pantalla OLED de 128 por 64 píxeles con un marco y los textos «Hola Mundo!», «decodigo.com» y «Año: 2026»
Lo que dibuja ese código, generado con el dispositivo simulado de luma.core y ampliado cuatro veces.
salidatamaño: (0, 0, 127, 63)
píxeles encendidos: 862 de 8192

Todo lo que se dibuja dentro del with canvas(device) se envía a la pantalla al salir del bloque. draw es un objeto de dibujo de Pillow, así que valen sus métodos: text, rectangle, line, ellipse. La tercera línea usa una fuente TrueType, que es la forma segura de que salgan bien la eñe y las tildes.

¿SH1106 o SSD1306?

Por fuera son iguales. Si usas el controlador equivocado, la pantalla no se queda en negro: muestra la imagen desplazada dos columnas o con basura en un borde. Es la pista para cambiar sh1106 por ssd1306, o al revés. La versión anterior de esta página dejaba el programa esperando 20 segundos con sleep(20): era para que diera tiempo a ver la pantalla antes de que el programa terminara y se apagara.

Revisada en octubre de 2026 para Raspberry Pi OS actual. Las salidas están copiadas de ejecuciones reales; lo que no se pudo ejecutar sin el hardware se indica en el propio texto.