Матрица NeoPixel на Arduino: руководство по панелям WS2812B 8x8 и 16x16

Матрица NeoPixel — один из самых эффектных дисплеев, которые можно собрать на Arduino. Она состоит из 8x8 (64 светодиода) или 16x16 (256 светодиодов) адресных RGB-светодиодов WS2812B, размещённых на панели, и цвет каждого пикселя задаётся отдельно по одному проводу данных. Она идеально подходит для бегущей строки, значков, небольших игр, индикаторов звукового спектра и декоративных анимаций. В этом руководстве ты шаг за шагом разберёшься с зигзагообразной раскладкой внутри панели, функцией, которая переводит координату x-y в номер светодиода, бегущей строкой и анимациями.

Работа с матрицей требует чуть больше внимания, чем одна лента NeoPixel. 256 светодиодов на полной яркости могут потреблять больше 15 ампер, 2 КБ ОЗУ Arduino Uno быстро заканчиваются на больших панелях, а выход 3,3 V у ESP32 и Pico на некоторых панелях может создавать проблемы. Поэтому, помимо кода, разберём расчёт тока, ограничение яркости и планирование памяти. Если основы WS2812B пока незнакомы, сначала загляни в статью о светодиодах WS2812B NeoPixel.

Что такое светодиодная матрица NeoPixel и как она работает?

Внутри каждого светодиода WS2812B, рядом с красным, зелёным и синим кристаллами, есть маленькая микросхема-драйвер. Микроконтроллер передаёт по линии данных на частоте 800 kHz по 24 бита цветовой информации на каждый светодиод; порядок битов — зелёный, красный, синий (GRB). Первый светодиод забирает себе первые 24 бита, а остальное передаёт следующему через пин DOUT, и так дальше по цепочке. Матричная панель работает так же: 64 или 256 светодиодов — это на самом деле одна длинная лента, сложенная в квадрат. Передача данных одному светодиоду занимает около 30 микросекунд, поэтому однократное обновление панели на 256 светодиодов занимает около 7,7 мс, а это плавная анимация с частотой больше 100 кадров в секунду.

Зигзагообразная раскладка пикселей и функция координат XY

В коде удобно думать о пикселе как о координате (x, y), но светодиоды адресуются одним порядковым номером, начиная с 0. Почти на всех гибких панелях и на моделях 16x16 светодиоды расположены зигзагом (змейкой, serpentine): первая строка идёт слева направо, вторая — справа налево, третья снова слева направо. Такая раскладка упрощает производство, потому что конец каждой строки соединяется с началом следующей кратчайшим путём. В таблице ниже показаны номера светодиодов в первых четырёх строках панели 8x8 с раскладкой зигзагом:

Формула получается сама собой: в чётных строках индекс = y × W + x, а в нечётных — индекс = y × W + (W − 1 − x), где W — ширина панели. Например, на панели 8x8 точка (2, 1) — это светодиод номер 1 × 8 + (7 − 2) = 13. Внимание: на некоторых платах 8x8 с жёсткой печатной платой все строки идут в одном направлении (прямая, или progressive, раскладка); тогда формула просто y × W + x. А на некоторых панелях светодиоды идут змейкой по столбцам, а не по строкам, то есть x и y нужно поменять местами. Самый надёжный способ узнать тип своей панели — запустить тестовый скетч, который зажигает светодиоды по одному, и посмотреть, как бежит свет.

Подключение матрицы NeoPixel: Arduino Uno, ESP32 и Pico

Для надёжной схемы добавь три небольшие детали: резистор 300–500 Ω последовательно в линию данных (защищает вход первого светодиода от выбросов напряжения), электролитический конденсатор около 1000 µF между 5V и GND панели (сглаживает бросок тока при первом включении источника) и, если нужно, преобразователь уровней на платах с логикой 3,3 V. При питании 5 V светодиоду WS2812B нужно видеть на входе данных минимум около 3,5 V (70% напряжения питания); выход 3,3 V у ESP32 и Pico работает с большинством панелей, но он ниже этой границы. Если появляется мерцание или случайные цвета, поставь буферную микросхему, например 74AHCT125; подробности — в статье о преобразователе логических уровней.

