Адресные светодиоды (WS2812B / SK6812)

💡 Адресные светодиоды (WS2812B / SK6812) на ESP32 — FastLED

Учебный проект про адресные LED-ленты: один и тот же провод данных управляет десятками независимых светодиодов, каждый из которых можно зажечь своим цветом. Проект показывает, как это работает “под капотом” (протокол, периферия RMT), и даёт готовый набор из 9 анимационных эффектов (радуга, дыхание, комета, твинкл и др.), которыми можно управлять прямо из Serial-консоли, не перепрошивая плату.

📋 Документация проекта

Архитектура кода

Один класс-драйвер на компонент, без обёрток из свободных функций поверх класса — стандартный паттерн для всех компонентов этого репозитория (см. COMPONENT_STANDARD.md):

├── include/
│   ├── LedEffects.h          # Класс-драйвер: 9 эффектов, машина состояний, isAlive()
│   ├── LedPhysicalLink.h     # Внутренний помощник: RGBW-упаковка (см. THEORY.md, раздел 7.3)
│   └── LedHardwareConfig.h   # ЕДИНАЯ точка настройки чипа, цвет. порядка и режима каналов (RGB/RGBW)
├── src/
│   ├── LedEffects.cpp        # Реализация эффектов (HSV, синусоиды времени, неблокирующие таймеры)
│   ├── LedPhysicalLink.cpp   # Упаковка кадра в 3 или 4 байта/пиксель перед FastLED.show()
│   └── main.cpp              # Точка входа: разбор команд из Serial + вызов LedEffects
├── platformio.ini            # Конфигурация окружения pioarduino
├── THEORY.md                 # Физика WS2812B/RMT, математика эффектов, архитектура класса
└── WIRING.md                 # Схема подключения встроенного диода и внешних лент

LedEffects — единственный публичный класс-драйвер: конструктор получает указатель на буфер CRGB и его длину (Dependency Injection — класс ничего не знает про конкретный GPIO/чип), а весь публичный API — это setEffect() + update() как обязательный минимум, плюс компактные сеттеры с разумными значениями по умолчанию (tickRainbow(speedMs = 20, ...) и т.д.). Именно поэтому отдельный упрощённый слой поверх класса не потребовался — main.cpp использует LedEffects напрямую, без фасада.

LedPhysicalLink — небольшой внутренний помощник (не альтернативный “слой API”, а часть реализации): решает исключительно задачу упаковки RGBW-кадра в 4 байта на пиксель для чипов с отдельным белым каналом (подробности — THEORY.md, раздел 7.3). В обычном 3-канальном (RGB) режиме это нулевые накладные расходы: sync() сразу выходит, физический и логический буферы — один и тот же указатель.

Вотчдог isAlive()

Это компонент-актуатор (прямой GPIO/RMT-выход), а не датчик — “обрыв провода” в классическом смысле неприменимо. strip.isAlive() отвечает на другой, педагогически более вероятный вопрос: вызывается ли update() достаточно регулярно. Если loop() где-то завис (например, на delay() или бесконечном цикле) — анимация молча застынет на одном кадре, а диагностика в консоли покажет !!! ЛЕНТА НЕ ОБНОВЛЯЕТСЯ !!! вместо ACTIVE (тот же принцип, что и в Components/2. LED_middle).

Минимальный пример использования

#include "LedEffects.h"
#include "LedHardwareConfig.h"

constexpr int LED_PIN = 5;
constexpr uint16_t NUM_LEDS = 60;

CRGB leds[NUM_LEDS];
LedEffects strip(leds, NUM_LEDS);   // autoShow = true по умолчанию — этого достаточно для одной ленты

void setup() {
    FastLED.addLeds<LED_CHIPSET, LED_PIN, LED_COLOR_ORDER>(leds, NUM_LEDS);
    strip.setEffect(LedEffects::Effect::RAINBOW);
}

void loop() {
    strip.update();   // ОДИН вызов в loop() — и вся анимация крутится сама
}

Тип чипа (WS2812B / SK6812 / …) и порядок цветов настраиваются один раз в LedHardwareConfig.h — в коде выше про них ничего не сказано. Если нужна RGBW-лента (4-й, белый канал) или несколько независимых лент одновременно — смотри разделы “Выбор типа светодиодов” и “Масштабирование на несколько лент” ниже — там показан полный LedPhysicalLink-вариант из main.cpp этого проекта.

Как менялась архитектура (для понимания читаемого кода)

⚙️ Конфигурация окружения (platformio.ini)

Использование форка pioarduino обязательно, так как оригинальная платформа espressif32 в PlatformIO не имеет полноценной поддержки Arduino Core 3.x. Зависимость проекта — fastled/FastLED @ ^3.9.0.

💡 Выбор типа светодиодов: чип, 3 или 4 канала, и почему не NeoPixel

Шаг 1 — какой у вас чип

Если лента не реагирует на код — скорее всего, дело не в проводах, а в том, что чип ленты не совпадает с тем, что зашит в коде (подробная физика — THEORY.md, раздел 7.1). Откройте include/LedHardwareConfig.h и поменяйте одну строку:

#define LED_CHIPSET SK6812   // было WS2812B — поменяйте на чип вашей ленты

Шаг 2 — 3 канала (RGB) или 4 канала (RGBW)

У SK6812 бывают обе версии: обычная (3 канала, как у WS2812B) и RGBW (4 канала — добавлен отдельный белый кристалл). Это тоже одна строка в том же файле:

#define LED_CHANNEL_MODE LED_MODE_RGBW   // или LED_MODE_RGB для 3-канальной ленты

Как понять, какая у вас лента: если после LED_MODE_RGB первые 1-2 диода работают нормально, а дальше по ленте цвета “съезжают”/смешиваются — это RGBW-лента, переключайтесь на LED_MODE_RGBW. Подробное объяснение симптома — THEORY.md, раздел 7.3.

В RGBW-режиме управление белым каналом — через команду white N в Serial-консоли (см. таблицу команд ниже) или напрямую stripLink.setAllWhite(255) в коде. Для RGB-ленты это безопасно, но ничего не делает — физического белого канала там просто нет.

