Aprender

Dibuja en un OLED SSD1306 con un Arduino

Intermedio

O mira todas las lecciones.

  • 526componentes en el banco de trabajo
  • 46placas funcionando ahora
  • 1.00xtiempo real, en todas las placas
Arduino Uno: OLED SSD1306en vivo0.000 s 0.00x
Haz clic para abrirlo en el editor
El ejemplo oled: un SSD1306 de 128x64 en A4 y A5, dibujando texto, figuras y una pelota que rebota.

El OLED SSD1306 de 0.96 pulgadas es la pantallita de todo kit de electrónica: 128 por 64 píxeles, cuatro pines, blanco nítido sobre negro. El circuito de arriba muestra uno en un Arduino Uno, dibujando un título, algunas figuras, un contador y una pelota rebotando en una caja. Corre en un Uno simulado, y la pantalla se decodifica del tráfico I2C real en los dos cables, bit por bit, en lugar de dibujarse desde un atajo.

Ábrelo en el editor para cambiar el código de dibujo y ejecútalo de nuevo. La compilación tarda uno o dos segundos, en el navegador.

Lo que necesitas

  • Un Arduino Uno
  • Un módulo OLED SSD1306 de 128x64, versión I2C
  • Cuatro cables de conexión

Cableado

Componente y pinVa aNota
OLED SDAA4
OLED SCLA5
OLED VCC5 VLa mayoría de los módulos aceptan 3.3 V o 5 V
OLED GNDGND

El código de Adafruit

El sketch del tutorial de la SSD1306 de Adafruit compila aquí tal cual, en todas las placas excepto la ATtiny85. Los headers son propios de Mokxi, escritos sobre su controlador de pantalla, y conservan las llamadas que usan los tutoriales: clearDisplay(), display(), drawPixel(), líneas, rectángulos, rectángulos redondeados, círculos y triángulos, bitmaps, setTextSize(), setCursor(), print(), setRotation() e invertDisplay().

Hay dos diferencias con la biblioteca original que conviene conocer antes de empezar. La fuente es la propia de Mokxi, de 5 por 7, con mayúsculas, dígitos y signos de puntuación, así que las minúsculas se imprimen como mayúsculas. Y begin() deja el panel en blanco, mientras que la biblioteca original dibuja su logotipo.

Hola en una SSD1306, con las llamadas de la biblioteca de Adafruit
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

Adafruit_SSD1306 display(128, 64, &Wire, -1);

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) for (;;);
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println("Hello, world!");
  display.drawRect(0, 20, 40, 20, SSD1306_WHITE);
  display.display();
}

void loop() {}

Abrir este sketch en el editorSolo el código: el editor coloca la placa y los componentes que puede leer del sketch.

Por qué no aparece nada hasta display()

El panel no se puede leer. Así que un controlador que quiere cambiar un píxel tiene que recordar los otros 1023 bytes del cuadro, y guarda esa copia en la memoria de la propia placa. Cada llamada de dibujo escribe en esa copia; display() es lo que la envía al panel. Si olvidas display(), habrás dibujado una imagen perfecta en RAM que nadie verá jamás.

That copy is 1 KB, which is half the Uno’s entire 2 KB of SRAM. It is the real cost of a pixel display on an ATmega328P, and the reason big sketches with an OLED run out of memory. The built-in example also shows a way to go faster: it sends only the 8-column blocks of the screen that changed, so a moving ball is a few dozen bytes on the bus rather than a full kilobyte. Over the Uno’s software I2C a full 1 KB frame takes about a third of a second, which is the difference between two frames a second and the twenty-five this sketch manages.

Pruébalo en el editor

Abre el circuito en el editor y selecciona la pantalla. Cambia su dirección de 0x3C a 0x3D y ejecútalo de nuevo. El monitor serie dice que ningún OLED respondió, y el panel queda oscuro, que es la primera falla más común con estos módulos.

Luego reemplaza el ejemplo con el sketch de Adafruit de arriba, agrega unas cuantas llamadas de dibujo más, un círculo, un triángulo relleno, una línea de texto grande con setTextSize(2), y ejecútalo. Cada compilación tarda un momento en el navegador y luego el panel muestra exactamente lo que dibujó el código.

Para una imagen en movimiento, vuelve a dibujar dentro de loop() y llama a display() una vez por cuadro. La pelota que rebota del ejemplo muestra el truco de borrar solo lo que se movió.

Errores comunes

La dirección equivocada. La mayoría de los módulos responden en 0x3C; algunos vienen configurados en 0x3D. En la dirección incorrecta no aparece nada, y un sketch de escáner I2C te dice cuál es la correcta.

Enviar el comando de encendido de la pantalla sin la bomba de carga. El panel necesita unos 7.5 voltios, generados por una bomba dentro del chip que arranca apagada. Un controlador escrito a mano que envía el encendido y olvida arrancar la bomba obtiene una pantalla negra. El panel simulado modela la bomba, así que esta falla también ocurre aquí. La biblioteca lo maneja por ti.

Quedarte sin memoria en una Uno. Con el búfer de cuadro ocupando 1 KB, un sketch con arreglos grandes o cadenas largas en RAM puede fallar de maneras extrañas. Guarda las cadenas constantes en flash.

Esperar desplazamiento por hardware. Los comandos de desplazamiento del panel se aceptan y se ignoran en la pantalla simulada, así que un banner con desplazamiento se queda quieto aquí. Desplaza redibujando.

Abre este circuito en el editor. Arduino Uno: OLED SSD1306, conectado como se ejecuta al inicio de esta página. Cambia un componente o un valor y ejecútalo de nuevo.

Abrir el circuito

Preguntas

¿Cuál es la dirección I2C de un OLED SSD1306?

Normalmente 0x3C, a veces 0x3D, definida por un jumper o una resistencia en la parte de atrás del módulo. El simulado tiene la dirección como una propiedad.

¿Puedo usar un OLED SSD1306 con un ESP32?

Sí, con las mismas llamadas de biblioteca en los pines I2C propios del ESP32. Hay ejemplos integrados de ESP32 con un OLED, incluida esta misma demostración de texto y formas, y un juego de paletas en un ESP32-C3.

¿Por qué el texto de mi OLED sale todo en mayúsculas?

Porque la biblioteca simulada usa la fuente de 5 por 7 de Mokxi, que solo tiene mayúsculas, dígitos y signos de puntuación. En hardware real la fuente de Adafruit tiene minúsculas.

¿La pantalla del simulador es una imagen o el protocolo real?

El protocolo real. El componente es un dispositivo I2C decodificado a partir de los flancos de los pines, con el conjunto de comandos que envían las bibliotecas comunes y su propio 1 KB de memoria de pantalla.

Ármalo en la vida real

Abre el editor, cambia un valor y mira cómo cambia el número con él. Nada que instalar y sin necesidad de cuenta.