Matriz LED NeoPixel Arduino: guía de paneles WS2812B 8x8 y 16x16

Una matriz NeoPixel es una de las pantallas más vistosas que puedes montar con Arduino: se forma con 8x8 (64 LED) o 16x16 (256 LED) LED RGB direccionables WS2812B dispuestos en un panel, y con un solo cable de datos controlas el color de cada píxel por separado. Es ideal para textos en desplazamiento, iconos, pequeños juegos, analizadores de espectro de audio y animaciones decorativas. En esta guía aprenderás paso a paso la disposición en zigzag del panel, la función que convierte coordenadas x-y en un número de LED, el texto en desplazamiento y las animaciones.

Trabajar con una matriz exige algo más de cuidado que con una sola tira NeoPixel. 256 LED a brillo máximo pueden consumir más de 15 amperios, los 2 KB de RAM del Arduino Uno se llenan enseguida con paneles grandes, y la salida de 3,3 V del ESP32 y de la Pico puede dar problemas en algunos paneles. Por eso, además del código, veremos el cálculo de corriente, la limitación de brillo y la planificación de memoria. Si aún no conoces lo básico del WS2812B, échale un vistazo antes a LED NeoPixel WS2812B.

¿Qué es una matriz LED NeoPixel y cómo funciona?

Dentro de cada LED WS2812B, junto a los chips rojo, verde y azul, hay un pequeño circuito controlador integrado. El microcontrolador envía por la línea de datos a 800 kHz la información de color de 24 bits por LED; el orden de esos bits es verde, rojo, azul (GRB). El primer LED se queda con los primeros 24 bits y pasa el resto al siguiente por la salida DOUT, y así sucesivamente. En un panel matricial ocurre lo mismo: los 64 o 256 LED son en realidad una tira larga doblada en forma cuadrada. Enviar datos a un LED tarda unos 30 microsegundos, así que actualizar un panel de 256 LED lleva unos 7,7 ms; eso permite animaciones fluidas de más de 100 fotogramas por segundo.

Disposición de píxeles en zigzag y función de coordenadas XY

En el código quieres pensar en un píxel como (x, y), pero los LED se direccionan con un único número de orden que empieza en 0. En casi todos los paneles flexibles y en los modelos de 16x16, los LED se colocan en zigzag (serpentina): la primera fila va de izquierda a derecha, la segunda vuelve de derecha a izquierda, la tercera otra vez de izquierda a derecha. Esta disposición facilita la fabricación, porque el final de cada fila se conecta al principio de la siguiente por el camino más corto. En la tabla siguiente ves los números de LED de las cuatro primeras filas de un panel 8x8 en zigzag:

La fórmula sale sola: en las filas pares índice = y × W + x, y en las impares índice = y × W + (W − 1 − x), donde W es el ancho del panel. Por ejemplo, en un panel 8x8 el punto (2, 1) es el LED número 1 × 8 + (7 − 2) = 13. Ojo: en algunas placas 8x8 con PCB rígido todas las filas avanzan en el mismo sentido (disposición lineal o progresiva); en ese caso la fórmula es simplemente y × W + x. En otros paneles los LED serpentean por columnas en lugar de filas, es decir, hay que intercambiar x e y. La forma más segura de saber qué tipo de panel tienes es ejecutar un código de prueba que encienda los LED uno a uno y observar cómo avanza la luz.

Conexión de la matriz NeoPixel: Arduino Uno, ESP32 y Pico

Para un circuito robusto añade tres piezas pequeñas: una resistencia de 300–500 Ω en serie con la línea de datos (protege la entrada del primer LED de picos de tensión), un condensador electrolítico de unos 1000 µF entre 5V y GND del panel (amortigua el pico de corriente al encender la fuente) y, en placas de 3,3 V si hace falta, un convertidor de nivel. Con alimentación de 5 V, el WS2812B quiere ver en su entrada de datos al menos unos 3,5 V (el 70 % de la tensión de alimentación); la salida de 3,3 V del ESP32 y la Pico funciona en la mayoría de paneles, aunque queda por debajo de ese límite. Si ves parpadeos o colores aleatorios, usa un buffer como el 74AHCT125; tienes los detalles en el artículo sobre el convertidor de nivel lógico.

