rbdimmerESP32 - Профессиональная библиотека управления AC регулятором яркости для ESP32

v2.0.0 Критические изменения: Внутренняя структура исходного кода изменена на модули src/internal/. Примеры перестроены на отдельные каталоги скетчей (Arduino IDE 2.x). Kconfig.txt переименован в Kconfig. Публичный API не изменился — изменения кода пользователя не требуются.

Профессиональная, высокопроизводительная библиотека управления AC регулятором яркости для микроконтроллеров ESP32. Разработана для точного управления синхронизацией, высокой эффективности оборудования, многофазной и многоканальной работы с поддержкой различных типов нагрузок, включая лампы накаливания, LED-диммеры и приложения управления двигателями.

Основные возможности

Оптимизация оборудования

Hardware Timer Integration: Uses ESP32's high-resolution timers for microsecond precision
Архитектура, управляемая прерываниями: Минимальные накладные расходы CPU с аппаратной обработкой прерываний
Поддержка многофазности: До 4 независимых AC фаз с индивидуальным обнаружением перехода через нуль
Автоматическое определение частоты: Поддержка 50 Гц и 60 Гц сети с автоматическим определением
Размещение IRAM_ATTR ISR: Все критичные по времени пути находятся в IRAM для детерминированной задержки
Диспетчеризация ESP_TIMER_ISR: Обратные вызовы таймера запускаются из контекста ISR для минимального дрожания
Фильтр помех zero-cross: Аппаратно проверенный фильтр подавления помех исключает ложные срабатывания от выбросов коммутации TRIAC

Расширенное управление

Несколько кривых яркости: Линейная, RMS-компенсированная и логарифмическая кривые для различных типов нагрузок
Плавные переходы: Неблокирующие переходы яркости с использованием задач FreeRTOS
Многоканальная работа: Одновременное управление до 8 независимых каналов регулятора яркости
Синхронизация в реальном времени: Работа, заблокированная по фазе с частотой сети

Профессиональные функции

Комплексная обработка ошибок: Подробные коды ошибок и диагностическая информация
Потокобезопасный дизайн: Полная совместимость с FreeRTOS с надлежащим управлением ресурсами
Обширная документация: Полная документация Doxygen с примерами
Кроссплатформенная поддержка: Работает с Arduino IDE и ESP-IDF

Модульная архитектура

v2.0.0 заменяет монолитную реализацию в одном файле на шесть внутренних модулей:

Модуль	Ответственность
`rbdimmer_zerocross`	GPIO ISR zero-cross, измерение частоты, фильтр помех
`rbdimmer_channel`	Состояние канала, диспетчеризация ZC по фазе, двухпроходная ISR
`rbdimmer_timer`	Обертки create/start/stop для esp_timer
`rbdimmer_curves`	Преобразование уровня → задержка (LINEAR, RMS, LOG)
`rbdimmer_transition`	Плавное переходное затухание на основе задач FreeRTOS
`rbdimmer_types`	Общие структуры и перечисления
`rbdimmer_hal`	Прокладка GPIO/timer HAL для портативности Arduino/ESP-IDF

Примечание: API публичного заголовка (rbdimmerESP32.h) не изменился — код пользователя не требует модификации.

Быстрый старт

Установка в Arduino IDE

Загрузите библиотеку с GitHub
В Arduino IDE: Sketch → Include Library → Add .ZIP Library
Выберите загруженный ZIP-файл
Включите в свой скетч:

cpp

#include

Пример базового использования

cpp

#include 
rbdimmer_channel_t* dimmer_channel;
void setup() {
    Serial.begin(115200);
    // Initialize the library
    rbdimmer_init();
    // Register zero-crossing detector on pin 2, phase 0, auto-detect frequency
    rbdimmer_register_zero_cross(2, 0, 0);
    // Configure dimmer channel
    rbdimmer_config_t config = {
        .gpio_pin = 4,              // Dimmer output pin
        .phase = 0,                 // Use phase 0
        .initial_level = 0,         // Start at 0% brightness
        .curve_type = RBDIMMER_CURVE_RMS  // RMS-compensated curve
    };
    // Create the channel
    rbdimmer_create_channel(&config, &dimmer_channel);
    Serial.println("RBDimmer initialized successfully");
}
void loop() {
    // Fade from 0% to 100% over 3 seconds
    rbdimmer_set_level_transition(dimmer_channel, 100, 3000);
    delay(4000);
    // Fade from 100% to 0% over 2 seconds
    rbdimmer_set_level_transition(dimmer_channel, 0, 2000);
    delay(3000);
}