⚠️ Если белый канал светится “не тем” цветом или цвета внутри RGBW перепутаны — поменяйте порядок байт LED_RGBW_BYTE_ORDER_* в том же файле (по умолчанию настроен самый частый вариант GRBW).

Шаг 3 — а не лучше ли использовать Adafruit_NeoPixel?

Закономерный вопрос: у Adafruit_NeoPixel RGBW поддерживается “из коробки” — Adafruit_NeoPixel(n, pin, NEO_GRBW + NEO_KHZ800) и setPixelColor(i, r, g, b, w), без описанного в THEORY.md трюка с переинтерпретацией буфера. Это честно проще, если вам нужна только RGBW-лента без анимаций. Мы тем не менее остаёмся на FastLED — вот честное сравнение:

Итог: если бы это был только “зажечь RGBW-ленту ровным светом” — NeoPixel был бы проще и короче. Но раз вся ценность проекта — в эффектах (радуга, дыхание, комета, твинкл, пульс и т.д.), переезд на NeoPixel означал бы выбросить готовую, проверенную математику FastLED и написать её самостоятельно. Подробный разбор — THEORY.md, раздел 7.4.

🐧 Настройка хост-системы Linux (при работе через Native USB)

Для работы с портом Native USB (/dev/ttyACM*) обычному пользователю требуются права на чтение и запись.

sudo usermod -a -G dialout,plugdev $USER

После этого необходимо перезагрузить компьютер (или хотя бы выйти и снова войти в графическую сессию), чтобы новые группы применились. Экстренный фикс без перезагрузки:

sudo chmod 666 /dev/ttyACM*

🚀 Как запустить

1. Подключите ленту по схеме из WIRING.md и плату — к компьютеру по USB.
2. Соберите, залейте прошивку и откройте монитор порта:

   pio run -t upload -t monitor
3. При старте лента на секунду вспыхивает сплошным белым (проверка, что все диоды подключены и чип задан верно), затем автоматически запускается эффект Rainbow.

🎛️ Управление эффектами без повторной прошивки

Во время работы можно переключать эффекты прямо в мониторе порта — наберите слово (или короткую букву) и нажмите Enter:

Если команда не распознана, прошивка явно ответит [CMD] Неизвестная команда: "..." — это удобный способ проверить, что Serial физически работает, даже если вы просто ошиблись в слове. Подробнее о том, почему построчный разбор надёжнее посимвольного — THEORY.md, раздел 9.2.

Раз в секунду в консоль выводится диагностическая строка:

Status: ACTIVE | Brightness: 255 | Free SRAM: 430124 bytes

Status берётся из strip.isAlive() — если вместо ACTIVE вы видите !!! ЛЕНТА НЕ ОБНОВЛЯЕТСЯ !!!, значит loop() где-то завис (см. раздел “Вотчдог isAlive()” выше).

🚨 Диагностика неисправностей

📈 Масштабирование на несколько лент

Класс LedEffects готов к одновременной работе с несколькими независимыми лентами:

CRGB ledsA[60];
CRGB ledsB[1];

// autoShow = false на ОБОИХ экземплярах — см. THEORY.md, раздел 6.3
LedEffects stripA(ledsA, 60, /*autoShow=*/false);
LedEffects stripB(ledsB, 1,  /*autoShow=*/false);

void loop() {
    stripA.update();
    stripB.update();
    FastLED.show(); // один общий вызов на весь кадр сразу для всех лент
}

Подробное объяснение того, почему именно так, а не иначе — THEORY.md, раздел 6.3 и 6.4.

RGBW-лента через LedPhysicalLink

Если лента RGBW (4 канала), используйте LedPhysicalLink — именно так устроен main.cpp этого проекта:

#include "LedEffects.h"
#include "LedPhysicalLink.h"

LedPhysicalLink stripLink(60, /*rgbw=*/true);
LedEffects strip(stripLink.logicalBuffer(), 60, /*autoShow=*/false);

void setup() {
    FastLED.addLeds<SK6812, 8, GRB>(stripLink.physicalBuffer(), stripLink.physicalSlotCount());
    strip.setEffect(LedEffects::Effect::RAINBOW);
}

void loop() {
    strip.update();
    stripLink.setAllWhite(128);           // независимое управление белым каналом
    stripLink.sync(strip.getBrightnessScale());
    FastLED.show();
}

LedEffects здесь, как и везде в проекте, работает только с обычным 3-канальным буфером и ничего не знает про White — RGBW-специфика целиком в LedPhysicalLink.

📝 Разбор используемых технологий

• FastLED (v3.9.0+): оптимизированная 8-битная математика цвета (HSV-пространство), целочисленные вычисления без float.
• Неблокирующие таймеры на полях объекта: в коде полностью исключена функция delay() в рабочих эффектах. Каждый экземпляр класса хранит собственные отметки времени, что делает диспетчеризацию задач по-настоящему независимой между несколькими лентами — подробности в THEORY.md.

Связанные материалы

• Резистор — токоограничение и расчёт мощности; для ленты особенно важен бюджет питания.
• Ambilight — проект на адресной ленте: подсветка, повторяющая цвета экрана.

Физика протокола WS2812B/RMT и архитектура класса LedEffects

Этот документ разбирает две вещи: как адресные светодиоды физически получают команды по одному проводу (протокол, периферия RMT), и какие архитектурные решения заложены в класс LedEffects — и почему именно такие.

1. ГЕНЕРАЦИЯ СИГНАЛОВ WS2812B ЧЕРЕЗ ПЕРИФЕРИЮ RMT

1.1 Наносекундный тайм-анализ протокола

• Шаг сетки частоты: на 1 бит требуется ровно 1.25 мкс.
• Бит 0: высокий уровень ≈400 нс, низкий ≈850 нс.
• Бит 1: высокий уровень ≈850 нс, низкий ≈400 нс.
• Цвет одного светодиода — строго 24 бита (8G + 8R + 8B), MSB first, порядок GRB.

Вся лента (хоть 1 диод, хоть 300) висит на ОДНОМ физическом проводе данных. Каждый светодиод в цепочке принимает первые 24 бита, “съедает” их себе и ретранслирует все следующие биты дальше по цепочке следующему диоду — так контроллер одним потоком бит управляет лентой любой длины.

1.2 Аппаратное решение: блок RMT

