Matrice LED NeoPixel Arduino: guida a pannelli WS2812B 8x8 e 16x16

La matrice NeoPixel è uno dei display più spettacolari che tu possa costruire con Arduino: è formata da 8x8 (64 LED) o 16x16 (256 LED) LED RGB indirizzabili WS2812B disposti su un pannello, e il colore di ogni pixel si imposta singolarmente con un solo filo dati. È ideale per testi scorrevoli, icone, piccoli giochi, indicatori di spettro audio e animazioni decorative. In questa guida imparerai passo dopo passo la disposizione a serpentina del pannello, la funzione che converte le coordinate x-y nel numero del LED, il testo scorrevole e le animazioni.

Lavorare con una matrice richiede un po' più di attenzione rispetto a una singola striscia NeoPixel. 256 LED a piena luminosità possono assorbire più di 15 ampere, i 2 KB di RAM di Arduino Uno si riempiono in fretta con i pannelli grandi, e l'uscita a 3,3 V di ESP32 e Pico può dare problemi con alcuni pannelli. Per questo, oltre al codice, vedremo anche il calcolo della corrente, la limitazione della luminosità e la gestione della memoria. Se non conosci ancora le basi del WS2812B, dai prima un'occhiata all'articolo LED WS2812B NeoPixel.

Cos'è una matrice LED NeoPixel e come funziona?

All'interno di ogni LED WS2812B, accanto ai chip rosso, verde e blu, c'è un piccolo circuito integrato di controllo. Il microcontrollore invia sulla linea dati a 800 kHz 24 bit di colore per ogni LED; l'ordine dei bit è verde, rosso, blu (GRB). Il primo LED trattiene i primi 24 bit e passa il resto al successivo tramite il pin DOUT, e così via lungo la catena. Nel pannello a matrice è lo stesso: i 64 o 256 LED sono in realtà una lunga striscia ripiegata a forma di quadrato. Inviare i dati a un LED richiede circa 30 microsecondi, quindi aggiornare un pannello da 256 LED richiede circa 7,7 ms: più di 100 fotogrammi al secondo, per animazioni fluide.

Disposizione dei pixel a serpentina e funzione di coordinate XY

Nel codice vorresti ragionare con le coordinate (x, y) di un pixel, ma i LED si indirizzano con un unico numero progressivo che parte da 0. Quasi tutti i pannelli flessibili e i modelli 16x16 hanno i LED disposti a serpentina (zigzag): la prima riga va da sinistra a destra, la seconda torna da destra a sinistra, la terza di nuovo da sinistra a destra. Questa disposizione semplifica la produzione, perché la fine di ogni riga si collega all'inizio della successiva nel modo più breve. Nella tabella qui sotto vedi i numeri dei LED delle prime quattro righe di un pannello 8x8 a serpentina:

La formula ne deriva da sola: nelle righe pari indice = y × W + x, in quelle dispari indice = y × W + (W − 1 − x), dove W è la larghezza del pannello. Per esempio, in un 8x8 il punto (2, 1) è il LED numero 1 × 8 + (7 − 2) = 13. Attenzione: su alcune schede 8x8 con PCB rigido tutte le righe procedono nella stessa direzione (disposizione lineare o progressiva); in quel caso la formula è semplicemente y × W + x. In altri pannelli i LED si ripiegano lungo le colonne invece che lungo le righe, quindi x e y vanno scambiati. Il modo più sicuro per capire di che tipo è il tuo pannello è eseguire un codice di prova che accende i LED uno alla volta e osservare come procede la luce.

Collegamento della matrice NeoPixel: Arduino Uno, ESP32 e Pico

Per un circuito affidabile aggiungi tre piccoli componenti: una resistenza da 300–500 Ω in serie sulla linea dati (protegge l'ingresso del primo LED dai picchi di tensione), un condensatore elettrolitico da circa 1000 µF tra 5V e GND del pannello (attenua l'impulso di corrente all'accensione dell'alimentatore) e, se serve, un convertitore di livello sulle schede a 3,3 V. Con alimentazione a 5 V, il WS2812B vuole vedere sull'ingresso dati almeno circa 3,5 V (il 70% della tensione di alimentazione); l'uscita a 3,3 V di ESP32 e Pico funziona con la maggior parte dei pannelli, ma è sotto questa soglia. Se vedi sfarfallii o colori casuali, usa un buffer come il 74AHCT125; trovi i dettagli nell'articolo sul convertitore di livello logico.

