← Biblioteca universal para ESP32 | Contenido | Siguiente: Guía framework ESP-IDF en C y ejemplos →

Guía Arduino y ejemplos

Antes de comenzar, lea la descripción general de la biblioteca: Biblioteca universal para ESP32

Info

Descargar la biblioteca desde GitHub: https://github.com/robotdyn-dimmer/rbdimmerESP32

Instalación de la biblioteca

Arduino IDE

Descargue la biblioteca rbdimmerESP32 como archivo ZIP
En Arduino IDE, seleccione: Programa > Incluir Biblioteca > Añadir biblioteca .ZIP
Seleccione el archivo ZIP descargado
Reinicie Arduino IDE para completar la instalación

PlatformIO

Cree un proyecto nuevo o abra uno existente
Añada la biblioteca a su platformio.ini desde el repositorio de GitHub o una ruta local:

ini

lib_deps =
  # GitHub repository
  https://github.com/robotdyn-dimmer/rbdimmerESP32
  # or local path
  # rbdimmer=file:///path/to/rbdimmerESP32

PlatformIO instalará automáticamente la biblioteca durante la próxima compilación

Conexión de hardware

Las instrucciones para conectar el dimmer al microcontrolador y la carga AC están disponibles aquí:

Conecte el pin Zero-Cross a cualquier GPIO con funcionalidad ISR; consulte la documentación de su chip ESP32
Conecte el pin Dimmer a cualquier GPIO
VCC a 3,3 V. Para ESP32, VCC = 3,3 V
GND a GND

Info

La guía detallada de conexión de hardware: Conexión de hardware

Ejemplo básico

cpp

#include 
#include "rbdimmerESP32.h"

// Pins
#define ZERO_CROSS_PIN  18   // Zero-Cross pin
#define DIMMER_PIN      19   // Dimming control pin
#define PHASE_NUM       0    // Phase N (0 for single phase)

// Global variables. Dimmer object
rbdimmer_channel_t* dimmer_channel = NULL;

void setup() {
  Serial.begin(115200);
  delay(1000);

  Serial.println("AC Dimmer Test");

  // Dimmer lib init
  if (rbdimmer_init() != RBDIMMER_OK) {
    Serial.println("Failed to initialize AC Dimmer library");
    return;
  }

  // Zero-cross detector and phase registry
  if (rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0) != RBDIMMER_OK) {
    Serial.println("Failed to register zero-cross detector");
    return;
  }

  // Dimmer channel. Configuration data structure.
  rbdimmer_config_t config_channel = {
    .gpio_pin = DIMMER_PIN,
    .phase = PHASE_NUM,
    .initial_level = 50,  // Initial dimming level 50%
    .curve_type = RBDIMMER_CURVE_RMS  // Level Curve Selection. RMS-curve
  };

  if (rbdimmer_create_channel(&config_channel, &dimmer_channel) != RBDIMMER_OK) {
    Serial.println("Failed to create dimmer channel");
    return;
  }

  Serial.println("AC Dimmer initialized successfully");
}

void loop() {
  // dimming from 10% to 90% with step 10
  for (int brightness = 10; brightness <= 90; brightness += 10) {
    Serial.printf("Setting brightness to %d%%\n", brightness);
    rbdimmer_set_level(dimmer_channel, brightness);
    delay(2000);
  }

  // Smooth transition from current level to 0 level in 5 sec
  Serial.println("Smooth transition to 0%");
  rbdimmer_set_level_transition(dimmer_channel, 0, 5000);
  delay(6000); // delay 6 sec

  // Smooth transition from current level (0) to 100 level in 5 sec
  Serial.println("Smooth transition to 100%");
  rbdimmer_set_level_transition(dimmer_channel, 100, 5000);
  delay(6000); // delay 6 sec
}

Referencia de API

Explicación del funcionamiento de la biblioteca

Preparación:

La biblioteca se inicializa con rbdimmer_init()
El detector de cruce por cero se registra con rbdimmer_register_zero_cross()
El canal dimmer se crea con rbdimmer_create_channel()

