Matriz NeoPixel com Arduino: guia de painéis LED WS2812B 8x8 e 16x16

Uma matriz NeoPixel é um dos displays mais chamativos que você pode montar com Arduino. Ela é formada por 8x8 (64 LEDs) ou 16x16 (256 LEDs) LEDs RGB endereçáveis WS2812B dispostos em um painel, e você define a cor de cada pixel individualmente por um único fio de dados. É ideal para texto rolante, ícones, pequenos jogos, indicadores de espectro de áudio e animações decorativas. Neste guia você vai aprender, passo a passo, a disposição em zigue-zague dentro do painel, a função que converte uma coordenada x-y no número do LED, o texto rolante e as animações.

Trabalhar com uma matriz exige um pouco mais de cuidado do que uma única fita NeoPixel. 256 LEDs podem puxar mais de 15 amperes com brilho máximo, os 2 KB de RAM do Arduino Uno se esgotam rápido em painéis grandes, e a saída de 3,3 V do ESP32 e do Pico pode causar problemas em alguns painéis. Por isso, além do código, também vamos tratar do cálculo de corrente, da limitação de brilho e do planejamento de memória. Se você ainda não conhece o básico do WS2812B, confira antes o post sobre LED WS2812B NeoPixel.

O que é uma matriz LED NeoPixel e como ela funciona?

Dentro de cada LED WS2812B, ao lado dos chips vermelho, verde e azul, há um pequeno CI driver. O microcontrolador envia 24 bits de dados de cor por LED pela linha de dados a 800 kHz; a ordem dos bits é verde, vermelho, azul (GRB). O primeiro LED pega os primeiros 24 bits para si e repassa o restante ao próximo pelo pino DOUT, e a cadeia continua assim. Um painel de matriz funciona do mesmo jeito: os 64 ou 256 LEDs são, na verdade, uma fita comprida dobrada em forma de quadrado. Enviar dados para um LED leva cerca de 30 microssegundos, então atualizar uma vez um painel de 256 LEDs leva cerca de 7,7 ms, o que significa animação fluida a mais de 100 quadros por segundo.

Disposição dos pixels em zigue-zague e a função de coordenadas XY

No código, você quer pensar em um pixel como uma coordenada (x, y), mas os LEDs são endereçados por um único índice que começa em 0. Em quase todos os painéis flexíveis e nos modelos 16x16, os LEDs são dispostos em zigue-zague (serpentina): a primeira linha vai da esquerda para a direita, a segunda vai da direita para a esquerda e a terceira volta a ir da esquerda para a direita. Essa disposição facilita a fabricação, porque o fim de cada linha se liga ao início da próxima pelo caminho mais curto. Na tabela abaixo você vê os números dos LEDs nas quatro primeiras linhas de um painel 8x8 em zigue-zague:

A fórmula sai diretamente daí: nas linhas pares índice = y × W + x, e nas linhas ímpares índice = y × W + (W − 1 − x), em que W é a largura do painel. Por exemplo, em um painel 8x8 o ponto (2, 1) é o LED número 1 × 8 + (7 − 2) = 13. Atenção: em algumas placas 8x8 de PCB rígida, todas as linhas seguem no mesmo sentido (disposição reta ou progressiva); nesse caso a fórmula é simplesmente y × W + x. Em alguns painéis, os LEDs serpenteiam ao longo das colunas em vez das linhas, o que significa que x e y precisam ser trocados. O jeito mais seguro de descobrir qual é o seu tipo é rodar um sketch de teste que acende os LEDs um por um e observar o caminho que a luz percorre.

Ligação da matriz NeoPixel: Arduino Uno, ESP32 e Pico

Para um circuito robusto, acrescente três pequenos componentes: um resistor de 300–500 Ω em série com a linha de dados (ele protege a entrada do primeiro LED contra picos de tensão), um capacitor eletrolítico de 1000 µF entre o 5V e o GND do painel (ele suaviza o pico de corrente quando a fonte é ligada) e, se necessário, um conversor de nível lógico nas placas de 3,3 V. Com alimentação de 5 V, o WS2812B quer ver pelo menos cerca de 3,5 V (70% da tensão de alimentação) na entrada de dados; a saída de 3,3 V do ESP32 e do Pico funciona na maioria dos painéis, mas fica abaixo desse limite. Se você notar cintilação ou cores aleatórias, use um CI buffer como o 74AHCT125; os detalhes estão no post sobre conversor de nível lógico.

