NeoPixel Matrix Arduino: 8x8 & 16x16 WS2812B LED-Panel Guide

Die NeoPixel-Matrix gehört zu den eindrucksvollsten Displays, die du mit dem Arduino bauen kannst: 8x8 (64 LEDs) oder 16x16 (256 LEDs) adressierbare WS2812B-RGB-LEDs sitzen auf einem Panel, und die Farbe jedes Pixels stellst du über nur eine einzige Datenleitung einzeln ein. Ideal für Lauftexte, Symbole, kleine Spiele, Audio-Spektrum-Anzeigen und dekorative Animationen. In diesem Guide lernst du Schritt für Schritt das Zickzack-Layout im Panel, die Funktion, die x-y-Koordinaten in eine LED-Nummer umrechnet, sowie Lauftext und Animationen.

Mit einer Matrix zu arbeiten erfordert etwas mehr Aufmerksamkeit als bei einem einzelnen NeoPixel-Streifen. 256 LEDs können bei voller Helligkeit mehr als 15 Ampere ziehen, die 2 KB RAM des Arduino Uno sind bei großen Panels schnell voll, und der 3,3-V-Ausgang von ESP32 und Pico macht bei manchen Panels Probleme. Deshalb behandeln wir neben dem Code auch Strombedarf, Helligkeitsbegrenzung und Speicherplanung. Wenn du die Grundlagen des WS2812B noch nicht kennst, lies zuerst den Beitrag WS2812B NeoPixel LED.

Was ist eine NeoPixel-LED-Matrix und wie funktioniert sie?

In jeder WS2812B-LED sitzt neben den roten, grünen und blauen Chips ein kleiner Treiber-IC. Der Mikrocontroller sendet über die Datenleitung mit 800 kHz pro LED 24 Bit Farbinformation; die Reihenfolge ist Grün, Rot, Blau (GRB). Die erste LED übernimmt die ersten 24 Bit und reicht den Rest über DOUT an die nächste weiter, und so setzt sich die Kette fort. Beim Matrix-Panel ist es genauso: Die 64 oder 256 LEDs sind eigentlich ein langer Streifen, der zu einem Quadrat gefaltet wurde. Das Senden an eine LED dauert etwa 30 Mikrosekunden, daher braucht ein Update des 256-LED-Panels rund 7,7 ms, also deutlich mehr als 100 flüssige Bilder pro Sekunde.

Zickzack-Pixel-Layout und die XY-Koordinatenfunktion

Im Code willst du ein Pixel als Koordinate (x, y) denken, aber die LEDs werden über eine einzige, bei 0 beginnende Nummer adressiert. Bei fast allen flexiblen Panels und bei 16x16-Modellen sind die LEDs im Zickzack (Serpentine) angeordnet: Die erste Reihe läuft von links nach rechts, die zweite von rechts nach links, die dritte wieder von links nach rechts. Das erleichtert die Fertigung, weil das Ende jeder Reihe auf kürzestem Weg mit dem Anfang der nächsten verbunden wird. In der folgenden Tabelle siehst du die LED-Nummern der ersten vier Reihen eines 8x8-Zickzack-Panels:

Die Formel ergibt sich daraus von selbst: In geraden Reihen gilt Index = y × W + x, in ungeraden Reihen Index = y × W + (W − 1 − x); dabei ist W die Breite des Panels. Beim 8x8-Panel ist der Punkt (2, 1) zum Beispiel die LED Nr. 1 × 8 + (7 − 2) = 13. Achtung: Bei manchen 8x8-Platinen mit starrer Leiterplatte laufen alle Reihen in dieselbe Richtung (progressives Layout); dann lautet die Formel einfach y × W + x. Bei manchen Panels verlaufen die LEDs spaltenweise statt zeilenweise, dann musst du x und y vertauschen. Am sichersten findest du den Typ heraus, indem du einen Testcode laufen lässt, der die LEDs nacheinander einzeln einschaltet, und beobachtest, wie das Licht wandert.

NeoPixel-Matrix anschließen: Arduino Uno, ESP32 und Pico

Für eine robuste Schaltung ergänzt du drei kleine Teile: einen 300–500 Ω-Widerstand in Reihe zur Datenleitung (schützt den Eingang der ersten LED vor Spannungsspitzen), einen Elektrolytkondensator von etwa 1000 µF zwischen 5V und GND des Panels (glättet den Stromstoß beim Einschalten des Netzteils) und bei 3,3-V-Boards bei Bedarf einen Pegelwandler. Der WS2812B möchte bei 5 V Versorgung am Dateneingang mindestens etwa 3,5 V sehen (70 % der Versorgungsspannung); der 3,3-V-Ausgang von ESP32 und Pico liegt darunter, funktioniert aber bei den meisten Panels trotzdem. Wenn du Flackern oder zufällige Farben siehst, nimm einen Puffer-IC wie den 74AHCT125; Details findest du im Beitrag Pegelwandler.