1. Макрос FASTLED_RMT_BUILTIN_DRIVER переключает движок FastLED на driver/rmt.h из состава ESP-IDF.
2. Каждое состояние сигнала описывается 32-битной структурой rmt_item32_t: [длительность высокого, длительность низкого].
3. После заполнения буфера на все 24 бита управление передаётся контроллеру DMA, который перекачивает данные в сдвиговый регистр GPIO без участия процессора — он в это время свободен обрабатывать USB-прерывания и Serial-вывод.

2. МАТЕМАТИКА ЦВЕТОВЫХ ЭФФЕКТОВ И FIXED-POINT ОПТИМИЗАЦИЯ

Вычисления с плавающей точкой дороги на большинстве микроконтроллеров без аппаратного FPU. FastLED обходит это через целочисленную математику с фиксированной запятой — знание этого объясняет, почему в коде эффектов нет ни одного float.

2.1 fill_rainbow и инкремент HSV

• _hue имеет тип uint8_t (диапазон 0..255). Операция _hue++ при достижении 255 автоматически сбрасывается в 0 за счёт аппаратного переполнения регистра — это эквивалент формулы H_new = (H_old + 1) mod 256.
• fill_rainbow строит градиент по формуле линейной интерполяции H[i] = hue + i * deltaHue целиком в целых числах; финальная конверсия HSV→RGB использует табличные значения.

2.2 beatsin8 (эффект “дыхания”)

Вместо вычисления синуса по ряду Тейлора FastLED использует Look-Up таблицу: системное время millis() переводится в фазовый угол 0..255, по которому из таблицы берётся готовое 8-битное значение синуса. Масштабирование под границы (10 и 255) выполняется делением, которое компилятор оптимизирует в сдвиг >> 8.

Важное уточнение: beatsin8() сам по себе не хранит состояния между вызовами — он считает фазу заново из millis() и bpm каждый раз. Это значит, что математика “дыхания” инстанс-безопасна сама по себе; проблема, разобранная в разделе 3.1, была не в ней, а в таймере, решающем когда выполнять следующий кадр.

2.3 fadeToBlackBy / nscale8

fadeToBlackBy(255 - brightness) и более общая операция nscale8(scale) реализуют умножение с насыщением:

В ассемблере это компилируется в умножение и сдвиг вправо на 8 бит — две инструкции, выполняемые за единицы тактов.

2.4 Корректность strobe на ленте произвольной длины

В исходной версии tickStrobe присваивал цвет только нулевому элементу массива (_leds[0] = ...). На одиночном диоде (numLeds == 1) это незаметно, но на реальной ленте из N светодиодов первый пиксель мигал бы, а остальные N-1 оставались “замороженными” с цветом предыдущего эффекта. В текущей версии используется fill_solid(_leds, _numLeds, color), заполняющий весь массив — теперь strobe одинаково корректно работает и на одном диоде, и на ленте любой длины.

3. АРХИТЕКТУРА КЛАССА LedEffects: ОТ ПРОТОТИПА К ПЕРЕИСПОЛЬЗУЕМОМУ ПАТТЕРНУ

Этот раздел объясняет, какую конкретно проблему решает архитектура класса, и почему она реальна, а не теоретическая придирка.

3.1 Почему EVERY_N_MILLISECONDS и static внутри метода класса — это ловушка

EVERY_N_MILLISECONDS(x) { ... } в FastLED разворачивается приблизительно в:

static CEveryNMillis timer; // <-- static-переменная привязана к МЕСТУ В КОДЕ
if (timer.ready(x)) { ... }

Ключевое слово здесь — место в коде (call site), а не объект. У static-переменной, объявленной внутри метода класса, ровно одна копия на всю программу — независимо от того, сколько экземпляров (LedEffects strip1(...), LedEffects strip2(...)) вызывают этот метод. Эта копия физически находится в той единственной строке исходного текста tickRainbow(), которая попадает в скомпилированный .cpp-файл один раз.

Что это значит на практике:

• tickStrobe() в исходной версии хранил static bool state — при двух экземплярах LedEffects (например, “лента A” + “лента B”, обе в режиме strobe) оба экземпляра переключали бы один и тот же булевый флаг. Видимый эффект: ленты мигали бы синхронно и в одной фазе, что само по себе может выглядеть “случайно правильным” — но стоит дать им разную скорость (speed), и логика начинает рассыпаться, потому что и сам таймер EVERY_N_MILLISECONDS внутри tickRainbow/tickStrobe — тоже один общий объект на двоих, и “последний вызвавший” перезатирает период для обоих.
• Для класса с заявленной целью “переиспользуемый на несколько независимых лент” и архитектурой Dependency Injection это прямое противоречие: DI обещает независимые объекты, а static внутри их методов тайно сшивает их состояние обратно в одну глобальную переменную.

Решение: каждый таймер (_lastRainbowMs, _lastBreathMs, _lastStrobeMs) и _strobeState — это private-поля объекта. У каждого экземпляра LedEffects своя физическая область памяти под эти поля, и поэтому их состояние никогда не пересекается между разными лентами.

Важная оговорка, чтобы не превращать находку в догму: EVERY_N_MILLISECONDS сам по себе не “плохой” макрос. Он отлично подходит для одиночных, не повторяющихся таймеров — например, в main.cpp для лога диагностики раз в секунду (там по определению только один loop() и одна точка вызова на всю программу). Проблема возникает конкретно тогда, когда макрос со static-состоянием помещается внутрь метода класса, который предполагается переиспользовать в нескольких экземплярах.

3.2 Безопасность к переполнению millis()

millis() возвращает uint32_t и переполняется примерно через 49 суток 17 часов непрерывной работы платы — не гипотетический сценарий для устройства, которое может работать неделями. Наивная проверка now - last >= interval остаётся корректной даже в момент переполнения благодаря тому, что вычитание двух uint32_t в C++ определено как операция по модулю 2^32: если now “перевернулся” и стал маленьким числом, а last — большим числом из “предыдущей эпохи”, разность всё равно равна фактически прошедшему времени. Явный static_cast<uint32_t> в _due() (и в isAlive()) зафиксирован в коде не для исправления ошибки (её здесь нет), а как документирующая аннотация для будущих читателей кода: “да, мы это учли осознанно”.

