Cómo usar una pantalla OLED (SSD1306): texto, formas y gráficos con Arduino

Aunque apenas es más grande que la yema de un dedo, la pantalla OLED de 0,96 pulgadas muestra una imagen nítida de 128×64 píxeles y es una de las favoritas para proyectos con Arduino. A diferencia de las LCD de caracteres, no solo dibuja letras: también líneas, círculos, iconos, gráficos e incluso pequeños juegos. Es ideal para relojes inteligentes, estaciones meteorológicas, mandos y aparatos de medida portátiles. Casi todas estas pantallas usan el chip controlador SSD1306 y se conectan con solo dos cables de datos (I2C).

¿Qué es una OLED y en qué se diferencia de una LCD?

En una pantalla OLED (Organic Light Emitting Diode) cada píxel emite su propia luz; no hay retroiluminación. Por eso el negro es negro de verdad, el contraste es altísimo, se ve nítida desde cualquier ángulo y consume muy poco cuando la mayor parte de la imagen está oscura. Sus 128×64 píxeles permiten gráficos, iconos y dibujos que las LCD de caracteres no pueden mostrar.

Características técnicas

Conexión de la pantalla OLED

En los modelos bicolor, las 16 filas superiores se ven amarillas y el resto azul; esos colores no se pueden cambiar por software, así que queda bien diseñar la parte de arriba como una barra de título. Si no sabes la dirección de la pantalla, usa el escáner I2C de Cómo usar una pantalla LCD I2C.

Instalar las librerías

1. Abre el Gestor de librerías del Arduino IDE y busca Adafruit SSD1306.
2. Cuando durante la instalación pregunte por las dependencias, elige Install all para instalar también Adafruit GFX y Adafruit BusIO.
3. Si quieres, abre Archivo > Ejemplos > Adafruit SSD1306 > ssd1306_128x64_i2c y pruébalo con la dirección 0x3C.

Primer programa: escribir texto en la pantalla

1#include <Wire.h>
2#include <Adafruit_GFX.h>
3#include <Adafruit_SSD1306.h>
4
5Adafruit_SSD1306 display(128, 64, &Wire, -1);   // genişlik, yükseklik, I2C, reset pini yok / width, height, I2C, no reset pin
6
7void setup() {
8  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {   // I2C adresi / I2C address
9    for (;;);                                         // ekran bulunamadı / display not found
10  }
11  display.clearDisplay();
12  display.setTextColor(SSD1306_WHITE);
13  display.setTextSize(2);                   // 2 kat büyük / double size
14  display.setCursor(0, 0);
15  display.println(F("BlueGrays"));
16  display.setTextSize(1);
17  display.setCursor(0, 24);
18  display.println(F("OLED 128x64 hazir!"));
19  display.display();                        // tamponu ekrana gönder / push the buffer to the screen
20}
21
22void loop() {
23}

Dibujar formas: funciones de Adafruit GFX

La esquina superior izquierda de la pantalla es (0, 0) y la inferior derecha, (127, 63). Como color se usa SSD1306_WHITE (encendido), SSD1306_BLACK (apagado) o SSD1306_INVERSE (invertir).

Mostrar un valor de sensor: un termómetro en directo

El punto fuerte de la OLED es mostrar medidas con números grandes y gráficos. El código siguiente escribe en letra grande la temperatura leída de un DHT11 y muestra debajo la humedad con una barra. Para conectar el sensor, mira Sensor de temperatura y humedad DHT11.

1#include <Wire.h>
2#include <Adafruit_GFX.h>
3#include <Adafruit_SSD1306.h>
4#include <DHT.h>
5
6Adafruit_SSD1306 display(128, 64, &Wire, -1);
7DHT dht(2, DHT11);
8
9void setup() {
10  display.begin(SSD1306_SWITCHCAPVCC, 0x3C);
11  display.setTextColor(SSD1306_WHITE);
12  dht.begin();
13}
14
15void loop() {
16  float t = dht.readTemperature();
17  float h = dht.readHumidity();
18  display.clearDisplay();
19  display.setTextSize(1);
20  display.setCursor(0, 0);
21  display.print(F("Sicaklik / Temp"));
22  display.setTextSize(3);
23  display.setCursor(0, 16);
24  display.print(t, 1);
25  display.print(F("C"));
26  display.drawRect(0, 52, 128, 10, SSD1306_WHITE);                    // nem çubuğu çerçevesi / humidity bar frame
27  display.fillRect(2, 54, (int)(h / 100.0 * 124), 6, SSD1306_WHITE);  // nem oranı kadar dolu / filled by humidity
28  display.display();
29  delay(2000);
30}