Control de atenuación:

Ajuste del nivel de atenuación con rbdimmer_set_level(). El nivel se establece en el rango 0 (apagado) a 100 (encendido)
Transición suave del nivel con rbdimmer_set_level_transition(). Transición gradual del nivel actual al nivel establecido en un período de tiempo (en milisegundos, 1 s = 1000 ms)

Info

Cómo funciona un dimmer — artículo en nuestro blog: Principios de funcionamiento del dimmer AC

Estructuras de datos

rbdimmer_config_t

typedef struct {
    uint8_t gpio_pin;                 // Dimmer GPIO
    uint8_t phase;                    // Phase number
    uint8_t initial_level;            // Initial dimming level
    rbdimmer_curve_t curve_type;      // Level Curve type
} rbdimmer_config_t;

Enumeraciones

rbdimmer_curve_t

Tipos de curvas de nivel:

typedef enum {
    RBDIMMER_CURVE_LINEAR,      // Linear curve
    RBDIMMER_CURVE_RMS,         // RMS-compensated curve (for incandescent bulbs)
    RBDIMMER_CURVE_LOGARITHMIC  // Logarithmic curve (for dimmable LED)
} rbdimmer_curve_t;

rbdimmer_err_t

Respuestas de las funciones de la biblioteca:

typedef enum {
    RBDIMMER_OK = 0,            // Successful execution
    RBDIMMER_ERR_INVALID_ARG,   // Invalid argument
    RBDIMMER_ERR_NO_MEMORY,     // Not enough memory
    RBDIMMER_ERR_NOT_FOUND,     // Object not found
    RBDIMMER_ERR_ALREADY_EXIST, // Object already exists
    RBDIMMER_ERR_TIMER_FAILED,  // Timer initialization error
    RBDIMMER_ERR_GPIO_FAILED    // GPIO initialization error
} rbdimmer_err_t;

Constantes y macros

Constantes en el archivo rbdimmerESP32.h. Puede modificar estos parámetros:

#define RBDIMMER_MAX_PHASES 4                 // Maximum number of phases
#define RBDIMMER_MAX_CHANNELS 8               // Maximum number of channels
#define RBDIMMER_DEFAULT_PULSE_WIDTH_US 50    // Pulse width (us)
#define RBDIMMER_MIN_DELAY_US 50              // Minimum delay (us)

Warning

No recomendamos modificar RBDIMMER_DEFAULT_PULSE_WIDTH_US, ya que está relacionado con las características de hardware del dimmer.

Funciones

Inicialización y configuración

// Initialize the library
rbdimmer_err_t rbdimmer_init(void);

// Register a zero-cross detector
rbdimmer_err_t rbdimmer_register_zero_cross(uint8_t pin, uint8_t phase, uint16_t frequency);

// Create a dimmer channel
rbdimmer_err_t rbdimmer_create_channel(rbdimmer_config_t* config, rbdimmer_channel_t** channel);

// Set callback function for zero-cross events
rbdimmer_err_t rbdimmer_set_callback(uint8_t phase, void (*callback)(void*), void* user_data);

Control de atenuación

// Set dimming level
rbdimmer_err_t rbdimmer_set_level(rbdimmer_channel_t* channel, uint8_t level_percent);

// Set brightness with smooth transition
rbdimmer_err_t rbdimmer_set_level_transition(rbdimmer_channel_t* channel, uint8_t level_percent, uint32_t transition_ms);

// Set brightness curve type
rbdimmer_err_t rbdimmer_set_curve(rbdimmer_channel_t* channel, rbdimmer_curve_t curve_type);

// Activate/deactivate channel
rbdimmer_err_t rbdimmer_set_active(rbdimmer_channel_t* channel, bool active);

Consultas de información

// Get current channel brightness
uint8_t rbdimmer_get_level(rbdimmer_channel_t* channel);