Primer programa de matriz paso a paso (Arduino Uno)

1. En el IDE de Arduino abre el Gestor de bibliotecas e instala la biblioteca Adafruit NeoPixel.
2. Conecta el panel según la tabla: DIN a D6 con una resistencia de 330 Ω, GND al GND del Arduino y 5V a la fuente.
3. Ajusta W y H en el código según el tamaño de tu panel; para un panel 16x16 pon ambos a 16.
4. En la primera prueba mantén el brillo bajo; setBrightness(30) reduce la corriente de un panel 8x8 a un nivel que el USB puede soportar.
5. Sube el código; deberías ver un arcoíris desplazándose en diagonal. Si los colores aparecen cortados fila a fila, la disposición de tu panel es distinta: corrige la función xyIndex en consecuencia.

1#include <Adafruit_NeoPixel.h>
2
3#define PIN_DATA 6                 // DIN pini (330 ohm ile) / DIN pin (via 330 ohm)
4#define W 8                        // panel genişliği / panel width
5#define H 8                        // panel yüksekliği / panel height
6#define NUM_LEDS (W * H)
7
8Adafruit_NeoPixel strip(NUM_LEDS, PIN_DATA, NEO_GRB + NEO_KHZ800);
9
10// (x, y) koordinatını LED numarasına çevirir (zikzak) / converts (x, y) to LED index (serpentine)
11uint16_t xyIndex(uint8_t x, uint8_t y) {
12  if (y & 1) {
13    return y * W + (W - 1 - x);    // tek satırlar sağdan sola / odd rows run right to left
14  }
15  return y * W + x;                // çift satırlar soldan sağa / even rows run left to right
16}
17
18void setup() {
19  strip.begin();
20  strip.setBrightness(30);         // 0-255, düşük tut / keep it low
21  strip.clear();
22  strip.show();
23}
24
25void loop() {
26  static uint16_t hueBase = 0;
27  for (uint8_t y = 0; y < H; y++) {
28    for (uint8_t x = 0; x < W; x++) {
29      uint16_t hue = hueBase + (x + y) * 4096U;   // çapraz gökkuşağı / diagonal rainbow
30      strip.setPixelColor(xyIndex(x, y), strip.gamma32(strip.ColorHSV(hue)));
31    }
32  }
33  strip.show();                    // tamponu panele gönder / push the buffer to the panel
34  hueBase += 256;                  // renkleri kaydır / shift the colors
35  delay(20);
36}

El corazón del código es la función xyIndex(): invierte x en las filas impares y así oculta el zigzag, de modo que en el resto del programa solo piensas en coordenadas. ColorHSV() convierte a RGB un valor de tono entre 0 y 65535 de la rueda de color; como el tono se desplaza al aumentar la suma x + y, se forman bandas de color diagonales. gamma32() corrige según la percepción del brillo del ojo y hace que las transiciones de color parezcan más naturales. Por último, mientras no llames a show() ningún cambio llega al panel; escribir todos los píxeles en memoria y enviarlos de una vez es el secreto de una imagen fluida.

Texto en desplazamiento con Adafruit NeoMatrix