Schritt für Schritt: dein erstes Matrix-Programm (Arduino Uno)

1. Öffne in der Arduino IDE den Bibliotheksverwalter und installiere die Bibliothek Adafruit NeoPixel.
2. Schließe das Panel gemäß Tabelle an: DIN über 330 Ω an D6, GND an Arduino-GND, 5V an die Stromquelle.
3. Passe W und H im Code an die Panelgröße an; bei einem 16x16-Panel setzt du beide auf 16.
4. Halte die Helligkeit beim ersten Test niedrig; setBrightness(30) senkt den Strom eines 8x8-Panels auf ein Niveau, das USB liefern kann.
5. Lade den Code hoch; du solltest einen diagonal wandernden Regenbogen sehen. Wirken die Farben Reihe für Reihe zerrissen, hat dein Panel ein anderes Layout, und du musst die Funktion xyIndex entsprechend anpassen.

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}

Das Herzstück des Codes ist die Funktion xyIndex(): Sie dreht in ungeraden Reihen x um und versteckt so das Zickzack-Layout, sodass du im restlichen Code nur noch in Koordinaten denkst. ColorHSV() wandelt einen Farbtonwert zwischen 0 und 65535 auf dem Farbkreis in RGB um; da der Farbton mit der Summe x + y wandert, entstehen diagonale Farbstreifen. gamma32() korrigiert nach der Helligkeitswahrnehmung des Auges und lässt Farbverläufe natürlicher wirken. Und ohne show() wird nichts an das Panel gesendet; alle Pixel zuerst in den Speicher zu schreiben und dann auf einmal zu senden, ist das Geheimnis eines flüssigen Bildes.

Lauftext: mit Adafruit NeoMatrix

Für Buchstaben und Symbole musst du nicht Pixel für Pixel arbeiten. Die Bibliothek Adafruit NeoMatrix macht aus dem NeoPixel-Panel ein Adafruit-GFX-kompatibles Display; so funktionieren Funktionen wie print(), drawLine(), fillRect() und drawBitmap(), die du von OLED-Displays kennst, auch auf der Matrix. Installiere NeoMatrix über den Bibliotheksverwalter zusammen mit den Abhängigkeiten Adafruit GFX und Adafruit NeoPixel. Die Flags im Konstruktor beschreiben den physischen Aufbau des Panels: NEO_MATRIX_TOP + NEO_MATRIX_LEFT sagt, dass die erste LED oben links sitzt, NEO_MATRIX_ROWS, dass die LEDs zeilenweise angeordnet sind, und NEO_MATRIX_ZIGZAG, dass die Reihen im Zickzack laufen; bei einem Board mit gleichgerichteten Reihen schreibst du statt ZIGZAG einfach NEO_MATRIX_PROGRESSIVE. Die Standardschrift 5×7 passt genau auf ein 8-reihiges Panel, und jedes Zeichen ist inklusive Abstand 6 Pixel breit. Ein Text mit neun Buchstaben misst 54 Pixel; die Konstante textWidth berechnet das automatisch, und wenn x unter diesen Wert fällt, läuft der Text von rechts wieder herein und wechselt die Farbe.

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}

Speichergrenze beim Arduino Uno

Der ATmega328P des Arduino Uno hat nur 2048 Byte RAM, und für jede LED wird ein 3-Byte-Farbpuffer gebraucht. Ein 8x8-Panel passt mit 192 Byte problemlos, ein 16x16-Panel belegt mit 768 Byte allein mehr als ein Drittel des RAMs. Tückisch ist: Adafruit NeoPixel reserviert diesen Puffer erst zur Laufzeit, daher steckt er nicht in der Auslastung der globalen Variablen, die nach dem Kompilieren angezeigt wird. Selbst wenn der Compiler 70 % Auslastung meldet, kann der Speicher mit dem Panelpuffer ausgehen; das Board hängt sich dann auf, oder du siehst sinnlose Farben. Außerdem werden bei AVR-Boards während show() die Interrupts abgeschaltet; bei 256 LEDs dauert das etwa 7,7 ms, in dieser Zeit kann millis() nachgehen, und Daten von Serial können verloren gehen. Für große Panels sind der Arduino Mega mit 8 KB RAM oder der ESP32 mit mehreren hundert Kilobyte RAM die deutlich bessere Wahl.

Stromverbrauch und Helligkeitsbegrenzung

Jeder Farbkanal eines WS2812B zieht bei voller Helligkeit etwa 20 mA; leuchten alle drei Kanäle, also bei Weiß, sind es 60 mA pro LED. Als grobe Rechnung kannst du die Formel I ≈ Anzahl LEDs × 60 mA × (Helligkeit / 255) verwenden. Ein 16x16-Panel zieht bei Vollweiß 256 × 60 = 15.360 mA, also mehr als 15 A; das belastet sowohl Netzteile als auch die dünnen Kupferbahnen des Panels. Die gute Nachricht: Eine Matrix ist sehr hell, in Innenräumen wirkt eine Helligkeit zwischen 20 und 50 von 255 schon blendend klar. In echten Animationen leuchten nicht alle LEDs gleichzeitig weiß, daher liegt der Durchschnittsstrom deutlich unter dem berechneten Wert, aber das Netzteil solltest du für den ungünstigsten Fall auslegen oder per Software begrenzen.