3.3 Почему FastLED.show() — глобальная операция, и что это значит для нескольких лент

FastLED.show() не привязан к конкретному экземпляру LedEffects или конкретному массиву CRGB — это статический метод фасада CFastLED, который проходит по всем контроллерам, зарегистрированным любыми предыдущими вызовами FastLED.addLeds<...>(...) за всё время работы программы, и отправляет в RMT-периферию буфер каждого из них.

Следствие: если у вас две ленты и оба экземпляра LedEffects вызывают FastLED.show() сами по себе (autoShow = true у обоих), то на каждый “тик” ленты А вы лишний раз пересылаете в физику и неизменный буфер ленты Б (и наоборот). Для одной-двух лент на коротких кадрах это обычно не заметно на глаз, но:

• удваивает нагрузку на шину RMT/DMA без пользы;
• при достаточно длинных лентах (сотни пикселей) суммарное время передачи может начать влиять на частоту кадров другого эффекта.

Решение: параметр конструктора autoShow. При autoShow = false каждый экземпляр только готовит свой кадр в _leds, а единственный вызов FastLED.show() остаётся в коде верхнего уровня (main.cpp), выполняясь один раз за итерацию loop() после того, как обновлены все экземпляры. Это классический паттерн “разделение модели и рендера” (update vs flush), знакомый из игровых движков, перенесённый на встраиваемую систему практически без изменений сути.

3.4 Программная яркость экземпляра (nscale8) vs FastLED.setBrightness()

FastLED.setBrightness() — тоже глобальная настройка фасада CFastLED: она задаёт единый множитель яркости, который автоматически применяется ко всем контроллерам в момент FastLED.show(). Это удобно как “общий аппаратный потолок” (например, ограничение тока питания на весь стенд), но не позволяет сделать одну ленту тусклее другой.

setBrightnessScale() решает это на уровне конкретного экземпляра: перед выводом кадра метод _applyBrightnessAndShow() умножает каждый пиксель именно этого _leds-массива на заданный коэффициент через nscale8() — целочисленную операцию (channel * scale) / 256, выполняемую программно прямо в RAM до того, как данные попадут в RMT. Оба механизма ортогональны и применяются последовательно: сначала глобальный потолок FastLED.setBrightness(), затем индивидуальная поправка nscale8() для конкретной ленты.

3.5 enum class Effect и update() как точка роста архитектуры

Введение enum class Effect { OFF, RAINBOW, BREATH, STROBE, ... } и единого диспетчера update() даёт практическое удобство: эффект переключается через односимвольную Serial-команду (r/b/s/0, см. README.md) без повторной прошивки платы. Архитектурно это также даёт “точку роста” без рефакторинга: добавление нового эффекта в будущем требует только (1) нового значения в enum class Effect, (2) нового tickXxx()-метода с собственным _lastXxxMs, и (3) одной строки case в update() — публичный интерфейс класса и весь существующий код в main.cpp при этом не меняются (принцип открытости/закрытости, Open/Closed Principle).

3.6 Вотчдог isAlive()

LedEffects — актуатор (прямой GPIO/RMT-выход), а не датчик: физического “обрыва провода”, который можно было бы обнаружить обратной связью, здесь нет. Вместо этого isAlive(timeoutMs = 500) отслеживает более вероятную для встраиваемого проекта ошибку — вызывается ли update() регулярно. Реализация — та же неблокирующая проверка на millis(), что и в _due() (раздел 3.2), только таймер _lastUpdateMs обновляется в самом начале update(), до любых return, чтобы засчитать сам факт вызова независимо от текущего эффекта. Если loop() где-то зависнет (например, на delay()), анимация молча застынет на одном кадре — без isAlive() это было бы незаметно; диагностика в main.cpp печатает эту метку каждую секунду.

4. SK6812 ВМЕСТО WS2812B: ПОЧЕМУ “ПРОСТО ПОМЕНЯТЬ NUM_LEDS” НЕ СРАБОТАЛО

4.1 Чип — это не настройка, а параметр шаблона C++

В вызове FastLED.addLeds<WS2812B, LED_PIN, GRB>(leds, NUM_LEDS) тип WS2812B — не строка и не число, а аргумент шаблона (template parameter). Компилятор на этапе сборки генерирует отдельную, специализированную под этот конкретный чип функцию вывода бит — с правильными длительностями высокого/низкого уровня именно для WS2812B (см. раздел 1.1: ~400/850 нс для бита 0, ~850/400 нс для бита 1).

У SK6812 эти длительности другие (обычно короче: порядок ~300/900 нс для нуля и ~600/600 нс для единицы — конкретные цифры зависят от партии и ревизии чипа у конкретного производителя). Если оставить шаблонный параметр WS2812B, а физически подключить SK6812, то компилятор честно генерирует корректный код для WS2812B — просто адресованный не тому чипу. Чип SK6812 получает фронты импульсов, которые не попадают в его собственные допуски, и либо игнорирует данные, либо считывает их с ошибками (мерцание, неверные цвета, иногда — полная “тишина”).

Решение: использовать шаблонный параметр SK6812 вместо WS2812B — у FastLED это готовая встроенная специализация с правильными таймингами. В проекте это сделано в одном месте — LED_CHIPSET в LedHardwareConfig.h — и оттуда подставляется как шаблонный аргумент в FastLED.addLeds<...>() внутри main.cpp. Сам класс LedEffects тут вообще ни при чём: он работает с готовым массивом CRGB и не знает (и не должен знать), какой физический чип стоит на ленте — это ответственность кода верхнего уровня, который вызывает FastLED.addLeds<...>().

4.2 Почему GPIO-пин тоже нельзя передать “просто переменной”

По той же причине, что и чип: FastLED.addLeds<CHIPSET, PIN, ORDER>(...) использует PIN как параметр шаблона, чтобы статически развернуть прямое обращение к регистру GPIO без накладных расходов на универсальный “цифровой ввод-вывод по номеру пина в рантайме”. Платой за эту скорость является то, что компилятору нужно знать номер пина заранее — поэтому в main.cpp это constexpr int LED_PIN, а не переменная, полученная, например, из Serial-команды или аргумента функции.