Para dibujar letras e iconos no hace falta ir píxel a píxel. La biblioteca Adafruit NeoMatrix convierte el panel NeoPixel en una pantalla compatible con Adafruit GFX; así, funciones como print(), drawLine(), fillRect() y drawBitmap(), que usas en las pantallas OLED, también funcionan en la matriz. Al instalar Adafruit NeoMatrix desde el Gestor de bibliotecas, instala también las dependencias Adafruit GFX y Adafruit NeoPixel. Las banderas del constructor describen la disposición física del panel: NEO_MATRIX_TOP + NEO_MATRIX_LEFT indica que el primer LED está en la esquina superior izquierda, NEO_MATRIX_ROWS que los LED se ordenan a lo largo de las filas y NEO_MATRIX_ZIGZAG que las filas van en zigzag; en una placa con disposición lineal basta con escribir NEO_MATRIX_PROGRESSIVE en lugar de ZIGZAG. La fuente predeterminada de 5×7 encaja justo en un panel de 8 filas y cada carácter, con su espacio, ocupa 6 píxeles de ancho. Un texto de nueve letras mide 54 píxeles; la constante textWidth lo calcula automáticamente, y cuando x baja de ese valor el texto vuelve a entrar por la derecha y cambia de color.

1#include <Adafruit_GFX.h>
2#include <Adafruit_NeoMatrix.h>
3#include <Adafruit_NeoPixel.h>
4
5#define PIN_DATA 6
6
7// 8x8 panel, ilk LED sol üstte, zikzak satırlar / 8x8 panel, first LED top-left, zigzag rows
8Adafruit_NeoMatrix matrix(8, 8, PIN_DATA,
9  NEO_MATRIX_TOP + NEO_MATRIX_LEFT + NEO_MATRIX_ROWS + NEO_MATRIX_ZIGZAG,
10  NEO_GRB + NEO_KHZ800);
11
12const char text[] = "BlueGrays";
13const int textWidth = (sizeof(text) - 1) * 6;   // karakter başına 6 piksel / 6 pixels per character
14int x = 8;                                      // yazı sağ kenardan başlar / text starts at the right edge
15uint8_t colorStep = 0;
16
17void setup() {
18  matrix.begin();
19  matrix.setTextWrap(false);       // satır kaydırma kapalı / no line wrap
20  matrix.setBrightness(40);
21  matrix.setTextColor(matrix.Color(255, 0, 0));
22}
23
24void loop() {
25  matrix.fillScreen(0);
26  matrix.setCursor(x, 0);
27  matrix.print(text);
28  if (--x < -textWidth) {          // yazı panelden tamamen çıktı / text fully left the panel
29    x = matrix.width();
30    colorStep = (colorStep + 1) % 3;
31    if (colorStep == 0) matrix.setTextColor(matrix.Color(255, 0, 0));
32    if (colorStep == 1) matrix.setTextColor(matrix.Color(0, 255, 0));
33    if (colorStep == 2) matrix.setTextColor(matrix.Color(0, 0, 255));
34  }
35  matrix.show();
36  delay(80);                       // kayma hızı / scroll speed
37}

El límite de memoria del Arduino Uno

El procesador ATmega328P del Arduino Uno tiene solo 2048 bytes de RAM y cada LED necesita un búfer de color de 3 bytes. Un panel 8x8 cabe holgadamente con 192 bytes; uno de 16x16, con 768 bytes, ocupa él solo más de un tercio de la RAM. Lo traicionero es que Adafruit NeoPixel reserva este búfer mientras el programa se ejecuta, por lo que no aparece en el porcentaje de variables globales que se muestra al compilar. Aunque la compilación indique un 70 % de uso, al añadir el búfer del panel la memoria puede agotarse; la placa se cuelga o ves colores sin sentido. Además, en las placas AVR las interrupciones se desactivan mientras se ejecuta show(); con 256 LED eso son unos 7,7 ms, durante los cuales millis() puede atrasarse y se pueden perder datos que lleguen por Serial. Para paneles grandes, un Arduino Mega con 8 KB de RAM o un ESP32 con cientos de kilobytes son opciones mucho más cómodas.

Consumo de corriente y limitación de brillo