Требования к оборудованию

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

ESP32 DevKit: Все варианты (ESP32-WROOM-32, ESP32-WROVER и т.д.)
ESP32-S2: Однопроцессорный вариант ESP32 с USB OTG
ESP32-S3: Двухпроцессорный с улучшенными возможностями AI и USB
ESP32-C3: На основе RISC-V, ультранизкое энергопотребление
ESP32-C6: Поддержка Wi-Fi 6 с 802.11ax
ESP32-H2: Предназначен для приложений Thread/Zigbee
ESP32-P4: Высокопроизводительный вариант с улучшенной обработкой
ESP32-C2: Оптимизированный по стоимости с базовой подключаемостью
Совместимые платы третьих сторон: Wemos D1 Mini ESP32, NodeMCU-32S и т.д.

Матрица совместимости фреймворков

Чип ESP32	Arduino Core	ESP-IDF	ESPHome
ESP32	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-S2	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-S3	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-C3	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-C6	✅ 3.x	✅ 5.3+	⏳ Скоро
ESP32-H2	✅ 3.x	✅ 5.3+	✅ 2024.x+
ESP32-P4	⏳ Скоро	✅ 5.3+	⏳ Скоро
ESP32-C2	✅ 3.x	✅ 5.3+	⚠️ Ограничено

Оборудование регулятора яркости

Эта библиотека предназначена для работы с готовыми модулями регуляторов яркости, которые включают: - Схему обнаружения перехода через нуль - Драйвер TRIAC или твердотельное реле - Оптическую изоляцию для безопасности - Надлежащее охлаждение

⚠️ Предупреждение о безопасности: Напряжение сети переменного тока опасно. Используйте только сертифицированные модули регуляторов яркости с надлежащей изоляцией.

Пример подключения

plaintext

ESP32 Pin 2  ←→  Zero-Cross Detector Output
ESP32 Pin 4  ←→  TRIAC Gate Control Input
ESP32 GND    ←→  Dimmer Module GND (isolated side)
ESP32 3.3V   ←→  Dimmer Module VCC (if required)

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

Документ	Описание
API Reference	Полная документация API
Hardware Guide	Схемы подключения и безопасность
Troubleshooting	Типичные проблемы и решения
Примеры	Все примеры скетчей объяснены
Changelog	История версий

Специфичные для платформы руководства

Руководство Arduino: Установка Arduino Framework и примеры
Руководство ESP-IDF: Установка ESP-IDF Framework и примеры
Обзор полной библиотеки: Полная документация

Расширенные функции

Несколько кривых яркости

Выберите оптимальную кривую для вашего типа нагрузки и желаемого визуального ответа:

cpp

// For incandescent bulbs (smooth, power-linear dimming)
rbdimmer_set_curve(channel, RBDIMMER_CURVE_RMS);
// For LED loads (perceptually linear brightness)
rbdimmer_set_curve(channel, RBDIMMER_CURVE_LOGARITHMIC);
// For motor control (linear power control)
rbdimmer_set_curve(channel, RBDIMMER_CURVE_LINEAR);

Подробные характеристики кривых:

Линейная (RBDIMMER_CURVE_LINEAR) - Равномерное изменение задержки угла фазы - Прямое преобразование процента в задержку - Подходит для управления двигателем и простых приложений - ⚠️ Примечание: Воспринимаемая яркость не является визуально линейной
RMS (RBDIMMER_CURVE_RMS) - Компенсирует характеристики RMS синусоидального переменного тока - Обеспечивает линейное изменение мощности: Power ∝ Level² - Идеален для ламп накаливания и резистивных нагрузок - На основе: angle = arccos(√(level/100))
Логарифмическая (RBDIMMER_CURVE_LOGARITHMIC) - Компенсирует логарифмическое восприятие яркости - Обеспечивает визуально линейные изменения яркости - Рекомендуется для LED освещения и дисплеев - На основе: log₁₀(1 + 9×(level/100))

