ELECTRONICS

Библиотека Adafruit NeoPixel для лент WS2812B

Обновлено

В менеджере библиотек
Adafruit NeoPixel by Adafruit
Версия
1.15.5 · всего 65 версий, первая — 1.0.0
Платы
любые — автор не ограничивал
СкачатьAdafruit_NeoPixel-1.15.5.zip · 84 КБ

Архивы — копии из официального индекса Arduino, контрольная сумма совпадает. Сверено 19.10.2026.

Простая библиотека для лент WS2812B и SK6812: задать цвет пикселя, показать. Меньше возможностей, чем у FastLED, зато меньше памяти.

NeoPixel — торговое имя Adafruit для WS2812B, и библиотека под него одна из самых простых: цвет каждого пикселя задаётся вызовом, потом show(). Из готовых эффектов — только радуга, палитр нет, зато всё понятно с первого взгляда, и RGBW-ленты SK6812 с белым кристаллом работают из коробки.

Чем она отличается от FastLED по памяти и возможностям — замер ниже, в разделе «NeoPixel или FastLED».

Как скачать и установить

  1. Через менеджер — самый простой путь. В Arduino IDE: Инструменты → Управлять библиотеками (Ctrl+Shift+I). Введите Adafruit NeoPixel и найдите в списке строку «Adafruit NeoPixel by Adafruit» — одноимённых библиотек бывает несколько, отличаются они автором. Нажмите «Установить».
  2. Конкретная версия — если в чужом проекте указана не последняя. В той же карточке менеджера рядом с кнопкой есть выпадающий список версий: выберите нужную и нажмите «Установить».
  3. Из архива — если нет интернета на рабочем компьютере или менеджер не открывается. Скачайте ZIP выше, затем Скетч → Подключить библиотеку → Добавить .ZIP библиотеку и укажите файл. Распаковывать не нужно.

Файл Adafruit_NeoPixel.h отдельно не скачивают: он внутри библиотеки и появляется после установки. Если среда пишет Adafruit_NeoPixel.h: No such file or directory — библиотека не установлена или установлена не та. Как устроен менеджер и куда складываются файлы — в общей статье про библиотеки.

Строка подключения:

#include <Adafruit_NeoPixel.h>

Создание объекта — обычно до setup():

Adafruit_NeoPixel strip(30, 6, NEO_GRB + NEO_KHZ800);   // пикселей, вывод, тип
strip.begin();                                          // в setup()

Подключение ленты

Три провода: питание, земля и данные на вход DIN через резистор 330 Ом. Каждый пиксель берёт до 60 мА на белом во всю яркость, поэтому от платы питают только короткий отрезок, а длинный — от отдельного блока питания, соединив его землю с землёй Arduino. У NeoPixel нет ограничения мощности, как у FastLED: яркость приходится держать в уме самому.

Схема подключения адресной ленты WS2812B к Arduino UNO: пин 6 через резистор 330 Ом к DIN, 5 В к питанию ленты, GND к земле
Схема с пояснением к каждому проводу — на странице модуля «Лента WS2812B».
WS2812B, WS2813, кольца и модули NeoPixel
Третий параметр конструктора: NEO_GRB + NEO_KHZ800

Подходит почти всем лентам, кольцам и матрицам на 5 В: у кольца те же три провода, пиксели просто стоят по кругу.

SK6812 RGBW
Третий параметр конструктора: NEO_GRBW + NEO_KHZ800

Четыре кристалла, 4 байта на пиксель; белый задаётся четвёртым параметром. Тут NeoPixel удобнее FastLED.

WS2811
Третий параметр конструктора: NEO_RGB или NEO_BRG + NEO_KHZ800

Порядок цветов у лент на 12 В разный — подбирается по красному.

Старые модули WS2811 на 400 кГц
Третий параметр конструктора: NEO_RGB + NEO_KHZ400

Встречаются в старых гирляндах; современные ленты — 800 кГц.

Конденсатор на вход питания ленты

Электролит 1000 мкФ между плюсом и минусом ленты, у места, где приходит питание, — гасит бросок тока при включении.

ESP32 и ESP8266: сигнал 3,3 В

Лента на 5 В ждёт сигнал около 3,5 В и выше. С 3,3 В первый пиксель начинает мигать случайными цветами — нужен преобразователь уровня 74HCT125.

NeoPixel или FastLED

Обе библиотеки управляют одними и теми же лентами, различаются тем, сколько берут и что умеют. Мы собрали один и тот же эффект — радугу по всей ленте — на обеих для UNO. Отчёт среды у NeoPixel не меняется с длиной ленты: буфер она выделяет при запуске, и среда его не видит. Столбец «на самом деле» — отчёт плюс 3 байта на пиксель.