4.3 Вариант SK6812 RGBW (4 канала) — как это реализовано

Если лента — RGBW-вариант SK6812 (есть отдельный белый кристалл), драйвер на обычных 3-байтных пикселях CRGB неправильно считает длину кадра одного пиксела (24 бита вместо ожидаемых чипом 32), и каждый следующий пиксель “съедает” чужой байт у соседа — внешне это похоже на то, что цвета по ходу ленты постепенно съезжают/смешиваются, особенно заметно после первых 1-2 диодов.

Ключевая идея решения: FastLED.addLeds<...>() не имеет понятия “где кончается пиксель” — он просто отправляет в RMT все байты переданного ему массива CRGB подряд. Значит, если отдать ему массив, который в сумме содержит ровно numLeds * 4 байт, он честно передаст их все — не зная (и ему не нужно знать), что “на самом деле” это N четырёхбайтных RGBW-пикселей, а не N*4/3 трёхбайтных RGB.

Класс LedPhysicalLink (include/LedPhysicalLink.h) реализует это так:

1. Логический буфер (_logical, тип CRGB[numLeds]) — с ним работает LedEffects, как и раньше, без единого изменения в коде эффектов. Здесь живут только R, G, B — White в этот буфер никогда не попадает.

2. Буфер белого канала (_white, тип uint8_t[numLeds]) — отдельно хранит уровень белого для каждого диода, устанавливается через setWhite()/setAllWhite().

3. Физический буфер (_physical, тип CRGB[physicalSlots]) — именно он передаётся в FastLED.addLeds<...>(). Его размер в “слотах” по 3 байта считается как:

   $$\text{physicalSlots} = \left\lceil \frac{\text{numLeds} \times 4}{3} \right\rceil$$

   в коде — целочисленный трюк ceil(a/b) == (a + b - 1) / b, то есть (numLeds*4 + 2) / 3. Если numLeds*4 не делится на 3 нацело, в конце буфера остаётся 1-2 “лишних” байта — они просто никогда не перезаписываются содержательными данными и уходят в эфир уже ПОСЛЕ последнего настоящего пиксела ленты, ни на что физически не влияя.

4. sync(brightnessScale) — перед каждым FastLED.show() читает байты напрямую из _physical, адресуя его как обычный uint8_t* (через reinterpret_cast), и на каждый диод пишет подряд 4 байта: R, G, B (из _logical) и White (из _white, дополнительно умноженный на ту же программную яркость, что и у RGB-канала — scale8(white, brightnessScale), чтобы яркость менялась согласованно по всем 4 каналам).

В RGB-режиме (LED_MODE_RGB) ничего из этого не нужно: _physical — это просто тот же указатель, что и _logical (без копирования), а sync() сразу выходит (if (!_rgbw) return;) — нулевые накладные расходы.

4.4 Почему не Adafruit_NeoPixel

Закономерный вопрос: у Adafruit_NeoPixel RGBW поддерживается “из коробки” — Adafruit_NeoPixel(n, pin, NEO_GRBW + NEO_KHZ800) и setPixelColor(i, r, g, b, w) — без описанного выше трюка с переинтерпретацией буфера. Если задача — только зажечь RGBW-ленту ровным/статичным светом, NeoPixel и правда был бы проще: меньше кода, меньше концепций для понимания.

Причина остаться на FastLED для ЭТОГО проекта — соотношение того, что уже построено, и того, что пришлось бы выбросить:

• Весь класс LedEffects (все 9 эффектов) построен на готовой целочисленной математике FastLED: fill_rainbow (HSV-градиент), beatsin8 (синусоида из LUT), nscale8/scale8 (умножение с фиксированной запятой), fadeToBlackBy (экспоненциальное затухание), qadd8/qsub8 (насыщающая арифметика), random8/random16 (генератор случайных чисел). У Adafruit_NeoPixel ничего из этого нет «из коробки» — есть только setPixelColor()/fill(), остальное нужно было бы реализовывать вручную, по сути заново написав то, что в FastLED уже отлажено и оптимизировано.
• Переход на NeoPixel означал бы переписать все эффекты LedEffects под другой API пикселей — большой объём работы и риска регрессий, причём ради выигрыша только в ОДНОЙ конкретной задаче (RGBW), которая в FastLED решается один раз и инкапсулируется в LedPhysicalLink — компактный кусок кода, который остальной проект (включая LedEffects) вообще не видит.
• RMT-драйвер у обеих библиотек — собственный. FASTLED_RMT_BUILTIN_DRIVER у FastLED активно поддерживается под новые чипы Espressif (в том числе ESP32-C6). У Adafruit_NeoPixel RMT-интеграция исторически тоже работает, но в сообществе периодически всплывают отдельные сложности с совместным использованием RMT-канала другими библиотеками/периферией на одной плате — это не довод “против” NeoPixel в целом, просто ещё один пункт сравнения.

Итоговое правило выбора (не догма, а ориентир): если в проекте нужны только статичные RGBW-цвета без анимаций — NeoPixel короче и проще. Если нужны анимированные эффекты (как в этом проекте) — дешевле один раз реализовать RGBW-прослойку над FastLED (как LedPhysicalLink), чем переписывать всю эффектную математику под другую библиотеку.

5. МАТЕМАТИКА ЭФФЕКТОВ COMET / TWINKLE / PULSE

5.1 Comet — затухание по экспоненте, а не по прямой

fadeToBlackBy(fade) применяется к всем пикселям каждый кадр, поэтому яркость следа кометы убывает не линейно, а геометрически: после n кадров без обновления яркость канала равна

— это придаёт хвосту кометы характерный “резкий спереди, мягко тающий сзади” профиль, визуально похожий на реальное движение света с инерцией, хотя в коде нет ничего, кроме одного целочисленного умножения на кадр.

5.2 Twinkle — независимые испытания Бернулли

Проверка random8() < density на каждом кадре — это независимое испытание Бернулли с вероятностью успеха density / 256. Среднее число “звёзд”, зажигающихся за секунду, при частоте кадра 1000 / speedMs кадров в секунду равно:

Школьникам это можно объяснить без формулы: “на каждом кадре подбрасываем взвешенную монетку — чем больше density, тем чаще выпадает решка, и тогда загорается случайная звезда”.