Primeiro programa da matriz passo a passo (Arduino Uno)

1. Abra o Gerenciador de Bibliotecas no Arduino IDE e instale a biblioteca Adafruit NeoPixel.
2. Ligue o painel como na tabela: DIN ao D6 por um resistor de 330 Ω, GND ao GND do Arduino, 5V à fonte.
3. Ajuste W e H no código para o tamanho do seu painel; para um painel 16x16, coloque 16 nos dois.
4. Mantenha o brilho baixo na primeira tentativa; setBrightness(30) reduz a corrente de um painel 8x8 a um nível que a USB aguenta.
5. Carregue o código; você deve ver um arco-íris rolando na diagonal. Se as cores parecerem quebradas linha a linha, a disposição do seu painel é diferente, então ajuste a função xyIndex de acordo.

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}

O coração do código é a função xyIndex(): invertendo x nas linhas ímpares, ela esconde a disposição em zigue-zague, e no restante do código você só pensa em coordenadas. ColorHSV() converte em RGB um valor de matiz entre 0 e 65535 na roda de cores; como a matiz muda conforme a soma x + y cresce, surgem faixas de cor diagonais. gamma32() corrige a forma como o olho percebe o brilho e deixa as transições de cor mais naturais. Por fim, nenhuma alteração chega ao painel até você chamar show(); escrever primeiro todos os pixels na memória e enviá-los de uma vez é o segredo de uma imagem fluida.

Texto rolante: com Adafruit NeoMatrix

Você não precisa mexer pixel por pixel para desenhar letras e ícones. A biblioteca Adafruit NeoMatrix transforma seu painel NeoPixel em um display compatível com Adafruit GFX, então as funções que você usa em displays OLED, como print(), drawLine(), fillRect() e drawBitmap(), também funcionam na matriz. Ao instalar a Adafruit NeoMatrix pelo Gerenciador de Bibliotecas, instale também as dependências Adafruit GFX e Adafruit NeoPixel. As flags no construtor descrevem a disposição física do painel: NEO_MATRIX_TOP + NEO_MATRIX_LEFT diz que o primeiro LED fica no canto superior esquerdo, NEO_MATRIX_ROWS diz que os LEDs seguem ao longo das linhas e NEO_MATRIX_ZIGZAG diz que as linhas fazem zigue-zague; em uma placa de disposição reta, basta escrever NEO_MATRIX_PROGRESSIVE em vez de ZIGZAG. A fonte padrão de 5×7 cabe perfeitamente em um painel de 8 linhas, e cada caractere tem 6 pixels de largura, incluindo o espaçamento. Um texto de nove letras ocupa 54 pixels; a constante textWidth calcula isso automaticamente, e quando x fica abaixo desse valor o texto volta a entrar pela direita e muda de cor.

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}

Limites de memória no Arduino Uno

O ATmega328P do Arduino Uno tem só 2048 bytes de RAM, e cada LED precisa de um buffer de cor de 3 bytes. Um painel 8x8 cabe com folga em 192 bytes, enquanto um painel 16x16 ocupa 768 bytes, mais de um terço da RAM sozinho. A parte traiçoeira é esta: a Adafruit NeoPixel aloca esse buffer enquanto o programa está rodando, então ele não entra no uso de variáveis globais mostrado ao fim da compilação. Mesmo que a compilação indique 70% de uso, a memória pode acabar quando o buffer do painel é somado; aí a placa trava ou você vê cores sem sentido. Além disso, nas placas AVR as interrupções ficam desativadas enquanto show() roda; com 256 LEDs isso leva cerca de 7,7 ms, durante os quais millis() pode atrasar e dados chegando pela Serial podem se perder. Para painéis grandes, um Arduino Mega com 8 KB de RAM ou um ESP32 com centenas de kilobytes é uma escolha muito mais confortável.

Consumo de corrente e limitação de brilho