Оптимизация производительности

Использование аппаратного таймера

ESP-Timer Integration: Uses ESP32's high-resolution software timers
Точность микросекунд: Точность синхронизации ±1-10 мкс при нормальной нагрузке
Эффективность ресурсов: 2 таймера на канал (задержка + ширина импульса)
Размещение в IRAM: Критичный код ISR размещен в IRAM для скорости

Оптимизация прерываний

cpp

// Zero-cross interrupt characteristics
static void IRAM_ATTR zero_cross_isr_handler(void* arg) {
    // Minimal code in ISR context
    // Uses pre-calculated lookup tables
    // Defers heavy processing to main tasks
}

Оптимизация памяти

Предварительно рассчитанные таблицы: Кривые яркости рассчитываются при инициализации
Эффективное кэширование: Параметры кэшируются для снижения повторных вычислений
Минимальное использование ОЗУ: ~200 байт на канал + ~1 КБ глобальных накладных расходов
Оптимизация флэш-памяти: ~32 КБ общего объема флэш-памяти

Система отладки и логирования

Включите подробное логирование для разработки и решения проблем:

cpp

// Enable detailed logging
#define RBDIMMER_DEBUG_LOG 1
// Check system performance
void monitor_performance() {
    Serial.printf("Free heap: %d bytes\n", ESP.getFreeHeap());
    Serial.printf("CPU frequency: %d MHz\n", ESP.getCpuFreqMHz());
    Serial.printf("Zero-cross frequency: %d Hz\n", rbdimmer_get_frequency(0));
    // Monitor timing accuracy
    uint32_t delay_us = rbdimmer_get_delay(channel);
    Serial.printf("Current delay: %d μs\n", delay_us);
}

Управление несколькими каналами

cpp

rbdimmer_channel_t* channels[4];
// Create multiple channels on different phases
for(int i = 0; i < 4; i++) {
    rbdimmer_register_zero_cross(zc_pins[i], i, 0);
    rbdimmer_config_t config = {
        .gpio_pin = dimmer_pins[i],
        .phase = i,
        .initial_level = 0,
        .curve_type = RBDIMMER_CURVE_RMS
    };
    rbdimmer_create_channel(&config, &channels[i]);
}

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

cpp

void zero_cross_callback(void* user_data) {
    // Called on every zero-crossing - perfect for synchronization
    static uint32_t cross_count = 0;
    cross_count++;
    // Implement custom effects, measurements, etc.
    if(cross_count % 100 == 0) {
        Serial.printf("Frequency: %d Hz\n", rbdimmer_get_frequency(0));
    }
}
// Register the callback
rbdimmer_set_callback(0, zero_cross_callback, NULL);

Параметры Kconfig

Четыре настраиваемых параметра для сборок ESP-IDF (Arduino использует значения по умолчанию при компиляции):

Параметр	По умолчанию	Описание
`CONFIG_RBDIMMER_ZC_DEBOUNCE_US`	3000 мкс	Окно фильтра помех после действительного края ZC
`CONFIG_RBDIMMER_MIN_DELAY_US`	100 мкс	Минимальная задержка ZC→TRIAC
`CONFIG_RBDIMMER_LEVEL_MIN`	3 %	Уровни ниже этого → ВЫКЛ
`CONFIG_RBDIMMER_LEVEL_MAX`	99 %	Уровни выше этого → ограничены

Сценарии использования

Автоматизация дома

Управление умным освещением с плавным затемнением
Интеграция с платформами IoT (Home Assistant, OpenHAB)
Голосовое управление и приложения для смартфонов
Мониторинг энергии и оптимизация

Коммерческие приложения

Освещение сцены и театра
Освещение ресторана и гостеприимства
Освещение розничных дисплеев
Управление промышленными процессами

Образовательные проекты