Сборка под UNOФлеш, байтОЗУ по отчёту средыОЗУ на самом деле
NeoPixel 1.15.5, 30 пикселей277041≈ 131
FastLED 3.10.7, 30 пикселей3666209209
NeoPixel 1.15.5, 300 пикселей278641≈ 941
FastLED 3.10.7, 300 пикселей367810191019

NeoPixel экономнее: примерно на 900 байт флеша и на 80 байт ОЗУ меньше. Умеет RGBW-ленты из коробки, а вывод данных задаётся переменной и меняется на ходу. Но яркость портит буфер, ограничения мощности нет, эффекты пишутся вручную.

FastLED тяжелее, зато в ней палитры, плавные переходы, шум, ограничение тока под блок питания и яркость, которая не трогает цвета. И среда честно предупреждает, когда лента не влезает в память. Подробно — на странице FastLED.

Скорость вывода в ленту у обеих одна и та же — её задаёт сам протокол WS2812B: около 30 мкс на пиксель, 300 пикселей — примерно 9 мс на кадр. Разница в скорости, которую находят в тестах, — это время на расчёт цветов в скетче, а не на show().

Зажечь десяток пикселей по кнопке или собрать индикатор — NeoPixel. Эффекты, длинная лента, питание на пределе — FastLED.

Методы

Только то, что нужно в обычном скетче. Сигнатуры сверены с версией 1.15.5.

Создание и запуск

Adafruit_NeoPixel(uint16_t n, int16_t pin = 6, neoPixelType type = NEO_GRB + NEO_KHZ800)

Создать ленту. Буфер под пиксели выделяется тут же, при запуске программы — поэтому среда при сборке его не видит.

n
сколько пикселей.
pin
вывод данных; в отличие от FastLED, может быть переменной.
type
порядок цветов плюс частота: NEO_GRB + NEO_KHZ800 почти для всех WS2812B, NEO_GRBW для SK6812 RGBW — таблица выше.
Adafruit_NeoPixel strip(30, 6, NEO_GRB + NEO_KHZ800);

bool begin()

Настроить вывод данных. Вызывают в setup() один раз.

Возвращает: true — готово; false — не задан вывод, а на RP2040 — не нашлось свободного блока PIO.

strip.begin();

uint16_t numPixels()

Сколько пикселей у ленты. Главная проверка памяти: если под буфер не хватило места, библиотека молча ставит длину 0.

Возвращает: число пикселей; 0 — память не выделилась.

if (strip.numPixels() == 0) Serial.println("Не хватило памяти");

void updateLength(uint16_t n)

Сменить длину ленты на ходу: старый буфер освобождается, выделяется новый. Сама Adafruit советует так не делать в новом коде — лучше сразу создать ленту нужной длины.

n
новое число пикселей.
strip.updateLength(60);

void setPin(int16_t p)

Сменить вывод данных на ходу — одной лентой по очереди управлять на разных выводах. FastLED так не умеет: у неё вывод задаётся при сборке.

strip.setPin(7);

Цвет пикселей

void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b)

Задать цвет пикселю в буфере. На ленте ничего не меняется до show().

n
номер пикселя с нуля; за пределами ленты вызов молча игнорируется.
r, g, b
компоненты 0–255.
strip.setPixelColor(0, 255, 0, 0);

void setPixelColor(uint16_t n, uint8_t r, uint8_t g, uint8_t b, uint8_t w)

То же для лент RGBW: четвёртый параметр — отдельный белый кристалл.

strip.setPixelColor(0, 0, 0, 0, 255);

void setPixelColor(uint16_t n, uint32_t c)

Задать цвет одним числом — из Color() или ColorHSV().

strip.setPixelColor(i, strip.Color(0, 120, 255));

uint32_t getPixelColor(uint16_t n)

Прочитать цвет пикселя из буфера. После setBrightness() вернётся уже ужатое значение, а не то, что записывали.

Возвращает: цвет одним числом; 0 — за пределами ленты.

uint32_t c = strip.getPixelColor(3);

void fill(uint32_t c = 0, uint16_t first = 0, uint16_t count = 0)

Залить участок одним цветом. Без аргументов — вся лента чёрным.

c
цвет.
first
с какого пикселя.
count
сколько; 0 — до конца ленты.
strip.fill(strip.Color(255, 0, 0), 0, 10);

void clear()

Все пиксели чёрные — в буфере; чтобы погасла лента, нужен show().