// Get measured mains frequency for the specified phase
uint16_t rbdimmer_get_frequency(uint8_t phase);

// Check if channel is active
bool rbdimmer_is_active(rbdimmer_channel_t* channel);

// Get channel curve type
rbdimmer_curve_t rbdimmer_get_curve(rbdimmer_channel_t* channel);

// Get current channel delay
uint32_t rbdimmer_get_delay(rbdimmer_channel_t* channel);

Guía paso a paso

Pasos de implementación para la inicialización de la biblioteca, registro de la fase, detector de cruce por cero, canal de atenuación y control de atenuación:

1. Definir la biblioteca y los pines

cpp

#include "rbdimmerESP32.h"

// Pins
#define ZERO_CROSS_PIN  18   // Zero-Cross pin
#define DIMMER_PIN      19   // Dimming control pin
#define PHASE_NUM       0    // Phase N (0 for single phase)

2. Crear el objeto dimmer

Para cada dimmer, crear un objeto:

cpp

rbdimmer_channel_t* dimmer_channel = NULL;

3. Inicialización de la biblioteca dimmer

La función devuelve un estado:

cpp

rbdimmer_init();

4. Registro del detector de cruce por cero y la fase

La función devuelve un estado:

cpp

rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

5. Configuración y creación del canal dimmer

cpp

rbdimmer_config_t config_channel = {
    .gpio_pin = DIMMER_PIN,
    .phase = PHASE_NUM,
    .initial_level = 50,  // Initial dimming level 50%
    .curve_type = RBDIMMER_CURVE_RMS  // Level Curve Selection. RMS-curve
};

rbdimmer_create_channel(&config_channel, &dimmer_channel);

6. Control de atenuación

cpp

rbdimmer_set_level(dimmer_channel, level);

7. Transiciones suaves de atenuación

cpp

rbdimmer_set_level_transition(dimmer_channel, 0, 5000);

Tip

La función crea una transición suave dividiéndola en múltiples pasos pequeños. Utiliza una tarea FreeRTOS; durante la transición, el código principal continúa ejecutándose.

Soluciones

Sistemas dimmer 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 rbdimmerESP32.h. Cada canal de atenuación debe tener un pin de salida independiente.

Ejemplo de creación de un sistema de dos canales:

cpp

#define ZERO_CROSS_PIN  18
#define DIMMER_PIN_1    19
#define DIMMER_PIN_2    21
#define PHASE_NUM       0

rbdimmer_channel_t* channel1 = NULL;
rbdimmer_channel_t* channel2 = NULL;

void setup() {
  // Initialize library
  rbdimmer_init();

  // Register zero-cross detector (one per phase)
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

  // Create first channel (incandescent bulbs)
  rbdimmer_config_t config1 = {
    .gpio_pin = DIMMER_PIN_1,
    .phase = PHASE_NUM,
    .initial_level = 50,
    .curve_type = RBDIMMER_CURVE_RMS
  };
  rbdimmer_create_channel(&config1, &channel1);

  // Create second channel (dimmable LED lighting)
  rbdimmer_config_t config2 = {
    .gpio_pin = DIMMER_PIN_2,
    .phase = PHASE_NUM,
    .initial_level = 50,
    .curve_type = RBDIMMER_CURVE_LOGARITHMIC
  };
  rbdimmer_create_channel(&config2, &channel2);
}

void loop() {
  // Control channels independently
  rbdimmer_set_level(channel1, 75);
  rbdimmer_set_level(channel2, 25);
  delay(2000);

  rbdimmer_set_level(channel1, 25);
  rbdimmer_set_level(channel2, 75);
  delay(2000);
}

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.

Ejemplo de registro y manejador de tarea FreeRTOS:

cpp

// Callback function for zero-cross events
void zero_cross_callback(void* arg) {
  // process zero-cross events
  digitalWrite(LED_PIN, !digitalRead(LED_PIN)); // Flashing with ZC frequency

  // Any code
}