Демонстрации силовой электроники
Эксперименты с управлением фазой AC
Обучение системам реального времени
Образование в области встроенного программирования

Проекты мейкеров

Контроллеры пользовательских ламп
Эффекты освещения на Хэллоуин/Рождество
Освещение синхронизированное с музыкой
Управление вентилятором на основе температуры

Типичные проблемы и быстрые решения

Общее мерцание или нестабильная яркость

Возможные причины: - Неправильное подключение нейтрали/линии переменного тока - Проблемы с сигналом детектора перехода через нуль - Выбросы коммутации TRIAC повторно запускают обнаружение ZC - Высокая нагрузка CPU или конфликты прерываний

Быстрые исправления: - Фильтр помех zero-cross v2.0.0 (ZC_DEBOUNCE_US = 3000 мкс) автоматически отфильтровывает повторные запуски выбросов TRIAC - Попробуйте другую кривую для вашего типа нагрузки:

cpp

rbdimmer_set_curve(channel, RBDIMMER_CURVE_RMS);    // For incandescent
rbdimmer_set_curve(channel, RBDIMMER_CURVE_LOGARITHMIC); // For LEDs
// Check zero-crossing detection
uint16_t freq = rbdimmer_get_frequency(0);
if (freq == 0) {
    Serial.println("Zero-crossing not detected - check wiring");
}

Мерцание на 100% яркости

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

Исправление в v2.0.0: MIN_DELAY_US увеличен с 50 до 100 мкс. Уровни на или выше 100% отображаются на LEVEL_MAX (99%), предотвращая сбои при полном включении.

Дрейф синхронизации многоканальной системы

Причина: Каналы активируются в немного разные моменты времени в течение одного события ZC.

Исправление в v2.0.0: Двухпроходная ISR — проход 1 сбрасывает все GPIO, проход 2 активирует все таймеры. Это гарантирует, что все каналы начинают с одной и той же базовой линии при каждом переходе через нуль.

Мерцание ниже 3% яркости

Причина: TRIAC не может надежно защелкиваться при очень малых углах проводимости.

Исправление в v2.0.0: Уровни ниже LEVEL_MIN (3%) рассматриваются как ВЫКЛ, исключая непредсказуемое мерцание в нижней части диапазона затемнения.

Проблемы яркости, специфичные для нагрузки

При 50% уровне лампа выглядит слишком яркой/тусклой:

cpp

// Test different curves to find optimal response
rbdimmer_curve_t curves[] = {RBDIMMER_CURVE_LINEAR,
                            RBDIMMER_CURVE_RMS,
                            RBDIMMER_CURVE_LOGARITHMIC};
for(int i = 0; i < 3; i++) {
    rbdimmer_set_curve(channel, curves[i]);
    rbdimmer_set_level(channel, 50);
    delay(3000); // Observe result
}

Отсутствие ответа регулятора яркости

Проверьте обнаружение перехода через нуль:

cpp

void diagnose_zero_cross() {
    if (rbdimmer_get_frequency(0) == 0) {
        Serial.println("Zero-cross signal not detected");
        Serial.println("Check: Pin connection, dimmer power, signal quality");
    }
}

Матрица сборки CI

Автоматизированная CI гарантирует чистую сборку каждой коммиты на всех поддерживаемых платформах:

Arduino: arduino/compile-sketches@v1, Core 3.x, 4 примера × 5 чипов (ESP32, S2, S3, C3, C6)
ESP-IDF: espressif/esp-idf-ci-action@v1, IDF v5.3/v5.4/v5.5 × 5 чипов = 15 заданий
test_app/: Минимальный проект ESP-IDF для проверки поверхности API при компиляции

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

Фреймворк Arduino

Arduino IDE 2.x
Бесшовная интеграция с библиотеками Arduino

Фреймворк ESP-IDF

ESP-IDF 5.3+ с поддержкой CMake
Функции профессиональной разработки

Инструменты разработки

Visual Studio Code с расширением ESP-IDF
CLion с плагином ESP-IDF
Eclipse CDT с инструментами ESP-IDF
Поддержка разработки из командной строки

Характеристики производительности