strip.clear();
strip.show();

void rainbow(uint16_t first_hue = 0, int8_t reps = 1, uint8_t saturation = 255, uint8_t brightness = 255, bool gammify = true)

Залить ленту радугой одним вызовом.

first_hue
оттенок первого пикселя, 0–65535. Меняйте со временем — радуга поползёт.
reps
сколько радуг уложить на ленту; отрицательное — в обратную сторону.
saturation, brightness
насыщенность и яркость 0–255.
gammify
true — с гамма-коррекцией, цвета ровнее.
strip.rainbow(0, 2);

void show()

Отправить буфер в ленту. На AVR, пока идёт передача, выключены прерывания — около 30 мкс на пиксель.

strip.show();

bool canShow()

Готова ли лента принять новый кадр прямо сейчас. Между кадрами лента требует паузу около 300 мкс, и show() сам её выжидает; эта проверка позволяет не ждать, а сделать за это время что-то ещё.

Возвращает: true — show() начнёт сразу; false — придётся подождать.

if (strip.canShow()) strip.show();

Яркость

void setBrightness(uint8_t b)

Общая яркость. В отличие от FastLED, пересчитывает сами значения в буфере — с потерями: если убавить и снова прибавить, цвета не вернутся. Ставят один раз в setup().

b
0–255; 0 — выключено.
strip.setBrightness(50);

uint8_t getBrightness()

Прочитать общую яркость.

Возвращает: 0–255.

Serial.println(strip.getBrightness());

Цвет из чисел

static uint32_t Color(uint8_t r, uint8_t g, uint8_t b)

Упаковать компоненты в одно число. Статическая: можно вызывать и без ленты, Adafruit_NeoPixel::Color(…).

Возвращает: цвет одним числом.

uint32_t orange = strip.Color(255, 80, 0);

static uint32_t Color(uint8_t r, uint8_t g, uint8_t b, uint8_t w)

То же с белым каналом — для лент RGBW.

uint32_t warm = strip.Color(60, 25, 0, 200);

static uint32_t ColorHSV(uint16_t hue, uint8_t sat = 255, uint8_t val = 255)

Цвет из оттенка, насыщенности и яркости.

hue
оттенок 0–65535 по кругу: 0 красный, 10923 жёлтый, 21845 зелёный, 32768 голубой, 43691 синий, 54613 фиолетовый.
sat
насыщенность: 255 — чистый цвет, 0 — белый.
val
яркость 0–255.

Возвращает: цвет одним числом.

strip.setPixelColor(i, strip.ColorHSV(43691));

static uint32_t gamma32(uint32_t x)

Гамма-коррекция цвета. Глаз видит яркость нелинейно, и без неё плавные переходы выглядят рваными, а середина — пересвеченной.

Возвращает: исправленный цвет.

strip.fill(strip.gamma32(strip.ColorHSV(hue)));

static uint8_t gamma8(uint8_t x)

То же для одного канала 0–255.

Возвращает: исправленное значение.

uint8_t v = strip.gamma8(128);

static uint8_t sine8(uint8_t x)

Быстрая синусоида из таблицы: полный период — 256 шагов. Для «дыхания» и пульсаций.

Возвращает: 0–255.

uint8_t level = strip.sine8(millis() / 8);

Примеры

Бегущая точка и проверка памяти

#include <Adafruit_NeoPixel.h>

#define PIN   6
#define COUNT 8
Adafruit_NeoPixel strip(COUNT, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  Serial.begin(9600);
  if (strip.numPixels() == 0) Serial.println("Не хватило памяти под ленту");
  strip.begin();
  strip.setBrightness(50);
  strip.show();                    // всё погасить на старте
}