Il primo programma per la matrice passo dopo passo (Arduino Uno)

1. Nell'IDE di Arduino apri il Gestore librerie e installa la libreria Adafruit NeoPixel.
2. Collega il pannello come nella tabella: DIN a D6 con la resistenza da 330 Ω, GND al GND di Arduino, 5V all'alimentatore.
3. Imposta i valori W e H nel codice in base alle dimensioni del pannello; per un 16x16 mettili entrambi a 16.
4. Nella prima prova tieni bassa la luminosità: setBrightness(30) porta la corrente di un pannello 8x8 a un livello che la USB riesce a sostenere.
5. Carica il codice: dovresti vedere un arcobaleno diagonale che scorre. Se i colori appaiono spezzati riga per riga, la disposizione del tuo pannello è diversa: correggi di conseguenza la funzione xyIndex.

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}

Il cuore del codice è la funzione xyIndex(): nasconde la serpentina invertendo x sulle righe dispari, così nel resto del codice ragioni solo con le coordinate. ColorHSV() converte in RGB un valore di tonalità da 0 a 65535 sulla ruota dei colori; poiché la tonalità cambia al crescere di x + y, si formano strisce di colore diagonali. gamma32() corregge i valori in base alla percezione della luminosità dell'occhio e rende le transizioni di colore più naturali. Infine, finché non chiami show() nessuna modifica arriva al pannello: scrivere prima tutti i pixel in memoria e inviarli in una volta sola è il segreto di un'immagine fluida.

Testo scorrevole con Adafruit NeoMatrix

Per disegnare lettere e simboli non devi lavorare pixel per pixel. La libreria Adafruit NeoMatrix trasforma il pannello NeoPixel in un display compatibile con Adafruit GFX, così funzioni come print(), drawLine(), fillRect() e drawBitmap(), che usi con i display OLED, funzionano anche sulla matrice. Quando installi Adafruit NeoMatrix dal Gestore librerie, installa anche le dipendenze Adafruit GFX e Adafruit NeoPixel. I flag nel costruttore descrivono la disposizione fisica del pannello: NEO_MATRIX_TOP + NEO_MATRIX_LEFT indica che il primo LED è in alto a sinistra, NEO_MATRIX_ROWS che i LED seguono le righe e NEO_MATRIX_ZIGZAG che le righe sono a zigzag; su una scheda con disposizione lineare basta scrivere NEO_MATRIX_PROGRESSIVE al posto di ZIGZAG. Il font predefinito 5×7 si adatta perfettamente a un pannello di 8 righe e ogni carattere, spazio incluso, è largo 6 pixel. Un testo di nove lettere occupa 54 pixel; la costante textWidth lo calcola in automatico e, quando x scende sotto questo valore, il testo rientra da destra e cambia colore.

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}

Il limite di memoria di Arduino Uno

Il processore ATmega328P dell'Arduino Uno ha solo 2048 byte di RAM e per ogni LED serve un buffer colore di 3 byte. Un pannello 8x8 ci sta comodamente con 192 byte, mentre un 16x16 con 768 byte occupa da solo più di un terzo della RAM. Il lato insidioso è questo: Adafruit NeoPixel alloca il buffer mentre il programma è in esecuzione, quindi non rientra nella percentuale di variabili globali mostrata al termine della compilazione. Anche se la compilazione indica il 70% di utilizzo, aggiungendo il buffer del pannello la memoria può esaurirsi: la scheda si blocca o vedi colori senza senso. Inoltre, sulle schede AVR le interruzioni sono disattivate durante show(); con 256 LED dura circa 7,7 ms, durante i quali millis() può restare indietro e i dati in arrivo da Serial possono andare persi. Per i pannelli grandi, Arduino Mega con 8 KB di RAM o ESP32 con centinaia di kilobyte sono scelte molto più comode.

Consumo di corrente e limitazione della luminosità

