Lopaka Basics 01: tu primera pantalla

Termostatos, relojes inteligentes, impresoras 3D, estaciones meteorológicas: casi todos los dispositivos tienen una pantalla pequeña y alguien tuvo que dibujarla. Lopaka Basics es una serie de diez partes para quienes nunca han tocado un microcontrolador y nunca han abierto Lopaka.

Cada episodio sigue el mismo camino: dibújalo, consigue el código, míralo en una pantalla. En este primero verás qué ocurre dentro de un dispositivo cuando muestra una imagen, después diseñarás una pantalla pequeña en Lopaka y ejecutarás el código generado en un Arduino simulado.

Lo que vas a crear: una pantalla OLED de 128×64 con un marco, un «HELLO!» grande, un pie, una línea divisoria y un pequeño punto de estado. Lo que necesitas: un navegador. Una placa real es opcional; ejecutamos el código en un simulador en línea gratuito.

Qué hay dentro de un dispositivo

Una computadora diminuta que ejecuta un programa

La mayoría de los dispositivos pequeños tienen una placa con microcontrolador dentro: un Arduino UNO, un ESP32, una Raspberry Pi Pico o algo similar. Un microcontrolador es una computadora diminuta. A diferencia de tu computadora portátil, ejecuta un programa, tu firmware. En un sketch de Arduino, la función loop() de ese programa se repite mientras la placa tenga energía.

Tu programa dibuja todo lo que aparece en la pantalla. La placa no te da un escritorio, ventanas ni botones listos para empezar.

La pantalla es una cuadrícula de píxeles

La pantalla que usamos en los primeros episodios es una de las más comunes en electrónica de aficionados: un pequeño OLED monocromo, de 128 píxeles de ancho y 64 píxeles de alto. El módulo común es una placa de 0,96 pulgadas con el controlador SSD1306. Eso hace 8.192 píxeles y cada uno está encendido o apagado. Sin tonos de gris, todo en ella, incluido el texto, se ve nítido y en bloques.

La versión I2C del módulo se conecta a la placa con cuatro cables: dos para energía (GND y VCC) y dos para datos (SCL y SDA).

Cada píxel tiene una dirección

Para encender un píxel concreto, tu programa necesita decir cuál. Cada píxel tiene una dirección formada por dos números:

• x cuenta desde el borde izquierdo,
• y cuenta hacia abajo desde el borde superior.

Así, (0, 0) es la esquina superior izquierda. Dos detalles hacen tropezar a la mayoría de principiantes:

1. Y crece hacia abajo, lo contrario que en las matemáticas de la escuela. Un píxel en (40, 20) está 40 píxeles a la derecha y 20 píxeles hacia abajo desde la esquina.
2. El conteo empieza en cero. En una pantalla de 128×64 la última columna es 127 y la última fila es 63.

Una biblioteca de gráficos convierte comandos en píxeles

Tú no enciendes los 8.192 píxeles uno a uno. Tu programa llama a una biblioteca de gráficos y le habla en formas: dibuja un marco aquí, escribe este texto allá. La biblioteca averigua qué píxeles significa eso y los envía a la pantalla.

Para pantallas monocromo pequeñas, una de las bibliotecas más populares es U8g2. Dos líneas bastan para dibujar el inicio de nuestra pantalla:

u8g2.drawFrame(2, 2, 124, 60);      // a frame: x, y, width, height
u8g2.drawStr(28, 32, "HELLO!");     // text at x = 28, y = 32

La forma antigua: adivinar, compilar, subir, mirar

Escribes cada número de ese código a mano. Adivinas dónde debería empezar el texto, compilas el sketch, lo subes a la placa y miras la pantalla. ¿El texto está tres píxeles demasiado a la derecha? Cambias un número y vuelves a dar la vuelta: compilar, subir, mirar.

Cada ronda cuesta una compilación y una subida, a menudo decenas de segundos, y necesitas una placa conectada para ver algo. Incluso una pantalla sencilla como la nuestra puede llevar docenas de rondas antes de que todo se alinee.

Lopaka elimina ese bucle. Es un editor que se ejecuta en tu navegador. Dibujas la pantalla y Lopaka escribe el código para tu biblioteca de gráficos mientras dibujas.

Lopaka: inicio de sesión, proyectos y la galería

Abre lopaka.app e inicia sesión con correo electrónico, Google o GitHub. Lopaka guarda tus proyectos en la nube, así que puedes abrirlos desde cualquier computadora.