Cada canal de color de un WS2812B consume unos 20 mA a brillo máximo; cuando se encienden los tres a la vez, es decir, en blanco, son 60 mA por LED. Para un cálculo aproximado puedes usar la fórmula I ≈ número de LED × 60 mA × (brillo / 255). Un panel de 16x16 en blanco total consume 256 × 60 = 15.360 mA, es decir, más de 15 A, lo que exige a las fuentes de alimentación y a las finas pistas de cobre del panel. La buena noticia es que las matrices son muy luminosas: en interiores, un brillo de entre 20 y 50 sobre 255 ya se ve de sobra. En animaciones reales no todos los LED están en blanco a la vez, así que la corriente media es bastante menor que la calculada, pero conviene elegir la fuente para el peor caso o limitarlo por software.

En un panel de 16x16, si alimentas por un solo extremo, la tensión cae en los LED de la esquina lejana y el blanco se ve amarillento o rojizo. Para evitarlo, alimenta 5V y GND tanto por la entrada como por la salida del panel, con cables de al menos 0,75 mm² de sección; esto se llama inyección de energía. En el lado del software, la función setMaxPowerInVoltsAndMilliamps(5, 2000) de la biblioteca FastLED calcula la corriente estimada en cada fotograma y reduce el brillo automáticamente si se va a superar el límite. Si usas batería, puedes comprobar cuánto durará el circuito con la calculadora de autonomía de batería, y para elegir la fuente consulta el artículo sobre la alimentación de Arduino.

Animación de matriz 16x16 con ESP32 (FastLED)

El ESP32, con su amplia RAM y su procesador de 240 MHz, es una opción mucho más cómoda para paneles grandes; además genera la señal NeoPixel con la unidad de hardware RMT, así que apenas ocupa el procesador. El código siguiente dibuja con FastLED dos puntos de colores que se deslizan dejando estela en un panel 16x16. beatsin8() genera una coordenada que oscila de forma sinusoidal con el tiempo, y fadeToBlackBy() oscurece un poco todos los píxeles en cada fotograma para crear el efecto de cola. Basta con instalar la última versión de FastLED desde el Gestor de bibliotecas; las versiones actuales admiten los núcleos 2.x y 3.x de Arduino para ESP32.

1#include <FastLED.h>
2
3#define DATA_PIN 16                // DIN -> GPIO 16 (330 ohm ile) / DIN -> GPIO 16 (via 330 ohm)
4#define W 16
5#define H 16
6#define NUM_LEDS (W * H)
7
8CRGB leds[NUM_LEDS];
9
10// Zikzak dizilim için koordinat dönüşümü / coordinate mapping for serpentine layout
11uint16_t xyIndex(uint8_t x, uint8_t y) {
12  return (y & 1) ? (y * W + (W - 1 - x)) : (y * W + x);
13}
14
15void setup() {
16  FastLED.addLeds<WS2812B, DATA_PIN, GRB>(leds, NUM_LEDS);
17  FastLED.setBrightness(60);                       // genel parlaklık / global brightness
18  FastLED.setMaxPowerInVoltsAndMilliamps(5, 2000); // 5 V, en fazla 2 A / 5 V, max 2 A
19  FastLED.clear(true);
20}
21
22void loop() {
23  static uint8_t hue = 0;
24  fadeToBlackBy(leds, NUM_LEDS, 30);               // iz efekti / trail effect
25
26  uint8_t px1 = beatsin8(13, 0, W - 1);            // sinüs salınımlı koordinatlar / sine-wave coordinates
27  uint8_t py1 = beatsin8(17, 0, H - 1);
28  uint8_t px2 = beatsin8(11, 0, W - 1, 0, 64);
29  uint8_t py2 = beatsin8(7, 0, H - 1, 0, 128);
30
31  leds[xyIndex(px1, py1)] = CHSV(hue, 255, 255);
32  leds[xyIndex(px2, py2)] = CHSV(hue + 128, 255, 255);
33
34  FastLED.show();
35  hue++;
36  delay(16);                                       // yaklaşık 60 kare/sn / about 60 fps
37}

Matriz NeoPixel con Raspberry Pi Pico y MicroPython

