rbdimmerESP32 - Biblioteca Profesional de Controlador AC para ESP32

v2.0.0 Cambios Incompatibles: El diseño interno del código fuente cambió a módulos en src/internal/. Los ejemplos se restructuraron en directorios por sketch (Arduino IDE 2.x). El archivo Kconfig.txt se renombró a Kconfig. La API pública no ha cambiado — no se requieren cambios en el código del usuario.

Una biblioteca profesional y de alto rendimiento para el control de dimmers AC en microcontroladores ESP32. Diseñada para precisión en tiempos, eficiencia de hardware, operación multi-fase y multi-canal con soporte para varios tipos de carga incluyendo bombillas incandescentes, dimmers LED y aplicaciones de control de motores.

Características Principales

Optimización de Hardware

• Hardware Timer Integration: Uses ESP32's high-resolution timers for microsecond precision
• Arquitectura Basada en Interrupciones: Overhead de CPU mínimo con manejo de interrupciones de hardware
• Soporte Multi-Fase: Hasta 4 fases AC independientes con detección individual de paso por cero
• Detección Automática de Frecuencia: Soporta redes de 50Hz y 60Hz con auto-detección
• Colocación IRAM_ATTR ISR: Todas las rutas críticas en tiempo están en IRAM para latencia determinística
• Despacho ESP_TIMER_ISR: Las devoluciones de llamada del temporizador se despachadas desde contexto ISR para mínima fluctuación
• Compuerta de Ruido de Paso por Cero: Filtro de rebote validado por hardware que elimina disparos falsos de picos de conmutación TRIAC

Control Avanzado

• Múltiples Curvas de Brillo: Curvas lineal, compensada por RMS y logarítmica para diferentes cargas
• Transiciones Suaves: Transiciones de brillo sin bloqueo usando tareas FreeRTOS
• Operación Multi-Canal: Control de hasta 8 canales de dimmer independientes simultáneamente
• Sincronización en Tiempo Real: Operación bloqueada en fase con frecuencia de la red

Características Profesionales

• Manejo Integral de Errores: Códigos de error detallados e información de diagnóstico
• Diseño Thread-Safe: Compatibilidad total con FreeRTOS con gestión adecuada de recursos
• Documentación Extensa: Documentación Doxygen completa con ejemplos
• Soporte Multiplataforma: Funciona con Arduino IDE y ESP-IDF

Arquitectura Modular

v2.0.0 reemplaza la implementación monolítica de archivo único con seis módulos internos:

Nota: El encabezado público (rbdimmerESP32.h) y la API no han cambiado — el código del usuario no requiere modificación.

Inicio Rápido

Instalación en Arduino IDE

1. Descargue la biblioteca desde GitHub
2. En Arduino IDE: Sketch → Include Library → Add .ZIP Library
3. Seleccione el archivo ZIP descargado
4. Incluya en su sketch:

#include 

Ejemplo de Uso Básico

#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);
}

Requisitos de Hardware

Placas Soportadas

• ESP32 DevKit: Todas las variantes (ESP32-WROOM-32, ESP32-WROVER, etc.)
• ESP32-S2: Variante ESP32 de núcleo único con USB OTG
• ESP32-S3: Dual-core con capacidades AI mejoradas y USB
• ESP32-C3: Basado en RISC-V, consumo ultra-bajo de potencia
• ESP32-C6: Soporte Wi-Fi 6 con 802.11ax
• ESP32-H2: Dedicado para aplicaciones Thread/Zigbee
• ESP32-P4: Variante de alto rendimiento con procesamiento mejorado
• ESP32-C2: Optimizado por costo con conectividad esencial
• Placas Compatibles de Terceros: Wemos D1 Mini ESP32, NodeMCU-32S, etc.

Matriz de Compatibilidad de Frameworks

Hardware del Dimmer

Esta biblioteca está diseñada para funcionar con módulos dimmers pre-construidos que incluyen: - Circuito de detección de paso por cero - Controlador TRIAC o relé de estado sólido - Aislamiento óptico para seguridad - Disipación de calor apropiada

⚠️ Advertencia de Seguridad: El voltaje de la red AC es peligroso. Solo utilice módulos dimmers certificados con aislamiento adecuado.

Ejemplo de Cableado

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)

Documentación

Guías Específicas de Plataforma

