FastLED: установка библиотеки и первый скетч

Лента лежала на столе, провода были прикручены, а в меню Скетч → Подключить библиотеку я листал пустоватый список, где не было ни FastLED, ни NeoPixel. Первый раз я поступил логично и бездарно одновременно: загуглил «скачать FastLED», вытащил архив с GitHub, распаковал — и IDE не увидела его, потому что папка распаковалась с хвостом -master, а Arduino ищет по имени без суффиксов. Полчаса переименований, перезапусков и чтения форумов. Мораль та поездка дала простую: ручная установка — запасной выход, а штатная дорога занимает два клика.

«Установка библиотеки» звучит как самая скучная часть пути, но именно здесь решаются три будущие беды: от выбранной версии зависит, какие функции будут доступны; от момента с порядком каналов — какого цвета будет ваш «красный»; а от свободной памяти платы — сколько пикселей вы вообще себе позволите. Поэтому пройдём этот шаг не по диагонали.

Этот урок — про путь от чистой IDE до мигающего пикселя. Поставим библиотеку штатно и через запасной путь, соберём минимальный скетч из пяти смысловых строк, разберём на нём модель «буфер — show» и закончим чек-листом диагностики на самый частый случай новичка: скетч залился, плата жива, лента молчит.

Штатный путь. В Arduino IDE откройте Скетч → Подключить библиотеку → Управлять библиотеками (или Ctrl+Shift+I), в поиске наберите FastLED и нажмите Установить — менеджер подтянет последнюю версию вместе с примерами, которые после установки лежат в Файл → Примеры → FastLED. Библиотека общая для всех плат: если у вас и Uno, и Nano, ставится один раз. Мы уже прогоняли этот механизм в уроке про менеджер библиотек — там же про версии и обновления. Если поиск в менеджере не находит ничего по запросу «fastled arduino», набирайте ровно FastLED: фильтр чувствителен к лишним словам. Для PlatformIO установка — одна строка lib_deps = fastled/FastLED в platformio.ini. Версия показывается в менеджере рядом с кнопкой Установить: если чей-то скетч из интернета не заводится, первым делом сравните свою с минимальной из документации к нему.

Вместе с библиотекой ставится пакет примеров — не пропускайте их, но и не копируйте вслепую. Файл → Примеры → FastLED → DemoReel100 — это витрина из десятка эффектов, собранная вокруг того же кадрового каркаса на millis(), который мы разбирали в уроке про эффекты. Прежде чем запускать чужой пример, всегда проверяйте в нём три строки: пин данных, число пикселей и порядок каналов — примеры пишутся под конкретную макетку автора, и лента у него может быть другой длины. Первая компиляция после установки идёт заметно дольше обычного: библиотека большая, компилятор переваривает её шаблоны под ваш чип; это нормально, дальше не повторяется. На классических платах с ATmega328 — Uno и Nano — памяти хватает на сотни пикселей: буфер в 300 байт из двух килобайт ОЗУ ещё оставляет запас под остальной скетч.

Запасной путь, если менеджеру не хватает интернета: Скетч → Подключить библиотеку → Добавить .ZIP-библиотеку — и выбираете скачанный архив целиком, распаковывать не нужно. Если идёте через ручную распаковку, запомните два условия: папка должна лежать в Документы/Arduino/libraries и называться ровно FastLED, без -master и -main, а внутри неё обязан быть файл FastLED.h. Компилятор ищет заголовок по имени папки — любой суффикс ломает поиск, это и был мой получасовой тупик. Этот же маршрут работает и на Linux, и на macOS: папка libraries лежит в скетчбуке пользователя, а не в системных каталогах IDE — искать её нужно в Документах.

Разберём построчно. Строка #include подключает библиотеку — в Arduino IDE она обязательна, симулятор на этой странице знает FastLED без неё. CRGB leds[16] — буфер: шестнадцать ячеек в памяти, по одной на пиксель, и пока вы не вызвали show(), лента о ваших планах не знает. FastLED.addLeds — паспорт подключения: чип WS2812B, данные на пине 6, порядок каналов GRB, буфер — наш массив, пикселей 16. Модель буфера удобнее всего понимать как черновик: leds[] — лист, на котором вы рисуете кадр хоть по частям, хоть вразнобой, а show() — момент, когда черновик отправляется на стену. Из этого следует приятное: между записями и show() можно делать любую арифметику — массив не дёргает ленту ни при каком количестве правок.