En el firmware MicroPython de la Pico el módulo neopixel viene incluido, sin necesidad de copiar ningún archivo. El módulo genera por sí mismo la temporización de la señal; tú solo asignas el color con np[i] = (r, g, b) y lo envías al panel con write(). Como en MicroPython no existe una función setBrightness como la de la biblioteca de Adafruit, limitas el brillo tú mismo multiplicando los valores de color por un coeficiente. El ejemplo siguiente hace brillar y apagarse lentamente un corazón en un panel 8x8; el icono se dibuja a partir de un array de mapa de bits en el que cada fila es un byte y el bit más a la izquierda corresponde a la columna x = 0.

1from machine import Pin
2from neopixel import NeoPixel
3import time
4
5W, H = 8, 8
6np = NeoPixel(Pin(2), W * H)       # DIN -> GP2 (330 ohm ile) / DIN -> GP2 (via 330 ohm)
7BRIGHTNESS = 0.1                   # %10 parlaklık / 10% brightness
8
9HEART = [
10    0b01100110,
11    0b11111111,
12    0b11111111,
13    0b11111111,
14    0b01111110,
15    0b00111100,
16    0b00011000,
17    0b00000000,
18]
19
20def xy_index(x, y):
21    # zikzak dizilim / serpentine layout
22    if y % 2:
23        return y * W + (W - 1 - x)
24    return y * W + x
25
26def draw_bitmap(rows, color):
27    r, g, b = color
28    c = (int(r * BRIGHTNESS), int(g * BRIGHTNESS), int(b * BRIGHTNESS))
29    for y in range(H):
30        for x in range(W):
31            on = rows[y] & (0x80 >> x)     # soldaki bit x=0 / leftmost bit is x=0
32            np[xy_index(x, y)] = c if on else (0, 0, 0)
33    np.write()                     # panele gönder / push to the panel
34
35while True:
36    for level in range(0, 256, 8):         # kalp yavaşça yanar / heart fades in
37        draw_bitmap(HEART, (level, 0, 0))
38        time.sleep_ms(20)
39    for level in range(255, -1, -8):       # ve söner / and fades out
40        draw_bitmap(HEART, (level, 0, 0))
41        time.sleep_ms(20)

Ideas de proyectos con matriz NeoPixel

• Cartel de texto en desplazamiento: con un ESP32, desplaza mensajes recibidos de internet o la hora; para la hora puedes usar el método del artículo reloj NTP con ESP32.
• Juegos de la serpiente y de bloques: monta una minicónsola de juegos en color con un panel de 16x16 y un joystick.
• Espectro sensible a la música: muestra el nivel de sonido medido con un micrófono en columnas de colores; los detalles están en el artículo sobre LED sensibles a la música.
• Insignia de iconos: cambia con un botón entre iconos como una cara sonriente, un corazón y una flecha en un panel 8x8.
• Termómetro de colores: dibuja una barra que se llena de azul a rojo según la temperatura medida con un DHT11.
• Control desde el móvil: instala WLED en el ESP32 y maneja el panel por Wi-Fi con efectos 2D ya hechos.
• Adorno navideño: añade un panel visual con animaciones de nieve y estrellas a tu proyecto de árbol de Navidad con LED.

Errores comunes y cómo solucionarlos

Una matriz NeoPixel, con un panel de precio asequible, es la forma más divertida de dar a tus proyectos una pantalla colorida y en movimiento. Empieza poco a poco: primero haz funcionar el panel 8x8 con brillo bajo, asienta la función xyIndex y después pasa al texto en desplazamiento y a las animaciones 16x16. Si solo vas a mostrar texto y números de un color, una matriz LED MAX7219 es una alternativa que consume menos corriente. En la app de BlueGrays puedes revisar paso a paso, con esquemas y código, proyectos como la luz de policía WS2812B, el coche fantástico y las animaciones, además de juegos de la serpiente en matrices 8x8 y 16x16.