void setup() {
  // ... Lib inits ...

  // callback-function registry
  rbdimmer_set_callback(PHASE_NUM, zero_cross_callback, NULL);

  // ... any code ...
}

Warning

No use código pesado en la función callback. Recomendamos usar llamadas a tareas FreeRTOS.

Sistemas multifásicos

Para sistemas trifásicos, debe registrarse un detector de cruce por cero independiente para cada fase:

cpp

#define ZERO_CROSS_PIN_PHASE_A  18
#define ZERO_CROSS_PIN_PHASE_B  19
#define ZERO_CROSS_PIN_PHASE_C  21

#define DIMMER_PIN_PHASE_A      22
#define DIMMER_PIN_PHASE_B      23
#define DIMMER_PIN_PHASE_C      25

#define PHASE_A  0
#define PHASE_B  1
#define PHASE_C  2

void setup() {
  // Lib init
  rbdimmer_init();

  // ZC detect registry for each phase
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN_PHASE_A, PHASE_A, 0);
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN_PHASE_B, PHASE_B, 0);
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN_PHASE_C, PHASE_C, 0);

  // Create dimming channels for each phase
  // ... dimming code ...
}

Monitoreo del funcionamiento

Para depuración, puede usar las funciones integradas de la biblioteca:

cpp

void printDimmerStatus(rbdimmer_channel_t* channel) {
  Serial.println("=== Dimmer Status ===");
  Serial.printf("Mains frequency: %d Hz\n", rbdimmer_get_frequency(0));
  Serial.printf("Brightness: %d%%\n", rbdimmer_get_level(channel));
  Serial.printf("Active: %s\n", rbdimmer_is_active(channel) ? "Yes" : "No");
  Serial.printf("Curve type: %d\n", rbdimmer_get_curve(channel));
  Serial.printf("Delay: %d us\n", rbdimmer_get_delay(channel));
  Serial.println("====================");
}

Ejemplos básicos para la biblioteca dimmer AC

Control básico del dimmer

Descripción: el ejemplo más simple que muestra cómo controlar un dimmer AC con un nivel de brillo fijo.

cpp

#include 
#include "rbdimmerESP32.h"

#define ZERO_CROSS_PIN 18
#define DIMMER_PIN 19
#define PHASE_NUM 0

rbdimmer_channel_t* dimmer = NULL;

void setup() {
  Serial.begin(115200);
  delay(1000);

  // Initialize the library
  rbdimmer_init();

  // Register zero-cross detector
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

  // Create dimmer channel with RMS curve (best for incandescent bulbs)
  rbdimmer_config_t config = {
    .gpio_pin = DIMMER_PIN,
    .phase = PHASE_NUM,
    .initial_level = 50,  // Start at 50% brightness
    .curve_type = RBDIMMER_CURVE_RMS
  };

  rbdimmer_create_channel(&config, &dimmer);
  Serial.println("Dimmer initialized at 50% brightness");
}

void loop() {
  // Nothing needed in the loop - dimmer maintains its state
  delay(1000);
}

Transición de brillo

Muestra cómo crear transiciones suaves entre niveles de brillo.

cpp

#include 
#include "rbdimmerESP32.h"

#define ZERO_CROSS_PIN 18
#define DIMMER_PIN 19
#define PHASE_NUM 0

rbdimmer_channel_t* dimmer = NULL;

void setup() {
  Serial.begin(115200);
  delay(1000);

  // Initialize dimmer
  rbdimmer_init();
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

  rbdimmer_config_t config = {
    .gpio_pin = DIMMER_PIN,
    .phase = PHASE_NUM,
    .initial_level = 0,  // Start with light off
    .curve_type = RBDIMMER_CURVE_RMS
  };

  rbdimmer_create_channel(&config, &dimmer);
  Serial.println("Dimmer initialized");
}