Paso 1: crea un proyecto nuevo

Haz clic en + New Project. La primera y más importante elección es la Platform, la biblioteca de gráficos que usará tu firmware. Esto decide qué tipo de código generará Lopaka, así que elige la biblioteca que vas a instalar en la placa.

Para cada biblioteca, Lopaka escribe el código de la forma que esa biblioteca espera.

Para un OLED pequeño en blanco y negro, elige U8g2. Su descripción lo llama «the default choice for monochrome OLED and LCD panels such as SSD1306, SH1106 and ST7565, where every pixel is simply on or off», y el código puede exportarse como Arduino C++ o ESP-IDF C.

Después completa el resto del diálogo:

• Title: «My First Screen».
• Screen Size: 128×64. Para U8g2 ya está seleccionado; la lista tiene docenas de otros tamaños. El interruptor Custom te permite escribir cualquier tamaño y Rounded es para pantallas redondas.

Haz clic en Save.

Paso 2: un recorrido rápido por el editor

Este es el editor. Todo lo que necesitas para este episodio cabe en una pantalla:

• Barra superior. El nombre del proyecto, seguido de dos insignias: la biblioteca (u8g2) y el tamaño de pantalla (128×64). El ícono de engranaje junto a ellas abre los ajustes del proyecto. A la derecha están Fork y Share.
• Herramientas de dibujo, sobre el lienzo: deshacer y rehacer, la herramienta de selección y después el pincel, el texto (Aa), el rectángulo, la elipse (el ícono de círculo), la línea, el triángulo y el polígono.
• El lienzo en el centro es tu pantalla a 128×64, con reglas en sus bordes. Cuando seleccionas una forma, las reglas marcan sus bordes exactos en píxeles.
• Capas a la izquierda. Cada forma que dibujas se convierte aquí en una capa, agrupada bajo su pantalla. Add Screen crea otra pantalla en el mismo proyecto; las pestañas Images y Animations de abajo guardan tus bitmaps y animaciones.
• Propiedades a la derecha, también llamado el inspector: la posición, el tamaño y el estilo exactos de lo que esté seleccionado.
• Código generado abajo. Se actualiza en vivo mientras dibujas. Junto a él están el interruptor Syntax (Arduino C++ o ESP-IDF C para U8g2) e interruptores que controlan qué va en el código.

Paso 3: dibuja la pantalla

Un marco y tu primera línea de código

Elige la herramienta rectangle y arrastra sobre el lienzo. Aparece un marco en la pantalla y, en el mismo momento, aparece una línea nueva en el código:

u8g2.drawFrame(2, 2, 124, 60);

Esos cuatro números son x, y, width y height: las mismas direcciones de píxel del principio del artículo. Salta el arrastre preciso y escribe los valores exactos en el inspector: X 2, Y 2, W 124, H 60. Las reglas siguen tus números y marcan los bordes de la forma en 2 y 126 en horizontal, 2 y 62 en vertical. Las reglas cuentan las líneas entre píxeles, así que el borde derecho en 126 significa que la última columna encendida es la 125.

Un marco que empieza en x = 2 y tiene 124 píxeles de ancho cubre las columnas 2 a 125. Eso deja dos columnas vacías a cada lado de la pantalla de 128 píxeles, y el mismo margen de dos píxeles arriba y abajo. A mano, harías esta aritmética mentalmente antes de cada compilación.

Las demás propiedades del rectángulo también cambian el código:

• R redondea las esquinas y la llamada se convierte en drawRFrame.
• Filled convierte el contorno en un bloque sólido, drawBox.
• Inverted (XOR) invierte los píxeles bajo la forma en lugar de encenderlos, lo que es útil para elementos de menú resaltados.

Texto y fuentes

Elige la herramienta text (Aa) y haz clic en el lienzo. Aparece una capa nueva con la palabra Text; selecciónala si todavía no está seleccionada y escribe HELLO! en el campo de texto del inspector. El primer texto de un proyecto usa la fuente predeterminada, 4x6, que es diminuta: cada carácter tiene cuatro píxeles de ancho. Cada texto que añades después empieza con la última fuente que elegiste.

Abre la lista Font. Lopaka ofrece 42 fuentes U8g2 integradas, desde microtexto de 4×6 píxeles hasta tipos de pantalla grandes. El primer elemento de la lista, Import font..., añade la tuya. Elige profont22.

