LedMatrix

Прошивка для светодиодной матрицы на базе WS2812B/WS2811 и микроконтроллеров ESP8266 или ESP32. Поддержка множества визуальных режимов, управление кнопкой, ИК-пультом, автомод и сохранение настроек.

Возможности

• 31 визуальный режим в прошивке (огонь, дождь, конфетти, змейка, спираль, кольца и др.; id 1–31, 0 — ошибка)
• Переключение режимов кнопкой или ИК-пультом
• Автоматическая смена режима по таймеру (опционально)
• Сохранение текущего режима и списка в файл (LittleFS) или статический список
• Ограничение потребления по току (опционально)
• Поддержка разных типов матриц (зигзаг/параллельная), угла подключения и направления ленты

Поддерживаемые платы

Окружение	Плата	Платформа
esp12e	ESP8266 ESP-12E	espressif8266
esp32dev	ESP32 Dev Module	espressif32

Сборка и загрузка

Проект собирается через PlatformIO.

# Сборка для ESP32
pio run -e esp32dev

# Сборка для ESP8266
pio run -e esp12e

# Загрузка прошивки (ESP32)
pio run -e esp32dev -t upload

# Загрузка файловой системы (настройки)
pio run -e esp32dev -t uploadfs

Прошивки:
.pio/build/esp32dev/firmware.bin и .pio/build/esp12e/firmware.bin.

Подробнее — в .cursor/rules/build.mdc.

Настройка

Основные параметры задаются в **src/configs/matrix.h**:

• LEDS_WIDTH, LEDS_HEIGHT — размер матрицы (по умолчанию 16×16)
• LEDS_PIN — пин данных ленты (ESP32: 22, ESP8266: D2)
• LEDS_BRIGHTNRSS — яркость 0–255
• LEDS_COLOR_ORDER — порядок цветов (GRB/RGB и т.д.)
• LEDS_MATRIX_TYPE, LEDS_CONNECTION_ANGLE, LEDS_STRIP_DIRECTION — тип матрицы и подключение
• BTN_PIN — пин кнопки
• BTN_ENABLE, IR_ENABLE, RELAY_ENABLE — включение кнопки, ИК, реле
• SAVE_TO_EEPROM — true для сохранения в файл (LittleFS), false — только статический список режимов
• AUTOMOD_INTERVAL, AUTOMOD_DEF_STATE — интервал и состояние автомода

Режимы (эффекты)

№	Режим	Описание (кратко)
1	SlowRandom	Медленная смена случайных цветов
2	SimpleRainbow	Радужная заливка
3	Dribs	Капли
4	Rain	Дождь
5	AllRandom	Случайные пиксели
6	Snow	Снег
7	Fire	Огонь
8	TheMatrix	Матрица (зелёный код)
9	SimpleBalls	Шарики со следами
10	Confetti	Конфетти
11	Starfall	Падающие звёзды
12	DynamicSquare	Динамический квадрат
13	RandomRain	Случайный дождь
14	RainbowRain	Радужный дождь
15	Points	Движущиеся точки
16	RainbowPoint	Радужная точка
17	RainbowStaticPoint	Статичная радужная точка
18	TextMode	Текст
19	Mouse	Указатель мыши
20	Pacman	Пакман
21	CircularPoint	Круговая точка
22	ZigZag	Зигзаг
23	HorizontalRainbowPoint	Горизонтальная радужная точка
24	Ny2020	Новогодний
25	DribsAllSide	Капли со всех сторон
26	Snake	Змейка
27	RadialFire	Радиальный огонь
28	RadialPattern	Радиальный узор
29	CrazyBees	Пчёлы
30	Spiral	Спираль
31	PulseRings	Импульсные кольца

Сохранение эффектов в память

Режимы работы

В src/configs/matrix.h задаётся флаг SAVE_TO_EEPROM:

Значение	Хранилище	Поведение
true	FileEffectStorage	Список режимов и текущий индекс хранятся в файле на LittleFS. После перезагрузки восстанавливаются последний выбранный режим и порядок режимов.
false	StaticEffectStorage	Список фиксированный (зашит в коде), текущий режим не сохраняется — после перезагрузки всегда стартует с последнего в списке.

При SAVE_TO_EEPROM = true используется файл с именем из SAVE_TO_EEPROM_FILE (по умолчанию "mods.txt"). Файл создаётся в корне LittleFS (путь /mods.txt).

Что сохраняется (при сохранении в файл)

• Текущий индекс — номер режима в списке (0, 1, 2, …), который сейчас показывается.
• Список эффектов — последовательность записей вида «id эффекта + служебный savedIndex». Порядок записей = порядок переключения кнопкой «вперёд/назад».

Запись в файл происходит при смене режима (текущий индекс) и при изменении списка (добавление/удаление эффектов через API хранилища). Формат бинарный (см. EffectInfo::serialize в src/core/effect/EffectInfo.h).

Первый запуск с сохранением в файл