Первая программа для матрицы шаг за шагом (Arduino Uno)

1. Открой в Arduino IDE «Менеджер библиотек» (Library Manager) и установи библиотеку Adafruit NeoPixel.
2. Подключи панель по таблице: DIN — к D6 через резистор 330 Ω, GND — к GND Arduino, 5V — к источнику питания.
3. Задай в коде W и H по размеру своей панели; для панели 16x16 сделай оба значения равными 16.
4. В первый раз держи яркость низкой: setBrightness(30) снижает ток панели 8x8 до уровня, с которым справится USB.
5. Загрузи код: должна появиться радуга, бегущая по диагонали. Если цвета ломаются от строки к строке, у панели другая раскладка — поправь под неё функцию 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}

Сердце кода — функция xyIndex(): она переворачивает x в нечётных строках и тем самым скрывает зигзагообразную раскладку, так что в остальном коде можно думать только координатами. ColorHSV() переводит в RGB значение тона на цветовом круге от 0 до 65535; поскольку тон сдвигается с ростом суммы x + y, получаются диагональные цветные полосы. gamma32() вносит поправку на то, как глаз воспринимает яркость, и делает переходы цветов естественнее. И наконец, ни одно изменение не попадёт на панель, пока не вызвана show(): сначала записать все пиксели в память, а потом отправить их разом — вот секрет плавной картинки.

Бегущая строка с Adafruit NeoMatrix

Чтобы рисовать буквы и значки, не нужно возиться с каждым пикселем. Библиотека Adafruit NeoMatrix превращает панель NeoPixel в дисплей, совместимый с Adafruit GFX, поэтому функции, знакомые по OLED-дисплеям, — print(), drawLine(), fillRect() и drawBitmap() — работают и на матрице. Устанавливая Adafruit NeoMatrix через «Менеджер библиотек», поставь и зависимости Adafruit GFX и Adafruit NeoPixel. Флаги в конструкторе описывают физическую раскладку панели: NEO_MATRIX_TOP + NEO_MATRIX_LEFT означает, что первый светодиод в левом верхнем углу, NEO_MATRIX_ROWS — что светодиоды идут по строкам, а NEO_MATRIX_ZIGZAG — что строки идут зигзагом; на плате с прямой раскладкой достаточно написать NEO_MATRIX_PROGRESSIVE вместо ZIGZAG. Стандартный шрифт 5×7 идеально помещается на панель из 8 строк, а каждый символ вместе с промежутком занимает 6 пикселей в ширину. Текст из девяти букв занимает 54 пикселя; константа textWidth считает это автоматически, и когда x опускается ниже этого значения, текст снова въезжает справа и меняет цвет.

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}

Ограничение памяти на Arduino Uno

У ATmega328P в Arduino Uno всего 2048 байт ОЗУ, а каждому светодиоду нужен 3-байтовый буфер цвета. Панель 8x8 со своими 192 байтами помещается свободно, а 16x16 занимает 768 байт — больше трети ОЗУ в одиночку. Коварство вот в чём: Adafruit NeoPixel выделяет этот буфер во время работы программы, поэтому он не входит в использование памяти глобальными переменными, которое показывается в конце компиляции. Даже если компиляция сообщает о заполнении 70%, после добавления буфера панели память может закончиться; тогда плата зависает или появляются бессмысленные цвета. Кроме того, на платах AVR во время работы show() прерывания отключены; для 256 светодиодов это около 7,7 мс, за которые millis() может отстать, а данные, приходящие по Serial, — потеряться. Для больших панелей Arduino Mega с 8 КБ ОЗУ или ESP32 с сотнями килобайт — гораздо более удобный выбор.

Потребление тока и ограничение яркости