Cada canal de cor de um WS2812B puxa cerca de 20 mA com brilho máximo; quando os três estão acesos, ou seja, em branco, isso dá 60 mA por LED. Para uma conta aproximada, você pode usar a fórmula I ≈ número de LEDs × 60 mA × (brilho / 255). Um painel 16x16 em branco total puxa 256 × 60 = 15,360 mA, mais de 15 A; isso sobrecarrega tanto as fontes de alimentação quanto as trilhas finas de cobre do painel. A boa notícia é que a matriz é muito brilhante: em ambientes internos, um brilho de 20–50 em 255 já fica nítido o bastante para chamar a atenção. Em animações reais nem todos os LEDs ficam brancos ao mesmo tempo, então a corrente média é bem menor que o valor calculado, mas mesmo assim é preciso escolher a fonte pensando no pior caso ou limitar a corrente por software.

Em um painel 16x16, se você alimentar a corrente só por uma extremidade, os LEDs do canto mais distante sofrem queda de tensão e o branco fica amarelado ou avermelhado. Para evitar isso, alimente 5V e GND pelas duas extremidades do painel, entrada e saída, usando fios de pelo menos 0,75 mm² de seção; isso se chama injeção de alimentação. No lado do software, a função setMaxPowerInVoltsAndMilliamps(5, 2000) da biblioteca FastLED calcula a corrente estimada a cada quadro e reduz o brilho automaticamente se o limite for ultrapassado. Se usar baterias, você pode conferir quanto tempo o circuito vai durar com a calculadora Autonomia da bateria, e para detalhes sobre a escolha da fonte veja o post sobre alimentação do Arduino.

Animação em matriz 16x16 com ESP32 (FastLED)

Com sua RAM grande e o processador de 240 MHz, o ESP32 é uma escolha muito mais confortável para painéis grandes; como ele gera o sinal NeoPixel com a unidade de hardware RMT, também não deixa o processador muito ocupado. O código abaixo usa a FastLED para desenhar dois pontos coloridos deslizando com rastro em um painel 16x16. beatsin8() produz uma coordenada que oscila de forma senoidal ao longo do tempo, enquanto fadeToBlackBy() escurece um pouco todos os pixels a cada quadro para criar o efeito de cauda. Basta instalar a versão mais recente da FastLED pelo Gerenciador de Bibliotecas; as versões atuais suportam tanto a 2.x quanto a 3.x do core Arduino do 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 com Raspberry Pi Pico e MicroPython

O MicroPython do Pico já vem com o módulo neopixel embutido, então você não precisa copiar nenhum arquivo extra. O próprio módulo gera a temporização do sinal; você só atribui as cores com np[i] = (r, g, b) e as envia ao painel com write(). Como o MicroPython não tem uma função setBrightness como a da biblioteca da Adafruit, você mesmo limita o brilho multiplicando os valores de cor por um fator. O exemplo abaixo faz um ícone de coração acender e apagar devagar em um painel 8x8; o ícone é desenhado a partir de um array de bitmap em que cada linha é um byte e o bit mais à esquerda corresponde à coluna 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)

Ideias de projetos com matriz NeoPixel

• Letreiro de texto rolante: faça rolar mensagens buscadas na internet, ou a hora, com um ESP32; para o relógio, você pode usar o método do post relógio NTP com ESP32.
• Jogos de cobrinha e de blocos: monte um minivideogame colorido com um painel 16x16 e um joystick.
• Espectro que reage à música: mostre o nível de som medido por um microfone como colunas coloridas; os detalhes estão no post LEDs que reagem à música.
• Crachá de ícones: alterne com um botão entre ícones como carinha sorridente, coração e seta em um painel 8x8.
• Termômetro colorido: desenhe uma barra que se enche do azul ao vermelho conforme a temperatura medida por um DHT11.
• Controle pelo celular: instale o WLED em um ESP32 e controle o painel pelo Wi-Fi com efeitos 2D prontos.
• Decoração de Natal: acrescente um painel visual com animações de neve caindo e estrelas ao seu projeto de árvore de Natal com LEDs.

Erros comuns e como corrigi-los

A matriz NeoPixel é o jeito mais divertido de dar aos seus projetos um display colorido e animado com um painel acessível. Comece pequeno: primeiro faça um painel 8x8 funcionar com brilho baixo, acerte a função xyIndex e depois passe para o texto rolante e as animações em 16x16. Se você só precisa mostrar texto e números de uma cor, uma matriz LED MAX7219 é uma alternativa que consome menos corrente. No app BlueGrays você pode explorar projetos de luzes de polícia com WS2812B, efeito Knight Rider e animações, além de jogos da cobrinha em matrizes 8x8 e 16x16, passo a passo, com esquemas do circuito e código.