Ogni canale colore di un WS2812B assorbe circa 20 mA a piena luminosità; con i tre canali accesi insieme, cioè in bianco, sono 60 mA per LED. Per un calcolo approssimativo puoi usare la formula I ≈ numero di LED × 60 mA × (luminosità / 255). Un pannello 16x16 in bianco pieno assorbe 256 × 60 = 15.360 mA, cioè più di 15 A, un carico che mette a dura prova sia gli alimentatori sia le sottili piste di rame del pannello. La buona notizia è che la matrice è molto luminosa: in ambienti interni una luminosità tra 20 e 50 su 255 è già ben visibile. Nelle animazioni reali non tutti i LED sono bianchi contemporaneamente, quindi la corrente media è molto inferiore al valore calcolato, ma l'alimentatore va scelto sul caso peggiore oppure la corrente va limitata via software.

Su un pannello 16x16, se alimenti solo da un'estremità, nei LED dell'angolo opposto la tensione cala e il bianco appare giallastro o rossastro. Per evitarlo, alimenta 5V e GND sia dall'ingresso sia dall'uscita del pannello con cavi di sezione almeno 0,75 mm²: si chiama iniezione di alimentazione. Lato software, la funzione setMaxPowerInVoltsAndMilliamps(5, 2000) della libreria FastLED calcola la corrente stimata a ogni fotogramma e, se sta per superare il limite, riduce automaticamente la luminosità. Se usi una batteria, puoi verificare quanto durerà il circuito con il calcolatore della durata della batteria, mentre per la scelta dell'alimentazione consulta l'articolo alimentazione di Arduino.

Animazione su matrice 16x16 con ESP32 (FastLED)

Con la sua RAM abbondante e il processore a 240 MHz, ESP32 è una scelta molto più comoda per i pannelli grandi; inoltre genera il segnale NeoPixel con l'unità hardware RMT e quindi impegna poco il processore. Il codice qui sotto, con FastLED, disegna su un pannello 16x16 due punti colorati che scivolano lasciando una scia. beatsin8() genera una coordinata che oscilla nel tempo in forma sinusoidale, mentre fadeToBlackBy() oscura leggermente tutti i pixel a ogni fotogramma creando l'effetto coda. Ti basta installare dal Gestore librerie l'ultima versione di FastLED; le versioni attuali supportano le versioni 2.x e 3.x del core Arduino per 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}

Matrice NeoPixel con Raspberry Pi Pico e MicroPython

Nel MicroPython del Pico il modulo neopixel è già incluso, quindi non devi copiare altri file. Il modulo genera da sé la temporizzazione del segnale: tu assegni il colore con np[i] = (r, g, b) e lo invii al pannello con write(). Poiché in MicroPython non esiste una funzione setBrightness come nella libreria Adafruit, la luminosità la limiti tu moltiplicando i valori dei colori per un coefficiente. L'esempio seguente fa accendere e spegnere lentamente un cuore su un pannello 8x8; l'icona è disegnata da un array bitmap in cui ogni riga è un byte e il bit più a sinistra corrisponde alla colonna 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)

Idee per progetti con la matrice NeoPixel

• Insegna scorrevole: fai scorrere sul pannello messaggi presi da internet o l'ora con ESP32; per l'orologio puoi usare il metodo dell'articolo orologio NTP con ESP32.
• Giochi Snake e a blocchi: costruisci una mini console colorata con un pannello 16x16 e un joystick.
• Spettro audio: mostra il livello del suono misurato con un microfono in colonne colorate; i dettagli sono nell'articolo LED sensibili alla musica.
• Badge con icone: sul pannello 8x8 alterna con un pulsante icone come faccina sorridente, cuore e freccia.
• Termometro colorato: disegna una barra che si riempie dal blu al rosso in base alla temperatura misurata dal DHT11.
• Controllo da telefono: installa WLED su ESP32 e gestisci il pannello via Wi-Fi con effetti 2D già pronti.
• Decorazione natalizia: aggiungi un pannello con animazioni di neve e stelle al tuo progetto di albero di Natale a LED.

Errori comuni e come risolverli

La matrice NeoPixel è il modo più divertente per dare ai tuoi progetti un display colorato e animato con un pannello dal prezzo accessibile. Parti in piccolo: prima fai funzionare il pannello 8x8 a bassa luminosità, metti a punto la funzione xyIndex, poi passa al testo scorrevole e alle animazioni 16x16. Se devi mostrare solo testo e numeri monocolore, la matrice LED MAX7219 è un'alternativa che consuma meno corrente. Nell'app BlueGrays trovi passo dopo passo, con schemi e codice, il lampeggiante della polizia WS2812B, l'auto fantastica e i progetti di animazione, oltre ai giochi Snake su matrice 8x8 e 16x16.