5.3 Pulse — две точки, растущие в противоположные стороны от одной оси

В отличие от fill_rainbow (линейная развёртка от 0 до numLeds), Pulse держит две координаты, симметричные относительно _origin: left = origin - radius, right = origin + radius. Радиус растёт на единицу каждый кадр, обе точки одновременно отдаляются от центра — отсюда визуальный эффект “круги на воде” вместо “бегущей точки”. Волна автоматически перезапускается, когда radius превышает расстояние до дальнего края ленты — это гарантирует, что эффект одинаково красиво смотрится и когда _origin стоит точно в середине, и когда он смещён почти к самому краю (тогда одна “половина” волны угасает быстрее другой — это физически достоверно: в реальности круги на воде у берега тоже доходят до него быстрее, чем до противоположного берега).

6. НАДЁЖНЫЙ ПАРСЕР SERIAL-КОМАНД

6.1 Почему построчный разбор команд надёжнее посимвольного

В ранней версии проекта каждый введённый символ обрабатывался немедленно (case 'r':, case 'b': и т.д.). У этого подхода есть скрытая зависимость от того, как именно терминал отправляет байты на устройство. В platformio.ini этого проекта указан фильтр send_on_enter — он накапливает ввод локально в терминале и отправляет его на устройство только после нажатия Enter. Сам по себе это не ломает посимвольную обработку (отправленные байты, включая символ конца строки, всё равно по очереди попадают в Serial.read()), но создаёт почву для путаницы: до нажатия Enter создаётся впечатление, что “консоль не реагирует”, хотя на самом деле байты ещё не были физически отправлены.

В текущей версии ввод явно накапливается в строку до \n/\r (handleSerialInput()), а распознаётся и исполняется только целая команда (handleCommand()). Это даёт три практических преимущества:

• UX становится явным и предсказуемым: “наберите слово, нажмите Enter” — что ровно соответствует тому, как ведёт себя терминал с send_on_enter, вместо неявного ожидания мгновенной реакции на отдельный символ.
• Команды можно делать словами (“rainbow”, “pulse 12”), а не только однобуквенными кодами — это понятнее школьнику и проще для отладки.
• На любой нераспознанный ввод теперь печатается явное сообщение ([CMD] Неизвестная команда: ...) — раньше неизвестный символ просто тихо игнорировался в default:, и со стороны было невозможно отличить “Serial не работает” от “я нажал не ту кнопку”.

Схема подключения и аппаратная конфигурация (Wiring & Power Guide)

Этот документ описывает аппаратную коммутацию проекта с адресными светодиодами на базе платы ESP32-C6-DevKitC-1 v1, включая внутреннюю разводку встроенного RGB-светодиода и правила безопасного подключения внешней адресной LED-ленты.

1. Внутренняя трассировка платы (On-Board LED Wiring)

На официальной плате ESP32-C6-DevKitC-1 v1 адресный светодиод WS2812B (RGB, корпус 5050) уже распаян производителем и подключён к внутренним шинам по следующей схеме:

+----------------------------------+
|       ESP32-C6 Microcontroller   |
|                                  |
|   [GPIO8] ────────────────────┐  |
+-------------------------------│--+
                                │
                                ▼ (линия данных)
+----------------------------------+
|          WS2812B RGB LED         |
|                                  |
|   [DIN] ◄─────────────────────┘  |
|   [VDD] ◄──── +5V (от шины USB)  |
|   [GND] ◄──── GND (общая земля)  |
+----------------------------------+

Аппаратные параметры линии

• Пин управления: GPIO8 — выбран инженерами Espressif, так как этот пин поддерживает аппаратный вывод через периферию RMT/DMA.
• Линия питания ($V_{DD}$): подключена к силовой шине 5V после защитного диода Шоттки разъёма USB.
• Порядок следования цветов в потоке: GRB (Green, Red, Blue).

2. Схема подключения внешней адресной ленты (External LED Strip)

Так как класс LedEffects универсален, вы можете использовать тот же код для работы с длинными внешними лентами (WS2812B, WS2811, SK6812). Для этого выберите свободный GPIO (например, GPIO5) и выполните подключение по следующей схеме.

🚨 Критически важное правило

Никогда не питайте длинную LED-ленту (более 10–15 диодов) напрямую от пина 5V платы ESP32! Встроенный стабилизатор или диод Шоттки на плате сгорят от перегрузки по току. Используйте внешний блок питания 5В.

📐 Принципиальная схема подключения

+---------------------------+
|  Блок питания 5В (внешний) |
|                            |
|  (+5V) ─────────────────┐  |
|  (GND) ───────────┐     │  |
+-------------------│-----│--+
                    │     │
+-------------------│-----│---------+
|     ESP32-C6 DevKitC-1  │   │     |
|                      │      │     |
|  [GND] ◄─────────────┘      │     |
|                             │     |
|  [GPIO5] ──[ R: 330 Ом ]────┼──┐  │     |
+-----------------------------+  │  │     |
                                 ▼  ▼  ▼
                       +---------------------+
                       |    Адресная лента    |
                       |    (WS2812B / 5V)    |
                       |                       |
                       |  [DIN]  [GND]  [+5V] |
                       +---------------------+

Компоненты схемы

1. Токоограничительный резистор ($R = 330\ \text{Ом}$, допустимый диапазон 220–470 Ом). Ставится в разрыв сигнальной линии между пином GPIO5 и входом ленты DIN, максимально близко к самому GPIO на плате ESP32-C6, а не у начала ленты. Такое расположение защищает именно выходной каскад микроконтроллера от наводок и обратных импульсов из длинного соединительного кабеля — а это приоритетная задача для диагностического стенда, где плата дороже одного пикселя ленты. Резистор одновременно сглаживает фронты сигнала RMT и ограничивает бросок тока в первый светодиод при включении питания, так что отдельного второго резистора у самой ленты не требуется.
2. Общая земля (Common GND): земля (GND) внешнего блока питания обязательно должна быть физически соединена с землёй (GND) платы ESP32-C6. Без общего провода заземления сигнальный уровень GPIO5 относительно ленты будет хаотично “плавать”, и вместо эффектов лента будет хаотично мигать белым цветом.
3. Сглаживающий конденсатор ($C = 100\text{–}1000\ \text{мкФ},\ 6.3\text{В}+$): подключается параллельно линиям $+5\text{В}$ и $GND$ непосредственно у начала LED-ленты. Компенсирует резкие броски тока при одновременном зажигании множества светодиодов, предотвращая мерцание первого пикселя и срабатывание защиты Brownout на ESP32-C6.