Speist du ein 16x16-Panel nur an einem Ende ein, fällt die Spannung bei den LEDs in der entfernten Ecke ab, und Weiß wirkt gelblich oder rötlich. Um das zu vermeiden, versorge 5V und GND sowohl am Eingang als auch am Ausgang des Panels mit Kabeln von mindestens 0,75 mm² Querschnitt; das nennt man Power Injection. Auf der Softwareseite berechnet die Funktion setMaxPowerInVoltsAndMilliamps(5, 2000) der FastLED-Bibliothek in jedem Frame den geschätzten Strom und senkt die Helligkeit automatisch, wenn das Limit überschritten würde. Bei Akkubetrieb kannst du die Laufzeit mit dem Akkulaufzeit-Rechner prüfen, und Details zur Netzteilwahl findest du im Beitrag Arduino Stromversorgung.

ESP32 mit 16x16-Matrix-Animation (FastLED)

Der ESP32 ist mit seinem großen RAM und dem 240-MHz-Prozessor die deutlich bessere Wahl für große Panels; da er das NeoPixel-Signal mit der RMT-Hardwareeinheit erzeugt, beansprucht er den Prozessor kaum. Der folgende Code zeichnet mit FastLED auf einem 16x16-Panel zwei farbige Punkte, die mit Leuchtspur dahingleiten. beatsin8() erzeugt eine Koordinate, die im Lauf der Zeit sinusförmig schwingt, und fadeToBlackBy() dunkelt in jedem Frame alle Pixel etwas ab und erzeugt so den Schweif-Effekt. Es genügt, die aktuelle Version von FastLED über den Bibliotheksverwalter zu installieren; aktuelle Versionen unterstützen die ESP32-Arduino-Core-Versionen 2.x und 3.x.

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}

Raspberry Pi Pico und MicroPython mit NeoPixel-Matrix

In der MicroPython-Firmware des Pico ist das Modul neopixel bereits enthalten; du musst keine zusätzliche Datei kopieren. Das Modul erzeugt das Signal-Timing selbst, du weist nur mit np[i] = (r, g, b) Farben zu und sendest sie mit write() an das Panel. Da MicroPython keine Funktion wie setBrightness der Adafruit-Bibliothek hat, begrenzt du die Helligkeit selbst, indem du die Farbwerte mit einem Faktor multiplizierst. Das folgende Beispiel lässt auf einem 8x8-Panel ein Herz-Symbol langsam auf- und abglimmen; das Symbol wird aus einem Bitmap-Array gezeichnet, bei dem jede Zeile ein Byte ist und das linke Bit der Spalte x = 0 entspricht.

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)

Projektideen mit der NeoPixel-Matrix

• Lauftext-Schild: Lass mit dem ESP32 Nachrichten aus dem Internet oder die Uhrzeit über das Panel laufen; für die Uhr kannst du die Methode aus dem Beitrag ESP32 NTP-Uhr nutzen.
• Snake und Blockspiele: Baue mit einem 16x16-Panel und einem Joystick eine bunte Mini-Spielkonsole.
• Musikreaktives Spektrum: Zeige den mit einem Mikrofon gemessenen Pegel als farbige Säulen; Details im Beitrag Musikreaktive LED.
• Symbol-Badge: Wechsle auf dem 8x8-Panel per Taster zwischen Symbolen wie Smiley, Herz und Pfeil.
• Farbiges Thermometer: Zeichne einen Balken, der sich je nach mit dem DHT11 gemessenen Temperatur von Blau nach Rot füllt.
• Steuerung per Handy: Installiere WLED auf dem ESP32 und steuere das Panel per WLAN mit fertigen 2D-Effekten.
• Weihnachtsdeko: Ergänze dein Weihnachtsbaum-LED-Projekt mit Schneefall- und Sternanimationen auf einem Panel.

Häufige Fehler und Lösungen

Mit einem günstigen Panel bekommen deine Projekte mit der NeoPixel-Matrix ein buntes, bewegtes Display, und das macht richtig Spaß. Fang klein an: Bring zuerst das 8x8-Panel bei niedriger Helligkeit zum Laufen, bring die Funktion xyIndex zum Sitzen und geh dann zu Lauftext und 16x16-Animationen über. Wenn du nur einfarbigen Text und Zahlen anzeigen willst, ist die MAX7219-LED-Matrix eine Alternative mit geringerem Stromverbrauch. In der BlueGrays-App findest du WS2812B-Polizeiblitzer, Knight Rider und Animationsprojekte sowie Snake-Spiele für 8x8- und 16x16-Matrizen Schritt für Schritt mit Schaltplänen und Code.