Aparece una línea setFont en el código antes del texto, para que la biblioteca sepa con qué fuente dibujarlo:

u8g2.setFont(u8g2_font_profont22_tr);
u8g2.drawStr(56, 35, "HELLO!");

Alinea y mira cómo se mueven los números

Ahora coloca el texto con los botones de alineación de la parte superior del inspector: los dos botones centrales ponen el texto en el centro de la pantalla, horizontal y verticalmente. O arrástralo a cualquier sitio.

Mira el código mientras lo haces. Cada movimiento actualiza los números al instante, y centrar pone X en 28. Ves el resultado mientras lo cambias, sin compilación ni subida.

Mira las reglas en esta captura: marcan la caja alrededor de las letras de 25 a 39, y el código dice drawStr(28, 39, ...). En U8g2 la y de un texto es su línea base, la línea sobre la que se apoyan las letras, y las letras llenan las filas sobre ella. El texto que colocas a mano en y = 0 acaba sobre la pantalla, un error clásico de principiante. El inspector de Lopaka usa la misma línea base para Y, así que el número del campo va directo al código y el lienzo muestra dónde caerán las letras.

En el diseño terminado movemos «HELLO!» un poco más arriba, a y = 32, para dejar sitio a la línea y el pie de abajo.

Pie, línea y un punto de estado

Termina la pantalla con tres capas más:

• Un pie. Otra capa de texto, my first screen. Empieza en profont22, la última fuente que usaste, así que cámbiala a la más pequeña 6x10, céntrala horizontalmente y pon Y en 52: drawStr(19, 52, "my first screen"). Como este texto usa una fuente distinta, Lopaka añade otro setFont antes. Si dos textos seguidos usan la misma fuente, no repite la llamada.
• Una línea bajo «HELLO!»: drawLine(24, 39, 103, 39). Para las líneas, los cuatro números son el punto inicial y el punto final.
• Un punto pequeño en la esquina superior derecha, hecho con la herramienta de elipse, con Filled activado.

En el inspector el punto tiene X 117, Y 10, RX 2 y RY 2: la esquina superior izquierda de la caja que lo rodea y sus dos radios. La función de elipse de U8g2 toma el centro, así que el código dice drawFilledEllipse(119, 12, 2, 2). Cada biblioteca tiene convenciones como esta. Lopaka las convierte por ti y tú trabajas con lo que ves en el lienzo.

Ahora mira el panel de capas: rect 1, string 2, string 3, line 4, ellipse 5. Cada forma es una capa y cada capa es una línea de código, con su nombre como comentario encima.

Paso 4: consigue el código

Cuando la pantalla se vea bien, haz clic en Copy sobre el código. Obtienes una función lista para usar, con el nombre de la pantalla:

// [BEGIN lopaka generated]
void drawScreen_1(void) {
    u8g2.setFontMode(1);
    u8g2.setBitmapMode(1);
    // rect 1
    u8g2.drawFrame(2, 2, 124, 60);
    // string 2
    u8g2.setFont(u8g2_font_profont22_tr);
    u8g2.drawStr(28, 32, "HELLO!");
    // string 3
    u8g2.setFont(u8g2_font_6x10_tr);
    u8g2.drawStr(19, 52, "my first screen");
    // line 4
    u8g2.drawLine(24, 39, 103, 39);
    // ellipse 5
    u8g2.drawFilledEllipse(119, 12, 2, 2);
}
// [END lopaka generated]

Cuatro detalles en este código:

• Las fuentes ya están puestas. Cada texto recibe la fuente que elegiste en el editor, con el nombre de fuente U8g2 correcto. En u8g2_font_profont22_tr, la t significa fondo transparente y la r significa el conjunto de caracteres reducido: las letras latinas básicas, dígitos y puntuación, lo que mantiene la fuente pequeña en memoria.
• setFontMode(1) y setBitmapMode(1) hacen transparentes el texto y las imágenes, para que una letra dibujada sobre una línea no la borre con su fondo.
• Los marcadores BEGIN y END muestran qué parte de tu sketch vino de Lopaka. Cuando cambies el diseño, sustituye todo lo que hay entre ellos.
• Los interruptores junto al código controlan qué va en él: envolver el dibujo en una función, declarar las imágenes como PROGMEM, incluir fuentes y datos de imagen, comentarios con nombres de capa y más. Los valores predeterminados son correctos para este episodio.

Paso 5: ejecútalo

