← Подключение оборудования | Содержание | Далее: Руководство и примеры для Arduino →

Универсальная библиотека для ESP32

Обзор библиотеки

Библиотека AC Dimmer — эффективное решение для управления яркостью устройств на переменном токе (AC) с помощью микроконтроллеров семейства ESP32. Библиотека использует аппаратные возможности ESP32: обработку прерываний GPIO и высокоточные таймеры — для точного управления моментом открытия TRIAC в каждом полупериоде переменного тока.

Info

GitHub библиотеки: https://github.com/robotdyn-dimmer/rbdimmerESP32

Возможности и преимущества

Совместимость с фреймворками Arduino, ESP-IDF и ESPHome
Поддержка многофазных систем
Несколько независимых каналов диммирования
Минимальное потребление ресурсов процессора благодаря аппаратным прерываниям и таймерам ESP
Высокоточное управление яркостью AC-устройств
Различные кривые регулировки яркости (линейная, RMS, логарифмическая)
Автоматическое определение частоты сети (50/60 Гц и другие)
Плавные переходы между уровнями яркости
Поддержка колбэк-функций для синхронизации с другими событиями

Требования

Микроконтроллеры семейства ESP32

Совместимость с Arduino ESP32 Core (версия 2.0.0 и выше):

ESP32
ESP32-C3
ESP32-C6
ESP32-H2
ESP32-P4
ESP32-S2
ESP32-S3

Совместимость с ESP-IDF (версия 5.0 и выше):

ESP32
ESP32-S2
ESP32-C3
ESP32-S3
ESP32-C2
ESP32-C6
ESP32-H2
ESP32-P4

Совместимость с ESPHome:

ESP32
ESP32-S2
ESP32-S3
ESP32-C3
ESP32-H2

Фреймворки: руководства и примеры

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

Руководство и примеры для Arduino
Руководство и примеры для ESP-IDF
Руководство и примеры для ESPHome

Функциональные характеристики

Выбор кривой яркости

Библиотека поддерживает три типа кривых для регулировки яркости:

Линейная (AC_DIMMER_CURVE_LINEAR)

Равномерное изменение угла задержки
Подходит для простых приложений
Воспринимаемая яркость не линейна

RMS (AC_DIMMER_CURVE_RMS)

Компенсирует RMS-характеристику синусоидального сигнала
Обеспечивает линейное изменение мощности
Идеально для ламп накаливания и резистивных нагрузок

Логарифмическая (AC_DIMMER_CURVE_LOGARITHMIC)

Компенсирует логарифмическое восприятие яркости человеческим глазом
Обеспечивает визуально линейное изменение яркости
Рекомендуется для светодиодного освещения

Плавные переходы

Для создания плавных переходов между уровнями яркости используйте функцию ac_dimmer_set_brightness_transition():

Tip

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

Многоканальные системы

Библиотека поддерживает несколько независимых каналов диммирования. Максимальное количество каналов задаётся в настройках библиотеки в файле ac_dimmer.h. Каждый канал диммирования должен иметь отдельный выходной пин.

Использование колбэк-функций прерываний

Колбэк-функции позволяют синхронизировать код с событиями перехода через ноль. Это полезно для задач, требующих точной синхронизации с сетью AC.

Warning

Используйте минимальный код в колбэк-функции. Рекомендуется применять вызовы задач FreeRTOS.

Оптимизация и отладка

Оптимальное использование ресурсов

Ограничения esp-timer:

Библиотека использует esp_timer, позволяющий создавать несколько программных таймеров
Для каждого канала используются 2 таймера: один для задержки и один для ширины импульса

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

Обработчики прерываний максимально упрощены для снижения нагрузки
Атрибут IRAM_ATTR используется для размещения кода обработчика в IRAM
Сложные вычисления выполняются за пределами обработчиков прерываний

Warning

Важно: не используйте тяжёлый код в колбэк-функции прерывания перехода через ноль. Рекомендуется применять вызовы задач FreeRTOS.

Производительность:

Предварительно рассчитанные таблицы кривых яркости сокращают время вычислений
Кэширование параметров уменьшает число повторных вычислений

Логирование:

В библиотеке реализована расширенная система логирования. Для отладки проекта включите вывод операций библиотечных функций в последовательный порт.

Решение типовых проблем

Лампа мигает или яркость нестабильна

Может проявляться при уровнях диммирования 0–8.

Причины и решения:

Неправильное подключение нулевого провода AC и фазы: проверьте подключение источника питания AC. Нулевой — к N, фаза — к AC-L IN
Проблемы с детектором перехода через ноль: проверьте форму сигнала и порог срабатывания
Архитектура микроконтроллера ESP32 и Arduino core: неоптимальная совместимость и приоритеты модулей ISR и таймера на уровне Arduino Core
Высокая загрузка процессора: сократите количество вычислений в основном цикле
Конфликты прерываний: убедитесь, что другие библиотеки не конфликтуют с прерываниями

Некорректная яркость для определённых типов нагрузок

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

Решение: измените тип кривой яркости для вашей нагрузки

Детектор перехода через ноль не работает

Диммер не реагирует на регулировку:

Проверьте подключение пина перехода через ноль
Убедитесь, что сигнал поступает на ESP32
Проверьте функцию ac_dimmer_get_frequency() — если она возвращает 0, частота сети не определена

Техническая информация

Принципы работы AC-диммера

Управление мощностью в цепях AC основано на принципе фазового регулирования с помощью TRIAC (тиристора).

Info

Подробнее см. в статье о принципе работы TRIAC.

Особенности esp-timer в ESP32

Библиотека использует esp_timer для точного управления задержками:

Преимущества esp-timer:

разрешение в микросекундах
программная реализация позволяет создавать большое количество таймеров
низкие накладные расходы

Архитектура esp-timer:

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

Ограничения:

небольшой джиттер (±10–50 мкс) при высокой загрузке системы
колбэк-функция не должна блокировать выполнение надолго

Обработка прерываний

Прерывания перехода через ноль:

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

Таймеры:

первый таймер запускается с временем задержки и активирует выход
второй таймер запускается для определения длительности импульса

Методы повышения стабильности:

обработчики прерываний максимально упрощены и размещены в IRAM
критические секции защищают общие данные
минимум вычислений в обработчиках прерываний