1. Соберите прошивку с SAVE_TO_EEPROM = true.
2. Один раз загрузите файловую систему (раздел LittleFS):
   pio run -e esp32dev -t uploadfs
   (для ESP8266 — pio run -e esp12e -t uploadfs).
3. При первом запуске файла mods.txt нет или он пустой — тогда автоматически создаётся список по умолчанию из DefaultEffects::effectIds в src/configs/DefaultEffectList.h (см. раздел ниже), и текущий режим ставится в 0.

Сброс списка к «заводскому»

При использовании FileEffectStorage сброс к списку по умолчанию выполняется вызовом reset() у хранилища: список очищается и снова заполняется из того же списка по умолчанию — массива DefaultEffects::effectIds в src/configs/DefaultEffectList.h. Текущий индекс становится 0. В прошивке вызов reset() нужно добавить в код (например, по длинному удержанию кнопки или отдельной команде), если такая функция нужна.

Как менять список режимов

Единственное место, где задаётся порядок и набор эффектов по умолчанию (при старте и после сброса): src/configs/DefaultEffectList.h — массив DefaultEffects::effectIds (элементы типа EffectId::…).

Что сделать	Как
Добавить режим в список	Вставить строку EffectId::ИмяРежима, (имя варианта из enum class EffectId в src/core/effect/EffectFactory.h). Номера из таблицы режимов в README — это те же значения id.
Убрать режим	Удалить или закомментировать соответствующую строку.
Поменять порядок	Переставить строки в массиве: сверху вниз = порядок переключения кнопкой «вперёд».
Повторить режим в списке	Добавить тот же EffectId::… ещё раз — режим будет встречаться несколько раз при переключении.
Размер массива не задаётся вручную: компилятор выводит его из числа элементов в { … }.

Этот список используется и при SAVE_TO_EEPROM = false (StaticEffectStorage), и при SAVE_TO_EEPROM = true при первом запуске, пустом файле и после reset() (FileEffectStorage): дублировать настройку в других файлах не нужно.

После правок пересоберите прошивку (pio run …) и при необходимости загрузите её; при использовании LittleFS, если нужно заново применить «заводской» список на уже прошивавшемся устройстве, сотрите файл настроек или вызовите reset() в коде (если он у вас подключён).

После изменения пересоберите прошивку и загрузите её.

Список по умолчанию при сохранении в файл

При SAVE_TO_EEPROM = true при первом запуске (или после сброса через reset()) список берётся из того же StaticEffectStorage::createDefaultEffectsList(): создаётся временный StaticEffectStorage, и его список копируется в файл. Поэтому правки в StaticEffectStorage.h в методе createDefaultEffectsList() влияют и на «стартовый» список при работе с файлом.

Итого: чтобы изменить начальный набор и порядок режимов (и при статике, и при сохранении в файл), редактируйте createDefaultEffectsList() в StaticEffectStorage.h: добавляйте/удаляйте/переставляйте вызовы internalAddEffect(id) по нужным id (1–31).

Структура проекта

LedMatrix/
├── platformio.ini           # Конфигурация PlatformIO
├── src/
│   ├── main.cpp            # Точка входа, setup/loop
│   ├── myapplication.*     # Приложение: кнопка, ИК, автомод, менеджер эффектов
│   ├── configs/
│   │   ├── matrix.h             # Настройки матрицы и пинов
│   │   ├── DefaultEffectList.h  # Список режимов по умолчанию (порядок и набор)
│   │   └── constants.h          # Константы, index_t
│   ├── core/
│   │   ├── effect/         # EffectManager, EffectFactory, хранилища
│   │   ├── file/           # Работа с файлами (LSF)
│   │   └── ...
│   ├── effects/
│   │   ├── effect.h        # Базовый класс Effect
│   │   └── effects_impl/   # Реализации режимов (*.h, при необходимости *.cpp)
│   ├── controls/           # Кнопка, ИК, автомод
│   ├── events/             # События, наблюдатель
│   ├── libs/               # LedMatrix, отладка, диапазоны
│   └── modules/            # Реле и др.
└── .cursor/rules/          # Правила сборки и создания эффектов

Добавление нового режима

1. Создать класс, наследующий Effect, в src/effects/effects_impl/<имя>.h.
2. Реализовать минимум on_update(); в on_init() при необходимости вызвать set_fps().
3. В EffectFactory.h: добавить новый вариант в enum class EffectId перед Count (следующий свободный номер).
4. В EffectFactory.cpp: #include заголовка эффекта и строка EFFECT_CASE(ИмяКакВEnum); (имя класса должно совпадать с именем в enum).
5. В DefaultEffectList.h: при необходимости добавить EffectId::… в DefaultEffects::effectIds, чтобы режим попал в стартовый список.

Подробная инструкция — в .cursor/rules/effects.mdc.

Зависимости

• FastLED — работа с лентой
• GyverButton — обработка кнопки
• IRremote — ИК-приём (опционально)
• Vector — список эффектов
• EspSoftwareSerial — только для ESP32 (если используется)