Внутри угловых скобок живут не только чип и пин. Третий аргумент — порядок каналов: GRB для большинства WS2812B, RGB для части клонов, BRG для редких партий — ровно тот рычаг, который спасает от «зелёного красного». Список чипов в шаблоне шире, чем кажется: WS2811 для лент, где чип вынесен наружу, SK6812 с белым четвёртым каналом, APA102 с отдельной линией тактов — у них паспорт пишется так же, меняется имя чипа и, у тактовых, добавляется второй пин. Один вызов addLeds описывает одну ленту; для двух секций на разных пинах таких вызовов два — но на Uno обычно хватает одной.

FastLED.setBrightness(90) — глобальная крутилка яркости от 0 до 255. Моё правило на время сборки: 60–120, не выше. Отладочный скетч часто заливает ленту белым на все пиксели, а белый на максимуме — это ампер тока с ленты на 16 пикселей и слепящие глаз вертикали. Уберёте мощность за 255, когда проект собран, ток посчитан и питание проверено — темой следующего урока. Дальше по loop(): запись цвета в нулевую ячейку буфера, show() — единственный момент, когда биты уходят в провод, пауза полсекунды, гашение, снова show(). По механике это то же мигание из урока про первый светодиод, только вместо digitalWrite — запись цвета и выталкивание кадра.

Залить всю ленту целиком — первое настоящее упражнение: цикл for из урока про циклы перебирает индексы от 0 до 15 и красит каждую ячейку буфера, а один show() в конце выталкивает готовый кадр. Обратите внимание на порядок: сначала все записи, потом один show — а не show внутри каждой итерации. Внутри цикла show отрабатывал бы шестнадцать раз за кадр, растянул передачу вшестнадцать раз и заставил бы ленту «дозревать» по пикселю, как старый телевизор с плохой антенной.

Моя вторая лента не завелась надолго и по глупой причине. Я подключил данные к пину 13 — рассуждал так: на нём же висит встроенный светодиод L, значит, пин «заведён» и виден в прошивке. Скетч залился, IDE отчиталась об успехе, а лента молчала. Перепроверил всё, кроме единственной строки с LED_PIN, — она честно говорила про пин 6, к которому ничего не было прикручено. Пин 13 для ленты в принципе плохой выбор: параллельно с линией данных висит светодиод платы, и на высоких скоростях он портит фронт импульса. Сменил define на 6 — заработало с первой загрузки. Отсюда привычка: чужой скетч-пример читайте глазами по трём константам — пин, число пикселей, порядок каналов, — прежде чем заливать на плату: минута чтения экономит вечер непонимания.

С тех пор диагностика молчащей ленты занимает у меня пять минут, потому что причина почти всегда в одном из пяти пунктов. Пройдите их по порядку, сверху вниз: они отсортированы по частоте, и первые два закрывают большинство случаев.

Мой обязательный тест перед всякой диагностикой — «один пиксель»: короткий скетч, который красит leds[0] красным и вызывает show() раз в секунду. Ток минимальный, переменных почти нет, и всё внимание уходит на провода. Кстати, мигающий светодиод L при заливке прошивки — это бутлоадер, а не общение с лентой: он мигает при каждой загрузке и ничего не говорит о том, дошла ли прошивка по делу. Учитесь отделять эти сигналы друг от друга — половина паники «скетч не залился» снимается простым фактом, что L мигает всегда, независимо от результата.

Библиотека стоит, первый пиксель мигает, диагностика в кармане. Ритуал первого запуска у меня теперь всегда один и тот же: шестнадцать пикселей, setBrightness(60), залив чистым красным — если красный горит красным, порядок каналов угадан и можно идти дальше. Осталась силовая часть, из-за которой ленты и горят, и мерцают: где брать пять вольт, зачем резистор 330 Ом у входа данных и что гасит конденсатор 1000 мкФ. Если заливка красным упёрлась в зелёный — вернитесь к порядку каналов: одна буква в угловых скобках решает больше, чем полчаса с мультиметром. А если хочется уже красить красиво — HSV-цвета из урока про палитры никуда не денутся, они ждут вас сразу после питания.