3. Расчёт бюджета мощности (Power Budget)

• Один кристалл (Красный, Зелёный или Синий) на максимальной яркости потребляет ~20 мА.
• Чистый белый цвет (все три кристалла на яркость 255) одного светодиода потребляет ~60 мА.
• Встроенный светодиод платы: в коде установлено программное ограничение FastLED.setBrightness(30). При такой настройке ток диода не превышает 5–7 мА — безопасно для питания от любого USB-порта компьютера через Native USB.

Расчёт для внешней ленты (например, 100 диодов)

Для тестирования такой ленты потребуется внешний блок питания 5В мощностью не менее 30 Вт ($5\text{В} \times 6\text{А}$).

4. Проблема согласования логических уровней (3.3V vs 5V)

• Рабочее напряжение логики ядра ESP32-C6 — 3.3В. На выходе GPIO5 логическая единица равна 3.3В.
• Напряжение питания WS2812B — 5.0В. Минимальное напряжение для распознавания логической единицы на входе DIN:

Почему встроенный диод работает без сдвига уровней?

На плате DevKit трасса от процессора до диода — несколько миллиметров, а напряжение шины USB под нагрузкой обычно проседает до 4.7–4.8В. При таком падении $V_{IH\_min}$ опускается до ~3.3В, и сигналы ESP32-C6 распознаются стабильно.

Что делать, если внешняя лента “глючит”?

Если при подключении длинной ленты цвета искажаются или эффекты застывают, значит уровень 3.3В не дотягивает до порога ленты. В этом случае в разрыв сигнальной линии (вместо резистора) нужно установить маломощный быстродействующий преобразователь логических уровней (level shifter), например 74AHCT125 или 74HCT245, который поднимет сигнал GPIO5 с 3.3В до полноценных 5.0В.

5. Связь с программной частью

Резистор, общий GND и (при необходимости) level shifter из этого документа — необходимое, но не единственное условие стабильной работы. Корректность тайминга RMT и целостность буфера кадра на стороне кода обеспечивает класс LedEffects (см. README.md и THEORY.md, раздел 1 и 3): если аппаратная часть собрана по этой схеме, а лента всё равно мигает рывками или мерцает только частично — первым делом проверьте версию класса LedEffects (актуальная версия использует fill_solid() для всех светодиодов во всех эффектах, а не только для первого пикселя — см. THEORY.md, раздел 2.4).

Методический план урока: адресные светодиоды — один провод на сотню огней

Паспорт урока

Образовательные цели

По итогам урока ученик умеет:

Чего на этом уроке делать НЕ надо. Не разбирать наносекундные тайминги протокола и устройство RMT для всех — это уровень C и материал THEORY.md, раздел 1. Не углубляться в fixed-point математику FastLED. Урок держится на другом: ребёнок делает красиво и понимает, почему это работает.

Что должно быть готово заранее

• Внешний блок питания 5 В — это критично, см. блок про мощность
• Лента проверена лично: эффект rainbow запущен и работает
• Конденсатор и резистор установлены по WIRING.md
• Общая земля платы и блока питания соединена — самая частая ошибка
• Яркость в коде ограничена заранее (FastLED.setBrightness) — глаза и питание
• Если лента SK6812 RGBW — проверен LedHardwareConfig.h

Критично про питание. Лента на 60 диодов при полной яркости в белом цвете берёт до 3,6 А. Плата ESP32 через USB такого не даст никогда. Если запитать от платы — в лучшем случае перезагрузка, в худшем выгорит стабилизатор. Расчёт — в WIRING.md, раздел 3, и его надо провести с детьми, а не просто запретить.

Сценарий занятия (первые 45 минут)

Вторые 45 минут — практика по уровням и создание своего эффекта.

Ключевой методический принцип — протокол разыгрывается телами. Объяснение адресации словами не работает: дети кивают и не понимают. Живая инсценировка (см. блок 2) даёт модель, которую невозможно забыть, и занимает пять минут.

Блок 1. Завязка (0–7 мин)

Запустить ленту с эффектом rainbow до прихода детей. Пусть работает.

«Сколько здесь светодиодов? А теперь посчитайте провода, которые идут к ленте.»

Ответ: диодов — десятки, проводов — три (питание, земля, данные). И только один из них несёт информацию.

«Как по одному проводу передать разные команды сотне разных лампочек? Ведь если послать сигнал, его услышат все сразу.»

Это главный вопрос урока. Дать высказаться — гипотезы обычно интересные: «у каждого свой номер», «по очереди», «разными напряжениями».

Блок 2. Как работает адресация (7–15 мин)

Инсценировка (обязательно, 5 минут)

Вызвать 5–6 человек, поставить в цепочку. Правило каждого:

«Тебе передают стопку карточек. Первую берёшь себе — это твой цвет. Остальные передаёшь дальше по цепочке. Больше ничего не делаешь.»

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

Разбор:

«Кто-нибудь спрашивал, какой он по счёту? Нет. Адрес возникает из позиции в цепочке. Отсюда название — адресные светодиоды.»

2.1. Базовый уровень (13–14 лет)

Достаточно модели выше плюс один факт:

Каждая карточка — три числа: сколько красного, зелёного и синего. От 0 до 255. Три числа на диод, 60 диодов — 180 чисел, и всё это летит по одному проводу около тридцати раз в секунду.

2.2. Углублённый уровень (15–16 лет)

Добавить, откуда берётся скорость:

Каждый бит кодируется длительностью импульса, и допуск — десятки наносекунд. Обычный код на процессоре такой точности не даст: прервётся на Wi-Fi — и кадр испорчен. Поэтому сигнал формирует отдельный аппаратный блок RMT, а процессор только готовит данные.

Подробности — THEORY.md, раздел 1. Здесь важен вывод, а не тайминги: некоторые задачи процессору отдавать нельзя, для них есть специальная периферия.