• Guía Arduino: Configuración de Arduino Framework y Ejemplos
• Guía ESP-IDF: Configuración de ESP-IDF Framework y Ejemplos
• Descripción Completa de la Biblioteca: Documentación Integral

Características Avanzadas

Múltiples Curvas de Brillo

Elija la curva óptima para su tipo de carga y respuesta visual deseada:

// 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);

Características Detalladas de la Curva:

1. Lineal (RBDIMMER_CURVE_LINEAR) - Cambio uniforme en retardo de ángulo de fase - Conversión directa de porcentaje a retardo - Adecuada para control de motores y aplicaciones simples - ⚠️ Nota: El brillo percibido no es visualmente lineal

2. RMS (RBDIMMER_CURVE_RMS) - Compensa características RMS de AC sinusoidal - Proporciona cambio de potencia lineal: Potencia ∝ Nivel² - Ideal para bombillas incandescentes y cargas resistivas - Basado en: angle = arccos(√(level/100))

3. Logarítmica (RBDIMMER_CURVE_LOGARITHMIC) - Compensa percepción de brillo logarítmica - Proporciona cambios de brillo visualmente lineales - Recomendado para iluminación LED y pantallas - Basado en: log₁₀(1 + 9×(level/100))

Optimización de Rendimiento

Utilización de Temporizador de Hardware

• ESP-Timer Integration: Uses ESP32's high-resolution software timers
• Precisión en Microsegundos: Precisión de tiempo ±1-10μs bajo carga normal
• Eficiente en Recursos: 2 temporizadores por canal (retardo + ancho de pulso)
• Colocación IRAM: Código ISR crítico colocado en IRAM para velocidad

Optimización de Interrupciones

// 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
}

Optimización de Memoria

• Tablas Pre-calculadas: Curvas de brillo calculadas en la inicialización
• Almacenamiento en Caché Eficiente: Parámetros almacenados en caché para reducir cálculos repetidos
• Uso Mínimo de RAM: ~200 bytes por canal + ~1KB de overhead global
• Optimización Flash: ~32KB de ocupación total de flash

Sistema de Depuración y Logging

Habilite logging comprehensivo para desarrollo y resolución de problemas:

// 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);
}

Control Multi-Canal

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]);
}

Devoluciones de Llamada en Tiempo Real

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);

Parámetros Kconfig

Cuatro parámetros ajustables para builds ESP-IDF (Arduino usa valores por defecto en tiempo de compilación):

Casos de Uso

Automatización del Hogar

• Control inteligente de iluminación con dimming suave
• Integración con plataformas IoT (Home Assistant, OpenHAB)
• Control por voz y aplicaciones de smartphone
• Monitoreo y optimización de energía

Aplicaciones Comerciales

• Iluminación de escena y teatral
• Ambiente en restaurantes y hostelería
• Iluminación de displays minoristas
• Control de procesos industriales

Proyectos Educativos

• Demostraciones de electrónica de potencia
• Experimentos de control de fase AC
• Aprendizaje de sistemas en tiempo real
• Educación en programación embebida

Proyectos Maker

• Controladores de lámparas personalizados
• Efectos de luces Halloween/Navidad
• Iluminación sincronizada con música
• Control de ventiladores basado en temperatura

Problemas Comunes y Soluciones Rápidas

Parpadeo General o Brillo Inestable

Posibles Causas: - Conexiones incorrectas de Neutro/Línea AC - Problemas de señal del detector de paso por cero - Picos de conmutación TRIAC re-disparando detección ZC - Carga alta de CPU o conflictos de interrupciones

Correcciones Rápidas: - La compuerta de ruido de paso por cero v2.0.0 (ZC_DEBOUNCE_US = 3000µs) filtra re-disparos por picos TRIAC automáticamente - Intente diferentes curvas para su tipo de carga:

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");
}

Parpadeo al 100% de Brillo

Causa: Retardo mínimo demasiado corto, o nivel excediendo rango seguro.

Corrección en v2.0.0: MIN_DELAY_US aumentado de 50 a 100µs. Los niveles en o por encima del 100% se asignan a LEVEL_MAX (99%), previniendo glitches de marcha completa.

Desfase de Sincronización Multi-Canal

Causa: Los canales se arman en momentos ligeramente diferentes dentro de un único evento ZC.

Corrección en v2.0.0: ISR de dos pasadas — Pasada 1 reinicia todos los GPIOs, Pasada 2 arma todos los temporizadores. Esto garantiza que todos los canales comiencen desde la misma línea base en cada paso por cero.