Dónde va la función: el búfer de fotogramas

Tu sketch tiene que llamar a la función copiada. Un sketch de Arduino mínimo para nuestra pantalla:

#include <U8g2lib.h>
#include <Wire.h>

// 128x64 SSD1306 OLED on I2C, full frame buffer
U8G2_SSD1306_128X64_NONAME_F_HW_I2C u8g2(U8G2_R0, U8X8_PIN_NONE);

// Paste the Lopaka code here

void setup() {
  u8g2.begin();
}

void loop() {
  u8g2.clearBuffer();
  drawScreen_1();
  u8g2.sendBuffer();
}

El nombre largo del objeto de pantalla se lee de izquierda a derecha: el controlador SSD1306, un panel 128X64, un módulo genérico (NONAME), un búfer de fotogramas completo (Full), conectado mediante I2C por HardWare. U8G2_R0 significa sin rotación y U8X8_PIN_NONE dice que el módulo no tiene un pin de reinicio cableado.

En loop(), llama a tu función entre clearBuffer() y sendBuffer():

1. clearBuffer() borra la imagen.
2. drawScreen_1() dibuja todo en memoria, no en la pantalla.
3. sendBuffer() envía la imagen terminada a la pantalla de una vez.

Esa imagen en memoria se llama búfer de fotogramas. La pantalla recibe solo fotogramas completos, así que nunca ves una pantalla a medio dibujar. El precio es la memoria: 128 × 64 píxeles a un bit cada uno son 1.024 bytes, la mitad de los 2 KB de RAM que tiene un Arduino UNO. Todo nuestro sketch ocupa 12.218 bytes de flash (37 %) y 1.578 bytes de RAM (77 %) en un UNO, y la mayor parte de esa RAM es el búfer de fotogramas. Para un sketch tan pequeño está bien. En un ESP32 el mismo sketch usa el 7 % de la RAM. Volveremos a la memoria, y a dibujar con menos, más adelante en la serie.

¿Todavía sin placa? Ejecútalo en un simulador

Puedes ver tu pantalla funcionando sin ningún hardware. Wokwi es un simulador en línea gratuito que compila y ejecuta código Arduino real:

1. Crea un proyecto Arduino UNO nuevo.
2. Añade una pantalla OLED SSD1306 y conecta cuatro cables: GND a GND, VCC a 5V, SCL a A5 y SDA a A4.
3. Añade la biblioteca U8g2 en la pestaña Library Manager.
4. Pega el sketch de arriba en sketch.ino, con el código de Lopaka en su sitio.
5. Pulsa Play.

La pantalla muestra lo que dibujaste, ejecutándose como código Arduino real. Pegamos el código de Lopaka sin cambiar un carácter y la pantalla simulada coincidió con el lienzo de Lopaka píxel a píxel.

En una placa real

Como es código real, el mismo sketch también se ejecuta en una placa real. Cablea la pantalla de la misma forma, instala U8g2 desde el Library Manager en el IDE de Arduino y sube el código. Dos cosas que comprobar en hardware real:

• El controlador. La mayoría de los módulos de 0,96 pulgadas usan el SSD1306. Muchos módulos de 1,3 pulgadas parecen iguales pero usan el SH1106; para esos, cambia SSD1306 por SH1106 en el constructor: U8G2_SH1106_128X64_NONAME_F_HW_I2C.
• La energía. La mayoría de estos módulos aceptan 3,3 V y 5 V, pero algunas placas básicas son solo de 3,3 V. Comprueba el anuncio de tu módulo.

Un episodio posterior de la serie recorre este paso a paso, incluido qué comprobar cuando la pantalla se queda en negro.

Resumen

El flujo de trabajo se mantiene igual para cada pantalla que hagas:

1. Elige tu biblioteca: la plataforma que eliges al crear un proyecto decide qué código obtienes. Para un OLED monocromo, empieza con U8g2.
2. Dibuja tu pantalla: cada forma es una capa, cada capa es una línea de código y el inspector muestra los números exactos.
3. Copia el código: llama a la función entre clearBuffer() y sendBuffer() y ejecútala en el simulador o en una placa real.

Próximo episodio: Text, Fonts & Icons. Creamos una miniestación meteorológica y descubrimos por qué cada fuente cuesta memoria. Lee el episodio 2 o míralo en YouTube.

¿Listo para probar? Abre Lopaka y dibuja tu primera pantalla.