Dibujar tu propio icono: mapas de bits

Para mostrar un logo o un icono conviertes la imagen en un array de bytes: cada bit es un píxel. Herramientas de conversión como image2cpp transforman directamente una imagen en blanco y negro en un array para Arduino. Los iconos pequeños también se pueden escribir a mano; el array de 8×8 siguiente dibuja un corazón:

1const unsigned char PROGMEM heart[] = {
2  0b01100110,
3  0b11111111,
4  0b11111111,
5  0b11111111,
6  0b01111110,
7  0b00111100,
8  0b00011000,
9  0b00000000
10};
11
12// setup() ya da loop() içinde / inside setup() or loop()
13display.drawBitmap(60, 28, heart, 8, 8, SSD1306_WHITE);
14display.display();

OLED con el ESP32 y la Raspberry Pi Pico

En el ESP32 funcionan el mismo código de Arduino y las mismas librerías; los pines I2C son GPIO 21 (SDA) y 22 (SCL). Como el ESP32 tiene mucha memoria, las animaciones y los gráficos que se actualizan rápido van mucho más fluidos. En la Pico con MicroPython, basta con copiar en la Pico el archivo controlador ssd1306.py (de micropython-lib):

1from machine import Pin, I2C
2import ssd1306                                 # ssd1306.py Pico'da olmalı / must be on the Pico
3
4i2c = I2C(0, sda=Pin(4), scl=Pin(5), freq=400000)
5oled = ssd1306.SSD1306_I2C(128, 64, i2c)       # adres varsayılan 0x3C / default address 0x3C
6
7oled.fill(0)                                   # ekranı temizle / clear the screen
8oled.text("BlueGrays", 0, 0)
9oled.text("Pico + OLED", 0, 16)
10oled.rect(0, 40, 128, 20, 1)                   # çerçeve / frame
11oled.fill_rect(2, 42, 80, 16, 1)               # dolu çubuk / filled bar
12oled.show()                                    # ekrana gönder / push to the screen

Vida de la pantalla y marcas fantasma (burn-in)

Los píxeles OLED pierden brillo con el uso. Si la misma imagen se queda meses en pantalla sin cambiar, puede formarse una sombra tenue en los píxeles que más se encienden. Para evitarlo, apaga la pantalla cuando no se use (display.ssd1306_command(SSD1306_DISPLAYOFF)), baja el brillo (display.dim(true)), desplaza de vez en cuando el contenido fijo unos píxeles o enciende la pantalla solo cuando haya alguien cerca con un sensor PIR.

Ideas de proyectos con pantalla OLED

• Miniestación meteorológica: muestra temperatura, humedad y presión con iconos.
• Juegos de bolsillo: juega al Pong o al dinosaurio T-Rex con botones o con un joystick.
• Pantalla del tiempo: muestra con iconos el tiempo que obtienes de internet con un ESP32.
• Indicador de aparcamiento: muestra como número y barra la distancia medida con un HC-SR04.
• Trazador de señales: dibuja los valores de analogRead como un gráfico que se desplaza.
• Reloj de escritorio: reúne en una sola pantalla la hora de internet, la fecha y el tiempo del día.

Errores comunes y cómo solucionarlos

• La pantalla sigue en blanco: no se llama a display.display(), la dirección es incorrecta (0x3D en lugar de 0x3C) o SDA y SCL están invertidos.
• «SSD1306 allocation failed»: el Uno se queda sin RAM; el búfer de una pantalla de 128×64 ocupa 1 KB. Escribe los textos con F(), pasa los arrays grandes a PROGMEM o usa la librería U8g2, que ahorra RAM.
• La imagen sale rota o a medias: una pantalla de 128×32 se ha declarado como 128×64 (o al revés); pon el tamaño correcto en el código.
• La imagen sale boca abajo: gírala 180 grados con display.setRotation(2).
• Conectar VCC y GND al revés: estropea la pantalla para siempre; lee las etiquetas de los pines antes de conectar.
• Bloqueos aleatorios: cables I2C largos y flojos; usa cables cortos y, si hace falta, baja la velocidad del I2C.

Una pantalla OLED es la forma más barata de dar a tu proyecto un aspecto profesional. Si solo vas a mostrar números, un display de 7 segmentos es buena opción, y para texto que deba leerse al sol, una LCD I2C. En la app BlueGrays encontrarás juegos de Pong y T-Rex en OLED, una pantalla del tiempo con ESP32, un sensor de aparcamiento y un registrador de temperatura, con esquemas y código.