Parpadeo por Debajo del 3% de Brillo

Causa: TRIAC no puede engancharse confiablemente en ángulos de conducción muy bajos.

Corrección en v2.0.0: Niveles por debajo de LEVEL_MIN (3%) se tratan como OFF, eliminando parpadeo errático en la parte inferior del rango de dimming.

Problemas de Brillo Específicos de Carga

Al 50%, la lámpara parece demasiado brillante/oscura:

// 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
}

Sin Respuesta del Dimmer

Compruebe la detección de paso por cero:

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");
    }
}

Matriz de Build CI

CI automatizado asegura que cada commit compile limpiamente en todas las plataformas soportadas:

• Arduino: arduino/compile-sketches@v1, Core 3.x, 4 ejemplos × 5 chips (ESP32, S2, S3, C3, C6)
• ESP-IDF: espressif/esp-idf-ci-action@v1, IDF v5.3/v5.4/v5.5 × 5 chips = 15 trabajos
• test_app/: Proyecto ESP-IDF mínimo para verificación de superficie API en tiempo de compilación

Plataformas Soportadas

Framework Arduino

• Arduino IDE 2.x
• Integración perfecta con librerías Arduino

Framework ESP-IDF

• ESP-IDF 5.3+ con soporte CMake
• Características de desarrollo profesionales

Herramientas de Desarrollo

• Visual Studio Code con extensión ESP-IDF
• CLion con plugin ESP-IDF
• Eclipse CDT con herramientas ESP-IDF
• Soporte de desarrollo desde línea de comandos

Características de Rendimiento

Beneficios de la Arquitectura ESP-Timer

• Implementación de Software: Permite numerosos temporizadores concurrentes
• Ejecución Basada en Cola: Ordenados por tiempo de disparo para eficiencia
• Overhead Bajo: Un único temporizador de hardware sirve todos los temporizadores de software
• Despacho ISR: Devoluciones de llamada del temporizador despachadas directamente desde contexto ISR para mínimo jitter

Limitaciones de Rendimiento

• Jitter del Temporizador: ±10-50μs posible bajo carga alta del sistema
• Restricciones de Devolución de Llamada: No deberían bloquear ejecución por períodos extendidos
• Escalado de Memoria: Cada canal requiere ~200 bytes RAM
• Limitaciones de GPIO: Los pines disponibles varían por variante ESP32

Comparación de Librerías

Contribuir

¡Bienvenido de contribuciones de la comunidad! Por favor lea nuestra Guía de Contribución para:

• Directrices de estilo de código
• Procedimientos de prueba
• Proceso de pull request
• Plantillas de reporte de problemas
• Configuración del ambiente de desarrollo

Ejemplos

Soporte y Comunidad

Recursos Oficiales

• Sitio Web: https://rbdimmer.com
• Documentación: https://www.rbdimmer.com/docs/universal-library-for-esp32
• Catálogo de Hardware: https://www.rbdimmer.com/dimmers-pricing
• Galería de Proyectos: https://www.rbdimmer.com/blog/integration-guides-8

Soporte Comunitario

• Foro: https://forum.rbdimmer.com
• GitHub Issues: Reportar bugs y solicitar características
• GitHub Discussions: Discusiones comunitarias y Q&A

Soporte Profesional

Para aplicaciones comerciales, soporte empresarial y desarrollo personalizado: - Email: [email protected] - Consulta Técnica: Disponible para proyectos complejos - Desarrollo Personalizado: Soluciones a medida para requisitos específicos

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENSE para detalles.

MIT License
Copyright (c) 2024 RBDimmer Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

Información de Versión

• Versión Actual: 2.0.0
• Fecha de Lanzamiento: 2026-03-23
• ESP-IDF Mínimo: 5.3+
• Arduino ESP32 Core: 3.x
• Arduino IDE: 2.x

Documentación en Otros Idiomas

La documentación completa está disponible en 5 idiomas en el sitio web de RBDimmer:

• English
• Русский (Russian)
• Français (French)
• Deutsch (German)
• Italiano (Italian)

Proyectos Relacionados

• Módulos de Hardware: Catálogo de Hardware RBDimmer
• Ejemplos de Aplicación: Galería de Proyectos
• Documentación Técnica: Base de Conocimiento

Hecho con ❤️ por el Equipo RBDimmer

Control profesional de dimmers AC para la comunidad maker