void loop() {
  // Fade up to 100% over 3 seconds
  Serial.println("Fading up...");
  rbdimmer_set_level_transition(dimmer, 100, 3000);
  delay(4000);  // Wait for transition + 1 second

  // Fade down to 10% over 3 seconds
  Serial.println("Fading down...");
  rbdimmer_set_level_transition(dimmer, 10, 3000);
  delay(4000);  // Wait for transition + 1 second
}

Múltiples canales dimmer

Controla dos canales dimmer independientes por separado.

cpp

#include 
#include "rbdimmerESP32.h"

#define ZERO_CROSS_PIN 18
#define DIMMER_PIN_1 19
#define DIMMER_PIN_2 21
#define PHASE_NUM 0

rbdimmer_channel_t* dimmer1 = NULL;
rbdimmer_channel_t* dimmer2 = NULL;

void setup() {
  Serial.begin(115200);
  delay(1000);

  // Initialize dimmer library
  rbdimmer_init();
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

  // Create first dimmer channel (for incandescent bulb)
  rbdimmer_config_t config1 = {
    .gpio_pin = DIMMER_PIN_1,
    .phase = PHASE_NUM,
    .initial_level = 50,
    .curve_type = RBDIMMER_CURVE_RMS
  };
  rbdimmer_create_channel(&config1, &dimmer1);

  // Create second dimmer channel (for LED light)
  rbdimmer_config_t config2 = {
    .gpio_pin = DIMMER_PIN_2,
    .phase = PHASE_NUM,
    .initial_level = 50,
    .curve_type = RBDIMMER_CURVE_LOGARITHMIC  // Better for LEDs
  };
  rbdimmer_create_channel(&config2, &dimmer2);

  Serial.println("Two dimmer channels initialized");
}

void loop() {
  // Alternate level between channels
  Serial.println("Channel 1: 80%, Channel 2: 20%");
  rbdimmer_set_level(dimmer1, 80);
  rbdimmer_set_level(dimmer2, 20);
  delay(3000);

  Serial.println("Channel 1: 20%, Channel 2: 80%");
  rbdimmer_set_level(dimmer1, 20);
  rbdimmer_set_level(dimmer2, 80);
  delay(3000);
}

Callback de cruce por cero

Demuestra el uso de una función callback con una tarea FreeRTOS para procesar de forma segura los eventos de cruce por cero, permitiendo sincronizarse con la onda AC sin añadir retardo de ejecución al manejador de interrupción.

cpp

#include 
#include "rbdimmerESP32.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"

#define ZERO_CROSS_PIN 18
#define DIMMER_PIN 19
#define LED_PIN 2  // Onboard LED for zero-cross visualization
#define PHASE_NUM 0

rbdimmer_channel_t* dimmer = NULL;
uint32_t zeroCount = 0;

// FreeRTOS components
QueueHandle_t zeroCrossQueue;
TaskHandle_t zeroCrossTaskHandle;

// Simple message type for our queue
typedef struct {
  uint32_t timestamp;
} ZeroCrossEvent_t;

// Callback function for zero-cross events (runs in ISR context)
void zeroCrossCallback(void* arg) {
  // Create event
  ZeroCrossEvent_t event;
  event.timestamp = millis();

  // Send to queue from ISR
  BaseType_t xHigherPriorityTaskWoken = pdFALSE;
  xQueueSendFromISR(zeroCrossQueue, &event, &xHigherPriorityTaskWoken);

  // If a higher priority task was woken, request context switch
  if (xHigherPriorityTaskWoken) {
    portYIELD_FROM_ISR();
  }
}

// Task to process zero-cross events
void zeroCrossProcessingTask(void* parameter) {
  ZeroCrossEvent_t event;

  // Task loop - will run forever
  for (;;) {
    // Wait for an item from the queue
    if (xQueueReceive(zeroCrossQueue, &event, portMAX_DELAY)) {
      // Process the event (now we're in task context, not ISR)

      // Toggle LED to visualize zero-crossing
      digitalWrite(LED_PIN, !digitalRead(LED_PIN));

      // Count zero-crossing events
      zeroCount++;

      // Additional processing can be done here safely
      // This doesn't affect the zero-cross interrupt timing
    }
  }
}

