Subiste el sketch, el monitor serie imprime bien… y la pantallita sigue negra. El display OLED SSD1306 es el panel de 0,96" (y primos) que más se ve en kits: poco cableado por I2C, buen contraste y librerías maduras. También es campeón de falsos “está quemado”: dirección I2C mal, 3,3 V vs 5 V, pines SDA/SCL del micro equivocados o controlador que no es SSD1306 aunque el anuncio lo diga.
Esta guía te lleva del cableado a los primeros textos y menús simples, con una tabla de problemas frecuentes y hábitos que evitan tres horas de pelea. Combina bien con protoboard sin errores y con la elección de placa en Arduino Nano vs Uno o ESP32 vs Arduino.
1. Qué es el SSD1306 y qué módulo estás comprando
El SSD1306 es el controlador de la matriz OLED. El módulo de kit añade:
- Panel 128×64 o 128×32 (lo más común: 128×64 de 0,96").
- Regulador y/o nivelado según diseño.
- Resistencias de pull-up en I2C (casi siempre).
- Pines VCC, GND, SCL, SDA (a veces también reset).
Hay módulos SPI del mismo controlador; esta guía se centra en el I2C de 4 hilos, el de mayor stock en Colombia y LATAM.
Idea clave: el anuncio diga “SSD1306” no garantiza el chip. Hay SH1106 y otros que se parecen. Si la librería “oficial” dibuja corrido o con basura en el borde, prueba el driver SH1106 o un constructor distinto en U8g2/Adafruit.
2. Pinout típico I2C
| Pin del módulo | A | Qué conectar |
|---|---|---|
| VCC | Alimentación | 3,3 V o 5 V según serigrafía del módulo |
| GND | Tierra | GND del micro |
| SCL | Reloj I2C | SCL de la placa (A5 en Uno/Nano 328P; pines etiquetados en ESP32) |
| SDA | Datos I2C | SDA (A4 en Uno/Nano 328P) |
Algunos módulos traen jumper de dirección (0x3C / 0x3D). El valor por defecto más visto en hobby es 0x3C, pero no es ley: un escáner I2C termina la discusión.
3. Voltaje: 3,3 V, 5 V y módulos “acepta ambos”
| Situación | Recomendación |
|---|---|
| Arduino Uno/Nano 5 V + módulo “5 V” | Directo, suele ir bien |
| ESP32 3,3 V + módulo solo 5 V de lógica | Verifica; muchos OLED de kit toleran 3,3 V en I2C y VCC 3.3–5 |
| VCC a 5 V y micro a 3,3 V | A menudo funciona por pull-ups del módulo; no todos los diseños son ideales |
| Duda | Alimenta VCC a 3,3 V si el módulo lo permite y el brillo alcanza |
No alimentes un módulo solo-3,3 V a 5 V “porque el Arduino es de 5”. Lee la serigrafía. Si el panel se calienta raro o el regulador del módulo huele, apaga y revisa.
4. Cableado en protoboard sin drama
- Nano o Uno firmes en el board.
- GND común primero.
- VCC al riel correcto (etiqueta 5 V o 3V3).
- SDA y SCL con jumpers cortos.
- No cruces los rieles partidos sin puente: el módulo al fondo del board puede quedarse sin alimentación.
Verifica con multímetro que VCC del módulo tiene tensión antes de culpar a la librería: multímetro.
5. Librerías: dos caminos populares
Adafruit SSD1306 + Adafruit GFX
- API clara para texto y formas.
- Muy documentada en ejemplos del IDE.
- Ideal para primeros textos y contadores.
U8g2
- Muchas fuentes y controladores (incluye SH1106 con facilidad).
- Excelente si tu panel “no es exactamente” el que creías.
- Curva un poco más larga al inicio.
Las dos se instalan desde el gestor de librerías del IDE (Programa → Incluir librería → Administrar bibliotecas). El código de ambas está publicado: Adafruit SSD1306 y U8g2. Lo que no conviene es mezclar el ejemplo de una con los include de la otra.
6. Tu primer sketch: escribir "Hola" en la pantalla
Este es el programa completo. Cárgalo tal cual con la librería de Adafruit instalada:
Dos detalles que explican la mayoría de los fracasos:
display()es obligatorio. Todo lo que dibujas se acumula en memoria y no aparece hasta que llamas a esa función. Sin ella, el programa "corre bien" y la pantalla sigue negra.- Si
beginfalla, el programa se detiene ahí a propósito. No es un error de C++: es cableado o dirección equivocada. Para eso está la sección siguiente.
7. Encontrar la dirección real con el escáner I2C
Cada dispositivo del bus I2C tiene una dirección, y la pantalla no responde si le hablas a la equivocada. Este programa recorre todas las direcciones posibles y te dice cuáles contestan. Es el primer sketch que hay que cargar cuando algo del bus no aparece:
Abre el Monitor Serie a 9600, anota la dirección que aparezca y ponla en el #define DIRECCION del sketch anterior. La documentación de la librería Wire, que es la que maneja el bus, está en la referencia oficial de Arduino.
Si el escáner no ve nada, revisa en este orden:
- Cable SDA/SCL intercambiado.
- Sin GND común.
- Sin alimentación.
- Pines I2C incorrectos en ESP32 (¿inicializaste
Wire.begin(SDA, SCL)en los GPIO que cableaste?). - Módulo muerto o mal soldado.
Si ve un reloj RTC u otro sensor pero no el OLED, el problema es del display o de su cableado, no del bus entero.
8. Tabla de síntomas → causas
| Síntoma | Causas probables |
|---|---|
| Negra total | Sin energía, begin fallido, contraste/dirección, cableado |
| Se ve basura / imagen corrida | Driver SH1106 vs SSD1306, resolución mal declarada |
| Parpadea o a veces funciona | Contacto flojo en protoboard, USB débil |
| Texto mirando al revés | Rotación de montaje; usa API de rotación si existe |
| Se ve y se apaga al sumar WiFi (ESP32) | Caída de alimentación, picos de corriente |
| Caracteres cortados | Buffer no enviado, fuente grande fuera de 128×64 |
9. Primeros textos que valen la pena
En lugar del “Hello World” eterno, muestra datos útiles:
- Estado de un sensor (temperatura, distancia).
- Menú de dos líneas (modo A / modo B).
- Contador de tiempo o versión de firmware (
v1.2). - Icono simple de batería si mides un divisor.
Hábitos de UI en 128×64:
- Fuentes pequeñas para datos densos.
- Una idea por pantalla en el primer proyecto.
- No redibujes a 1000 FPS: actualiza cuando el dato cambia o cada 200–500 ms.
- Limpia el buffer antes de dibujar un frame nuevo si no haces redraw parcial consciente.
Proyectos hermanos que combinan bien: DHT22, estación AHT20/BMP280, sensor ultrasónico.
10. ESP32 y pines I2C
En ESP32 los pines I2C son asignables en software. Si copias un tutorial de “SDA=21, SCL=22” pero cableaste otros GPIO, no funciona. Patrón:
Respeta pines de strapping y evita los que te compliquen el boot. Alimentación: el OLED no es un motor, pero un USB flojo + WiFi + pantalla puede sumar resets. Mide 3,3 V bajo carga.
En el Nano/Uno clásicos los pines I2C están fijos (A4/A5). Esa rigidez es una ventaja didáctica: menos variables. En ESP32 ganas flexibilidad y pierdes la “copia exacta del tutorial del 2018”. Anota en un comentario del sketch los GPIO reales del cableado; el yo del futuro (y el compañero de lab) lo agradece.
11. SPI vs I2C: ¿cuándo cambiar?
I2C gana en simplicidad (4 hilos). SPI gana en velocidad de refresco y a veces en proyectos con muchos dispositivos o animaciones. Si solo muestras texto de sensor cada segundo, I2C sobra. Si haces juegos o gráficos densos, evalúa SPI o un controlador más capaz.
También existen OLED de otras diagonales y controladores: no asumas que el mismo constructor Adafruit aplica sin leer el ejemplo del vendedor.
12. Buenas prácticas de montaje final
- Fija el módulo: el cable Dupont suelto es la falla intermitente número uno.
- Evita tensionar los 4 pines del header del OLED.
- Si va en caja, deja ventana o marco; el acrílico rayado mata el contraste percibido.
- Apaga el display en deep sleep si el nodo es a batería (API de sleep de la lib o corta VCC con MOSFET si diseñas hardware).
- Etiqueta en el firmware la dirección I2C usada: el yo del futuro lo agradece.
Para nodos a batería con carga de celda: TP4056.
Qué mostrar en la primera UI útil
En 128×64 no cabe un dashboard de avión. Prioriza:
- Una magnitud principal grande (temperatura, cm, estado ON/OFF).
- Una línea de contexto (unidad, modo, versión).
- Un indicador de salud (WiFi ok, batería baja, error de sensor).
Actualiza el buffer solo cuando el valor cambia o cada medio segundo: gastar ciclos redibujando el mismo texto no mejora la UX y complica el resto del loop. Si combinas OLED con un sensor DHT22, deja tiempo de lectura del sensor y no bloquees el bus I2C con animaciones innecesarias.
13. Checklist de compra del módulo OLED
- Resolución real (128×64 vs 128×32).
- Interfaz I2C (4 pines) o SPI (más pines).
- Color: blanco, azul, amarillo/azul dual (solo estética).
- VCC 3.3–5 V según tu micro.
- Pines soldados o hay que soldar header.
- Vendedor que no confunda SSD1306 con “pantalla TFT genérica”.
Stock y criterios de tienda: comprar componentes online, kit Arduino.
14. Resumen
El OLED SSD1306 por I2C es la forma más rápida de pasar de Serial Monitor a una UI embutida. El 90 % de las pantallas “muertas” son cableado, dirección o driver equivocado — no silicio quemado. Escanea el bus, declara la resolución real, alimenta con criterio 3.3/5 V y actualiza el buffer con calma. Cuando eso es aburrido de lo repetible, el panel deja de ser misterio y se vuelve un instrumento más del banco.
Preguntas frecuentes
¿Por qué el ejemplo se queda en “SSD1306 allocation failed” o no pasa del begin?
Memoria insuficiente en micros muy justos es raro en Uno para un solo OLED; más común es fallo de comunicación interpretado raro, o conflicto de librerías. Verifica I2C y prueba el scanner.
¿Puedo poner dos OLED en el mismo bus?
Sí, si tienen direcciones distintas (0x3C y 0x3D) o usas un multiplexor I2C. Dos módulos soldados a la misma dirección chocan.
¿El OLED se quema si muestro la misma imagen días?
Hay riesgo de burn-in en OLEDs encendidos estáticos mucho tiempo a alto contraste. Para un reloj de pared 24/7, rota contenido o atenúa. Para un medidor que enciendes al usar, relájate.
¿Funciona con Raspberry Pi Pico?
Sí, con las librerías del ecosistema que uses (Arduino core para Pico, MicroPython, etc.). Los pines I2C cambian: no copies el cableado del Nano.
¿Necesito resistencias pull-up externas?
La mayoría de módulos ya las traen. Sumar pull-ups extra fuertes en buses cortos de un solo dispositivo suele ser innecesario; en buses largos con varios esclavos, a veces se ajustan.
¿Qué resolución pongo en el código si mi pantalla es 128×32?
La real. Si declaras 128×64 en un panel 128×32, veras basura o contenido cortado. Confirma en la compra y en la serigrafía cuando exista.