← Conexión de hardware | Contenido | Siguiente: Guía Arduino y ejemplos →

Biblioteca universal para ESP32

Descripción general de la biblioteca

La biblioteca de dimmer AC es una solución eficiente para controlar el brillo de dispositivos de corriente alterna (AC) mediante un microcontrolador de la familia ESP32. La biblioteca aprovecha las capacidades de hardware del ESP32, como el procesamiento de interrupciones GPIO y los temporizadores de alta precisión, para controlar con exactitud el instante de activación del TRIAC en cada semiciclo de la corriente alterna.

Características y ventajas

• Compatible con los frameworks Arduino, ESP-IDF y ESPHome
• Compatible con sistemas multifásicos
• Soporte para múltiples canales de atenuación independientes
• Uso mínimo de recursos del procesador gracias a las interrupciones de hardware y los temporizadores ESP
• Control de brillo de alta precisión para dispositivos AC
• Diversas curvas de regulación de brillo (lineal, RMS, logarítmica)
• Detección automática de la frecuencia de red (50/60 Hz y otras)
• Transiciones suaves entre niveles de brillo
• Soporte para funciones callback para sincronización con otros eventos

Requisitos

Microcontrolador de la familia ESP32

Compatible con Arduino ESP32 Core (versión 2.0.0 o superior):

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

Compatible con ESP-IDF (5.0 o superior):

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

Compatible con ESPHome:

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

Frameworks: guías y ejemplos

Documentación disponible

• Guía Arduino y ejemplos
• Guía ESP-IDF y ejemplos
• Guía ESPHome y ejemplos

Especificaciones funcionales

Selección de la curva de brillo

La biblioteca admite tres tipos de curvas para el ajuste del brillo:

Lineal (AC_DIMMER_CURVE_LINEAR)

• Cambio uniforme del ángulo de retardo
• Adecuada para aplicaciones sencillas
• El brillo percibido no es lineal

RMS (AC_DIMMER_CURVE_RMS)

• Compensa la característica RMS de una señal sinusoidal
• Proporciona un cambio de potencia lineal
• Ideal para bombillas incandescentes y cargas resistivas

Logarítmica (AC_DIMMER_CURVE_LOGARITHMIC)

• Compensa la percepción logarítmica del brillo por el ojo humano
• Proporciona un cambio de brillo visualmente lineal
• Recomendada para iluminación LED

Transiciones suaves

Para crear transiciones suaves entre niveles de brillo, use la función ac_dimmer_set_brightness_transition():

Sistemas multicanal

La biblioteca admite múltiples canales de atenuación independientes. El número de canales está limitado en la configuración de la biblioteca en el archivo ac_dimmer.h. Cada canal de atenuación debe tener un pin de salida independiente.

Uso de funciones callback de interrupción

Las funciones callback permiten sincronizar el código con los eventos de cruce por cero. Útil para tareas que requieren sincronización precisa con la red AC.

Optimización y depuración

Uso óptimo de recursos

Limitaciones de los ESP-Timers:

• La biblioteca usa esp_timer, que permite crear múltiples temporizadores por software
• Para cada canal se usan 2 temporizadores: uno para el retardo y otro para el ancho de pulso

Optimización de interrupciones:

• Los manejadores de interrupción se mantienen lo más cortos posible para reducir la carga
• El atributo IRAM_ATTR se usa para ubicar el código del manejador en IRAM
• Los cálculos complejos se realizan fuera de los manejadores de interrupción

Rendimiento:

• Las tablas precalculadas para las curvas de brillo reducen el tiempo de cálculo
• El almacenamiento en caché de parámetros reduce los cálculos repetidos

Registro:

La biblioteca cuenta con un sistema de registro mejorado. Para depurar el proyecto, active el registro de las operaciones de las funciones de la biblioteca en el puerto serie.

Solución de problemas comunes

La lámpara parpadea o el brillo es inestable

Esto puede ocurrir en niveles de atenuación del 0 al 8.

Causas y soluciones:

• Conexión incorrecta del neutro y la fase AC: verifique la conexión de la fuente AC. Neutro a N, fase a AC-L IN
• Problemas con el detector de cruce por cero: verifique la forma de onda de la señal y el umbral de disparo
• Arquitectura del microcontrolador ESP32 y Arduino core: compatibilidad y prioridades subóptimas del módulo ISR y del módulo de temporizador a nivel de Arduino Core
• Alta carga de CPU: reduzca el número de cálculos en el bucle principal
• Conflictos de interrupciones: asegúrese de que otras bibliotecas no entren en conflicto con las interrupciones

Brillo incorrecto para ciertos tipos de carga

Causas: al 50% de brillo, la lámpara parece demasiado brillante o demasiado tenue

Solución: cambie el tipo de curva de brillo para su carga

El detector de cruce por cero no funciona

El dimmer no responde al ajuste:

• Verifique la conexión del pin de cruce por cero
• Asegúrese de que la señal llegue al ESP32
• Revise la función ac_dimmer_get_frequency() — si devuelve 0, la frecuencia de red no está determinada

Información técnica

Principios de funcionamiento del dimmer AC

El control de potencia en circuitos AC se basa en el principio de regulación de fase mediante un TRIAC (tiristor).

Características del ESP-Timer en ESP32

La biblioteca usa esp_timer para el control preciso de los retardos:

Ventajas del ESP-Timer:

• Resolución en microsegundos
• La implementación por software permite crear numerosos temporizadores
• Baja sobrecarga

Arquitectura del ESP-Timer:

• Un temporizador de hardware para todos los temporizadores por software
• Cola de temporizadores ordenada por tiempo de activación
• Las funciones callback se llaman en el contexto de la tarea del temporizador

Limitaciones:

• Ligero jitter (±10-50 µs) bajo alta carga del sistema
• La función callback no debe bloquear la ejecución por mucho tiempo

Gestión de interrupciones

Interrupciones de cruce por cero:

• Se generan en el momento del cruce por cero
• Se usa el tipo de interrupción GPIO_INTR_POSEDGE (solo flanco ascendente)
• El manejador inicia los temporizadores para todos los canales activos de la fase correspondiente

Temporizadores:

• El primer temporizador se inicia para el tiempo de retardo y activa la salida
• El segundo temporizador se inicia para determinar la duración del pulso

Métodos de mejora de la estabilidad:

• Los manejadores de interrupción se mantienen lo más cortos posible y se ubican en IRAM
• Las secciones críticas protegen los datos compartidos
• Cálculos mínimos en los manejadores de interrupción

← Conexión de hardware | Contenido | Siguiente: Guía Arduino y ejemplos →