void setup() {
  Serial.begin(115200);
  delay(1000);

  // Setup LED for visual zero-cross indication
  pinMode(LED_PIN, OUTPUT);

  // Create the queue to send events from ISR to task
  zeroCrossQueue = xQueueCreate(10, sizeof(ZeroCrossEvent_t));
  if (zeroCrossQueue == NULL) {
    Serial.println("Error creating the queue");
    while (1); // Stop execution on error
  }

  // Create the task to process zero-cross events
  BaseType_t xReturned = xTaskCreate(
    zeroCrossProcessingTask,  // Task function
    "ZeroCrossTask",          // Task name
    2048,                     // Stack size (bytes)
    NULL,                     // No parameters needed
    5,                        // Medium priority
    &zeroCrossTaskHandle      // Task handle
  );

  if (xReturned != pdPASS) {
    Serial.println("Error creating the task");
    while (1); // Stop execution on error
  }

  // Initialize dimmer
  rbdimmer_init();
  rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

  // Register zero-cross callback
  rbdimmer_set_callback(PHASE_NUM, zeroCrossCallback, NULL);

  // Create dimmer channel
  rbdimmer_config_t config = {
    .gpio_pin = DIMMER_PIN,
    .phase = PHASE_NUM,
    .initial_level = 60,
    .curve_type = RBDIMMER_CURVE_RMS
  };

  rbdimmer_create_channel(&config, &dimmer);
  Serial.println("Dimmer with zero-cross callback and task processing initialized");
}

void loop() {
  // Print zero-cross statistics every second
  static unsigned long lastPrint = 0;

  if (millis() - lastPrint >= 1000) {
    uint16_t frequency = rbdimmer_get_frequency(PHASE_NUM);

    Serial.printf("Zero-cross count: %u, Detected frequency: %u Hz\n",
                  zeroCount, frequency);

    lastPrint = millis();
  }

  delay(10);
}

Esta implementación mejora significativamente el ejemplo original al:

Mantener la ISR (rutina de servicio de interrupción) extremadamente corta — solo envía un mensaje a la cola
Mover toda la lógica de procesamiento a una tarea FreeRTOS dedicada
Usar mecanismos FreeRTOS apropiados para la comunicación segura entre ISR y tarea
Evitar problemas de timing en la detección del cruce por cero separando el manejo de la interrupción del procesamiento

Este enfoque sigue las mejores prácticas para sistemas en tiempo real, donde los manejadores de interrupción deben ser lo más cortos posible para no afectar el timing y la capacidad de respuesta del sistema.

← Biblioteca universal para ESP32 | Contenido | Siguiente: Guía framework ESP-IDF en C y ejemplos →

Products

Featured

Get Started

Integrations

Guides & Articles

ACRouter

Project Showcase

Getting Started

Integrations

AC Dimmers

DimmerLink

ACRouter

GitHub

Guía Arduino y ejemplos

Instalación de la biblioteca

Arduino IDE

PlatformIO

Conexión de hardware

Ejemplo básico

Referencia de API

Explicación del funcionamiento de la biblioteca

Estructuras de datos

rbdimmer_config_t

Enumeraciones

rbdimmer_curve_t

rbdimmer_err_t

Constantes y macros

Funciones

Inicialización y configuración

Control de atenuación

Consultas de información

Guía paso a paso

1. Definir la biblioteca y los pines

2. Crear el objeto dimmer

3. Inicialización de la biblioteca dimmer

4. Registro del detector de cruce por cero y la fase

5. Configuración y creación del canal dimmer

6. Control de atenuación

7. Transiciones suaves de atenuación

Soluciones

Sistemas dimmer multicanal

Uso de funciones callback de interrupción

Sistemas multifásicos

Monitoreo del funcionamiento

Ejemplos básicos para la biblioteca dimmer AC

Control básico del dimmer

Transición de brillo

Múltiples canales dimmer

Callback de cruce por cero