void loop() {
  for (int i = 0; i < COUNT; i++) {
    strip.clear();
    strip.setPixelColor(i, strip.Color(0, 120, 255));
    strip.show();
    delay(80);
  }
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Точка бежит по ленте. Первая строка setup() проверяет, выделилась ли память под ленту, — среда об этом не предупредит.

Монитор порта:

(пусто — память выделилась)\n\nПри нехватке:\nНе хватило памяти под ленту

Радуга одной строкой

#include <Adafruit_NeoPixel.h>

#define PIN   6
#define COUNT 30
Adafruit_NeoPixel strip(COUNT, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  strip.begin();
  strip.setBrightness(50);
}

void loop() {
  // оттенок первого пикселя растёт со временем — радуга ползёт;
  // 65536 — полный круг оттенков у ColorHSV
  strip.rainbow((millis() * 20) & 0xFFFF);
  strip.show();
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Вся лента — радуга, и она ползёт: rainbow() получает оттенок первого пикселя, который растёт со временем. Гамма-коррекция включена по умолчанию.

Шкала с потенциометра

#include <Adafruit_NeoPixel.h>

#define PIN   6
#define COUNT 10
Adafruit_NeoPixel strip(COUNT, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  strip.begin();
  strip.setBrightness(50);
}

void loop() {
  // потенциометр на A0: чем больше повернули, тем больше горит
  int lit = map(analogRead(A0), 0, 1023, 0, COUNT);
  strip.clear();
  for (int i = 0; i < lit; i++) {
    // от зелёного через жёлтый к красному: оттенок 21845 → 0
    uint16_t hue = 21845 - (uint32_t)21845 * i / (COUNT - 1);
    strip.setPixelColor(i, strip.ColorHSV(hue));
  }
  strip.show();
  delay(20);
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Индикатор уровня: крутите потенциометр на A0 — загорается больше пикселей, от зелёного к красному. Подходит для громкости, заряда, температуры — поменяйте только источник числа.

Дыхание с плавной сменой цвета

#include <Adafruit_NeoPixel.h>

#define PIN   6
#define COUNT 12
Adafruit_NeoPixel strip(COUNT, PIN, NEO_GRB + NEO_KHZ800);

void setup() {
  strip.begin();
}

void loop() {
  // «дыхание»: яркость по синусоиде, цвет медленно плывёт по кругу
  uint8_t level = Adafruit_NeoPixel::sine8(millis() / 8);
  uint16_t hue = millis() * 4;
  // gamma32 исправляет восприятие: без неё середина кажется слишком яркой
  uint32_t color = Adafruit_NeoPixel::gamma32(Adafruit_NeoPixel::ColorHSV(hue, 255, level));
  strip.fill(color);
  strip.show();
  delay(10);
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Вся лента плавно вдыхает и выдыхает, медленно меняя цвет. Без gamma32() на глаз кажется, что лента долго горит ярко и резко гаснет — коррекция делает переход ровным.

Белый канал ленты RGBW

#include <Adafruit_NeoPixel.h>

#define PIN   6
#define COUNT 30
// лента SK6812 RGBW: четыре кристалла в пикселе, тип NEO_GRBW
Adafruit_NeoPixel strip(COUNT, PIN, NEO_GRBW + NEO_KHZ800);

void setup() {
  strip.begin();
  strip.setBrightness(80);
}

void loop() {
  // настоящий белый — отдельным кристаллом: ровнее и экономнее, чем R+G+B
  strip.fill(strip.Color(0, 0, 0, 255));
  strip.show();
  delay(2000);
  // тёплый свет: белый кристалл плюс немного красного и зелёного
  strip.fill(strip.Color(60, 25, 0, 200));
  strip.show();
  delay(2000);
}
Запустить в симулятореСхема с этим скетчем — запустить в браузере

Лента SK6812 RGBW попеременно горит чистым белым и тёплым. Белый кристалл светит ровнее и тратит меньше тока, чем красный, зелёный и синий вместе. В буфере такая лента занимает 4 байта на пиксель.

На чём попадаются

Adafruit_NeoPixel.h: No such file or directory

Библиотека не установлена. В менеджере нужна строка «Adafruit NeoPixel by Adafruit»; из ZIP — Скетч → Подключить библиотеку → Добавить .ZIP.

Среда пишет, что памяти хватает, а лента не горит

Буфер ленты выделяется при запуске, и в отчёте среды его нет: там всегда несколько десятков байт, сколько бы пикселей ни было. Если память кончилась, библиотека молча ставит длину 0. Считайте сами — к отчёту среды прибавьте 3 байта на пиксель (4 для RGBW), и проверяйте strip.numPixels() == 0 в setup(). Кому тесно, есть статическая версия от Spence Konde: буфер объявляется в скетче, среда его видит, а флеша уходит на 600–700 байт меньше.

Ничего не горит

Забыли begin() или show(). Второе — самое частое: setPixelColor() меняет только буфер.

Цвета не те

Не тот порядок в третьем параметре конструктора: NEO_GRB, NEO_RGB, NEO_BRG. Залейте ленту красным и подберите.

setBrightness портит цвета

Она необратимо ужимает значения в буфере. Ставьте один раз в setup(), а для плавной яркости меняйте сами цвета — например, третьим параметром ColorHSV().

Скетч теряет данные из Serial

Пока идёт show(), на AVR выключены прерывания — около 30 мкс на пиксель. Входящие байты за это время теряются, а millis() отстаёт.

Где используется на сайте

Что дальше