Каждый цветовой канал WS2812B на полной яркости потребляет около 20 mA; когда горят все три, то есть белый цвет, получается 60 mA на светодиод. Для грубой оценки подойдёт формула I ≈ число светодиодов × 60 mA × (яркость / 255). Панель 16x16 на полном белом потребляет 256 × 60 = 15 360 mA, то есть больше 15 A; это нагружает и блоки питания, и тонкие медные дорожки панели. Хорошая новость: матрица очень яркая, и в помещении яркости 20–50 из 255 уже хватает, чтобы картинка была чёткой и бросалась в глаза. В реальных анимациях не все светодиоды горят белым одновременно, поэтому средний ток заметно ниже расчётного, но источник всё равно нужно выбирать под худший случай или ограничивать ток программно.

Если на панели 16x16 подавать ток только с одного конца, светодиоды в дальнем углу получают просадку напряжения, и белый выглядит желтоватым или красноватым. Чтобы этого избежать, подавай 5V и GND и на входной, и на выходной конец панели проводами сечением не меньше 0,75 мм²; это называется подпиткой (power injection). Программно функция setMaxPowerInVoltsAndMilliamps(5, 2000) библиотеки FastLED в каждом кадре рассчитывает ожидаемый ток и автоматически снижает яркость, если предел будет превышен. При питании от батарей проверь, сколько продержится схема, с помощью калькулятора времени работы от батареи, а подробности о выборе источника — в статье о питании Arduino.

Анимация на матрице 16x16 с ESP32 (FastLED)

Благодаря большому объёму ОЗУ и процессору на 240 MHz ESP32 гораздо удобнее для больших панелей; сигнал NeoPixel она формирует аппаратным блоком RMT, поэтому процессор почти не загружается. Код ниже с помощью FastLED рисует на панели 16x16 две цветные точки, которые плавно скользят и оставляют след. beatsin8() выдаёт координату, которая со временем колеблется по синусоиде, а fadeToBlackBy() в каждом кадре слегка затемняет все пиксели, создавая эффект хвоста. Достаточно установить свежую версию FastLED через «Менеджер библиотек»; актуальные версии поддерживают и 2.x, и 3.x ядра ESP32 для Arduino.

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}

Матрица NeoPixel на Raspberry Pi Pico и MicroPython

В MicroPython для Pico модуль neopixel встроен, копировать дополнительные файлы не нужно. Модуль сам формирует временные интервалы сигнала, а тебе остаётся задать цвета через np[i] = (r, g, b) и отправить их на панель через write(). В MicroPython нет функции setBrightness, как в библиотеке Adafruit, поэтому яркость ограничивается вручную умножением значений цвета на коэффициент. Пример ниже медленно разжигает и гасит значок сердца на панели 8x8; значок рисуется из массива-битмапа, где каждая строка — один байт, а самый левый бит соответствует столбцу 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)

Идеи проектов с матрицей NeoPixel

• Табло с бегущей строкой: прокручивай на панели сообщения из интернета или время с помощью ESP32; для часов подойдёт метод из статьи о часах NTP на ESP32.
• «Змейка» и блочные игры: собери яркую мини-консоль из панели 16x16 и джойстика.
• Спектр под музыку: показывай уровень звука с микрофона цветными столбиками; подробности — в статье о светодиодах, реагирующих на музыку.
• Значок-бейдж: переключай кнопкой значки на панели 8x8 — смайлик, сердце, стрелку.
• Цветной термометр: нарисуй столбик, который заполняется от синего к красному в зависимости от температуры с датчика DHT11.
• Управление с телефона: установи на ESP32 WLED и управляй панелью по Wi-Fi с готовыми 2D-эффектами.
• Новогоднее украшение: добавь в проект светодиодной новогодней ёлки панель с анимацией снегопада и звёзд.

Частые ошибки и их решение

Матрица NeoPixel — самый весёлый способ дать проектам цветной подвижный дисплей на недорогой панели. Начни с малого: сначала запусти панель 8x8 на низкой яркости, добейся работы функции xyIndex, затем переходи к бегущей строке и анимациям на 16x16. Если нужно показывать только одноцветный текст и цифры, альтернатива с меньшим потреблением тока — светодиодная матрица MAX7219. В приложении BlueGrays можно шаг за шагом, со схемами подключения и кодом, изучить проекты полицейской мигалки, огней Knight Rider и анимаций на WS2812B, а также игры «Змейка» на матрицах 8x8 и 16x16.