Функция	Спецификация	Примечания
Точность синхронизации	±1-10 микросекунд	Зависит от нагрузки системы
Макс. каналов	8 одновременно	2 таймера на канал
Макс. фаз	4 независимо	Ограничено GPIO и памятью
Диапазон частот	45-65 Гц автодетект	Основная поддержка 50/60 Гц
Время ответа	< 20 мс (один цикл AC)	Следующий переход через нуль
Накладные расходы CPU	< 1% (управляется прерываниями)	Оптимизированная IRAM ISR
Использование памяти	~8 КБ ОЗУ, ~32 КБ флэш	Масштабируется с каналами
Разрешение таймера	1 микросекунда	На основе ESP-Timer
Допуск дрожания	±10-50 мкс при нагрузке	Зависит от FreeRTOS

Преимущества архитектуры ESP-Timer

Программная реализация: Позволяет множество одновременных таймеров
Выполнение на основе очереди: Упорядочено по времени запуска для эффективности
Низкие накладные расходы: Один аппаратный таймер обслуживает все программные таймеры
Диспетчеризация ISR: Обратные вызовы таймера запускаются прямо из контекста ISR для минимального дрожания

Ограничения производительности

Дрожание таймера: ±10-50 мкс возможны при высокой системной нагрузке
Ограничения обратного вызова: Не должны блокировать выполнение в течение длительных периодов
Масштабирование памяти: Каждый канал требует ~200 байт ОЗУ
Ограничения GPIO: Доступные контакты варьируются в зависимости от варианта ESP32

Сравнение библиотек

Функция	rbdimmerESP32	Другие библиотеки
Аппаратные таймеры	✅ Встроенные таймеры ESP32	❌ Программные задержки
Многофазность	✅ До 4 фаз	❌ Только одна фаза
Определение частоты	✅ Автоматическое	❌ Ручная настройка
Типы кривых	✅ 3 встроенных + пользовательские	❌ Только линейная
Безопасность потоков	✅ Совместима с FreeRTOS	❌ Базовая реализация
Обработка ошибок	✅ Комплексная	❌ Ограниченная
Документация	✅ Профессиональные доки	❌ Базовые примеры

Вклад

Мы приветствуем вклад из сообщества! Пожалуйста, прочитайте нашу Руководство участника для:

Рекомендаций по стилю кода
Процедур тестирования
Процесса запроса на вытягивание
Шаблонов отчетов о проблемах
Установки среды разработки

Примеры

Пример	Платформа	Описание	Сложность
BasicDimmer	Arduino	Простое включение/выключение затемнения	Начинающий
BasicTransition	Arduino	Плавные переходы яркости	Начинающий
MultiDimmer	Arduino	Управление несколькими каналами	Средний
ZCCallBack	Arduino	Обратные вызовы перехода через нуль	Продвинутый
BasicDimmer.c	ESP-IDF	Управление затемнением на основе C	Средний
MultiDimmer.c	ESP-IDF	Многоканальное управление с C	Продвинутый
ZCCallBack.c	ESP-IDF	Продвинутая обработка прерываний	Эксперт
ESPHome Basic	ESPHome	Установка конфигурации YAML	Начинающий
ESPHome Advanced	ESPHome	Многоканальная конфигурация YAML	Средний

Поддержка и сообщество

Официальные ресурсы

Веб-сайт: https://rbdimmer.com
Документация: https://www.rbdimmer.com/docs/universal-library-for-esp32
Каталог оборудования: https://www.rbdimmer.com/dimmers-pricing
Галерея проектов: https://www.rbdimmer.com/blog/integration-guides-8

Поддержка сообщества

Форум: https://forum.rbdimmer.com
GitHub Issues: Сообщить об ошибках и запросить функции
GitHub Discussions: Обсуждения сообщества и вопросы-ответы

Профессиональная поддержка

Для коммерческих приложений, поддержки предприятия и пользовательской разработки: - Email: [email protected] - Техническая консультация: Доступна для сложных проектов - Пользовательская разработка: Решения, адаптированные к конкретным требованиям

Лицензия

Этот проект лицензирован в соответствии с лицензией MIT - см. файл LICENSE для деталей.