Блок 3. Бюджет мощности (15–25 мин)

Этот блок обязателен — он про безопасность и про инженерное мышление.

Ведём расчёт вместе

«Один диод при полной яркости в белом цвете берёт около 60 мА. У нас лента из 60 диодов. Сколько это?»

«Плата по USB может отдать 0,5 А. Во сколько раз не хватает?»

В семь раз. Вывод дети формулируют сами: нужен отдельный источник.

Три следствия, которые стоит проговорить

Полезный приём. Спросить: «что дешевле — блок питания на 4 А или ограничить яркость до 30%?» Дети обычно выбирают второе и правы: на уроке 30% яркости достаточно, а глазам комфортнее.

Полная методика — WIRING.md, раздел 3.

Блок 4. Сборка и запуск (25–35 мин)

Порядок сборки — строго по WIRING.md. Три точки контроля педагога:

1. Общая земля. Земля платы и земля блока питания соединены. Без этого лента ведёт себя хаотично — самая частая и самая непонятная для детей неисправность.
2. Резистор в линии данных (330 Ом) — гасит отражения в проводе.
3. Конденсатор по питанию — сглаживает бросок тока при включении.

Типичные неисправности

Блок 5. Эффекты (35–45 мин)

Девять готовых эффектов управляются словами в Serial — перепрошивка не нужна: rainbow, breath, comet, twinkle, pulse 12, colorwipe, strobe и другие (точный список — в README.md).

Дать попробовать все. Затем разобрать устройство двух из них:

Радуга и модель HSV. Почему радуга в коде — это одна строка, а не таблица цветов?

В модели RGB радуга — сложная кривая: три числа меняются несогласованно. В модели HSV цвет задаётся одним числом — тоном по кругу (0–255). Радуга = «увеличивай тон по цепочке». Отсюда простота.

Это хороший момент показать: правильно выбранная модель превращает сложную задачу в простую. Математика эффектов — THEORY.md, раздел 2.

Комета и затухание. Почему хвост кометы выглядит естественно?

Затухание идёт не по прямой, а умножением на коэффициент каждый кадр — то есть по экспоненте. Так гаснет всё в природе: звук, свет, тепло. Линейное затухание глаз читает как «ненастоящее».

Практика по уровням (второй урок)

Уровень A (базовый)

1. Запустить каждый из девяти эффектов, записать в тетрадь, какой понравился и чем.
2. Изменить скорость радуги вдвое.
3. Ограничить яркость до 20% и объяснить, что произошло с потреблением.

Уровень B (средний)

4. Сделать «индикатор заполнения»: первые N диодов зелёные, остальные погашены, N задаётся командой из Serial.
5. Сделать светофор на трёх участках ленты с корректными таймингами.
6. Объяснить письменно, почему таймеры эффектов вынесены в поля объекта, а не сделаны статическими внутри метода. Материал: THEORY.md, раздел 3.1.

Уровень C (продвинутый)

7. Добавить свой эффект в enum class Effect и реализовать его в update(). Требование: неблокирующий, работает на ленте любой длины.
8. Реализовать «градиент между двумя заданными цветами» с плавным переходом.
9. Разобраться, почему strobe в старой версии красил только первый диод, и объяснить, как это связано с тестированием на ленте из одного светодиода. Материал: THEORY.md, раздел 2.4.

Ответы на вопросы, которые прозвучат

«Можно ленту на 300 диодов?» Технически да, но считайте питание: это до 18 А в худшем случае — серьёзный блок и толстые провода. И кадр из 900 чисел передаётся дольше, частота обновления упадёт.

«Почему лента иногда мигает при старте платы?» В момент включения пин данных ещё не настроен, лента ловит мусор. Нормально. Первый корректный кадр всё исправляет.

«А можно две ленты?» Да, но есть тонкость: FastLED.show() — глобальная операция для всех лент сразу. Поэтому в драйвере предусмотрен флаг autoShow. Разбор — THEORY.md, раздел 3.3.

«Что такое SK6812 RGBW?» Лента с четвёртым, отдельным белым кристаллом. Белый от неё чище, чем смесь трёх цветов, но кадр становится 4 байта на диод. Поддержка есть — THEORY.md, раздел 4.3.

«Диод сгорел — можно заменить один?» Можно выпаять и заменить, но если сгорела его микросхема, все диоды после него тоже погаснут — цепочка разорвана. Хороший повод обсудить надёжность последовательных систем.

Итог урока: что записать в журнал

1. Адрес диода — это его позиция в цепочке, а не номер в памяти.
2. Потребление считают до подключения: ток × количество, белый — худший случай.
3. Выбор цветовой модели (HSV вместо RGB) может упростить задачу в разы.

Проверка понимания (экспресс, 2 минуты)

Типичные затруднения

Домашнее задание

Обязательная часть: найти три устройства с адресной подсветкой (клавиатура, кулер, гирлянда, вывеска) и определить: сколько примерно диодов, какой эффект, как думаете — сколько там проводов данных.

Уровень A: нарисовать на клетчатой бумаге ленту из 10 диодов и раскрасить три кадра эффекта «бегущий огонь».

Уровень B: придумать полезный индикатор для реального применения (загрузка, уровень воды, время до события) и описать, какой эффект и какие цвета вы выберете и почему.

Уровень C: прочитать раздел 1 THEORY.md и письменно объяснить, что произойдёт с кадром, если процессор отвлечётся на 5 мкс посреди передачи — и почему RMT эту проблему снимает.

Связь с курсом

Этот урок завершает блок исполнительных устройств. Дети умеют управлять светом (простым и адресным) и звуком. Дальше курс переходит к датчикам — и связка «датчик → обработка → индикация» станет основой всех проектов.

Чек-лист педагога перед уроком

• Внешнее питание 5 В на каждый стенд, проверено под нагрузкой
• Общая земля соединена и подписана на схеме
• Яркость программно ограничена (30% достаточно)
• Карточки с цветами для инсценировки протокола нарезаны
• Расчёт мощности подготовлен под вашу длину ленты
• Проверены LED_CHIPSET и LED_COLOR_ORDER под ваш тип ленты
• Карточки заданий A / B / C распечатаны