Passa al contenuto

← Libreria Universale per ESP32 | Indice | Prossimo: - Guida framework ESP-IDF C e esempi. →

Guida Arduino e Esempi

Prima di iniziare, leggi la panoramica della libreria: Libreria universale per ESP32

Novità in v2.0.0

  • Architettura interna modulare -- gli interni della libreria sono stati riorganizzati in moduli separati. L'API pubblica è invariata; gli sketch esistenti si compilano ed eseguono senza modifiche.
  • Porta di rumore zero-cross -- elimina i ri-trigger di picchi TRIAC falsi che in precedenza causavano sfarfallio su alcuni carichi.
  • ISR a due passate per la sincronizzazione multi-canale -- tutti i canali sulla stessa fase sono ora ordinati e attivati in un singolo mezzo ciclo, rimuovendo il jitter di temporizzazione tra i canali.
  • IRAM_ATTR su tutti i percorsi sensibili alla temporizzazione -- i gestori ISR e le funzioni correlate vengono posizionati in IRAM per evitare i miss della cache flash durante le operazioni sensibili al tempo.
  • Quattro nuovi parametri Kconfig -- configurabili tramite idf.py menuconfig per progetti ESP-IDF. I build Arduino utilizzano impostazioni predefinite in fase di compilazione (nessuna azione necessaria).

Requisiti

  • Arduino ESP32 Core 3.x (testato con 3.0+)
  • Arduino IDE 2.x
  • Gli esempi sono ristrutturati in directory per-sketch per la compatibilità con Arduino IDE 2.x

Installazione della Libreria

Arduino IDE

  1. Scarica la libreria rbdimmerESP32 come archivio ZIP
  2. In Arduino IDE, seleziona: Sketch > Include Library > Add .ZIP Library
  3. Seleziona il file ZIP scaricato
  4. Riavvia Arduino IDE per completare l'installazione

Spiegazione del Funzionamento della Libreria

Preparazione:

  1. La libreria viene inizializzata usando rbdimmer_init()
  2. Il rilevatore di attraversamento zero viene registrato usando rbdimmer_register_zero_cross()
  3. Il canale dimmer viene creato usando rbdimmer_create_channel()

Controllo dello Sbiadimento:

  • Impostazione del livello di attenuazione con rbdimmer_set_level(). Il livello di attenuazione è impostato nell'intervallo 0(OFF) ~ 100(ON)
  • Transizione fluida del livello di attenuazione con rbdimmer_set_level_transition(). Transizione fluida dal livello corrente al livello impostato in un periodo di tempo (in millisecondi, 1s=1000ms)

Strutture Dati

rbdimmer_config_t

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

Enumerazioni

rbdimmer_curve_t

Tipi di curve di livello:

c
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

Risposte della funzione libreria:

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

Costanti e Macro

Costanti nel file rbdimmerESP32.h. Puoi modificare questi parametri:

c
#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 100             // Minimum delay (us) — raised from 50 in v2.0.0

Funzioni

Inizializzazione e Configurazione

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

Controllo dello Sbiadimento

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

Query di Informazioni

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

Linee Guida Passo dopo Passo

Passaggi di implementazione per libreria iniziale, registrazione della fase, rilevatore zero-cross, canale di attenuazione e controllo di attenuazione:

1. Definisci libreria e pin

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. Crea oggetto dimmer

Per ogni dimmer, crea un oggetto:

cpp
rbdimmer_channel_t* dimmer_channel = NULL;

3. Inizializzazione della libreria dimmer

La funzione restituisce uno stato:

cpp
rbdimmer_init();

4. Rilevatore zero-cross e registrazione della fase

La funzione restituisce uno stato:

cpp
rbdimmer_register_zero_cross(ZERO_CROSS_PIN, PHASE_NUM, 0);

5. Configurazione e creazione del canale 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. Operazione di attenuazione

cpp
rbdimmer_set_level(dimmer_channel, level);

7. Transizioni di attenuazione fluida

cpp
rbdimmer_set_level_transition(dimmer_channel, 0, 5000);

Soluzioni

Sistemi Dimmer Multi-Canale

La libreria supporta più canali di attenuazione indipendenti. Il numero di canali è limitato nelle impostazioni della libreria nel file rbdimmerESP32.h. Ogni canale di attenuazione deve avere un pin di output separato.

Esempio di creazione di un sistema a due canali:

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

Utilizzo delle Funzioni di Callback di Interruzione

Le funzioni di callback consentono di sincronizzare il codice con gli eventi di zero-crossing. Questo è utile per attività che richiedono una sincronizzazione precisa con la rete AC.

Esempio di registrazione e gestore attività 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 ...
}

Sistemi Multi-Fase

Per i sistemi trifase, un rilevatore di attraversamento zero separato deve essere registrato per ogni 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 ...
}

Monitoraggio Operativo

Per il debug, puoi utilizzare le funzioni di libreria integrate:

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

Risoluzione dei Problemi: Sfarfallio

v2.0.0 include diversi fix mirati per i problemi di sfarfallio comuni:

Sintomo Causa Fix v2.0.0
Sfarfallio generale / picchi casuali Il picco di accensione TRIAC ri-attiva il rilevatore zero-cross Porta di rumore zero-cross: ZC_DEBOUNCE_US = finestra di mascheramento di 3000 us dopo ogni zero-cross, ignorando i bordi falsi
Sfarfallio al 100% di luminosità Ritardo di accensione troppo vicino al prossimo zero-cross MIN_DELAY_US aumentato a 100 us; i livelli >= 100% vengono mappati internamente al 99% in modo che il TRIAC riceva sempre un impulso di gate appropriato
Sfarfallio sotto il 3% di luminosità TRIAC non può sostenere la corrente a angoli di conduzione molto piccoli I livelli sotto LEVEL_MIN vengono trattati come completamente OFF, evitando il disparo parziale inaffidabile
Jitter multi-canale / sfarfallio I canali vengono attivati con timer indipendenti causando conflitti di pianificazione ISR a due passate: tutti i canali sulla stessa fase vengono ordinati per ritardo e attivati sequenzialmente in una catena di timer in ogni mezzo ciclo

Se riscontri ancora sfarfallio dopo l'aggiornamento, verifica che il tuo segnale hardware zero-cross sia pulito (senza oscillazione) e che il tuo carico sia compatibile con l'attenuazione fase-cut leading-edge (TRIAC).

Esempi Base per la Libreria AC Dimmer

Gli sketch di esempio si trovano in directory per-sketch in examples/arduino/:

Esempio Percorso
Controllo Dimmer Base examples/arduino/BasicDimmer/BasicDimmer.ino
Transizione di Luminosità examples/arduino/BasicTransition/BasicTransition.ino
Più Canali Dimmer examples/arduino/MultiDimmer/MultiDimmer.ino
Callback Zero-Cross examples/arduino/ZCCallBack/ZCCallBack.ino

Controllo Dimmer Base

Descrizione: L'esempio più semplice che mostra come controllare un dimmer AC con un livello di luminosità fisso.

File: examples/arduino/BasicDimmer/BasicDimmer.ino

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

Transizione di Luminosità

Mostra come creare transizioni fluide tra i livelli di luminosità.

File: examples/arduino/BasicTransition/BasicTransition.ino

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
}

Più Canali Dimmer

Controlla due canali dimmer separati indipendentemente.

File: examples/arduino/MultiDimmer/MultiDimmer.ino

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 Zero-Cross

Dimostra l'utilizzo di una funzione di callback con un'attività FreeRTOS per elaborare in modo sicuro gli eventi di zero-crossing, che possono essere utilizzati per la sincronizzazione con la forma d'onda AC senza aggiungere ritardo di esecuzione del codice al gestore di interruzione.

File: examples/arduino/ZCCallBack/ZCCallBack.ino

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);
}
  • Mantenere l'ISR (Interrupt Service Routine) estremamente breve - invia solo un messaggio a una coda
  • Spostare tutta la logica di elaborazione a un'attività FreeRTOS dedicata
  • Utilizzare i meccanismi FreeRTOS corretti per la comunicazione sicura tra ISR e attività
  • Prevenire eventuali problemi di temporizzazione nel rilevamento dello zero-crossing separando la gestione dell'interruzione dall'elaborazione

Questo approccio segue le migliori pratiche per i sistemi real-time in cui i gestori di interruzione devono essere il più brevi possibile per evitare di influenzare la temporizzazione e la responsività del sistema.

Guarda CHANGELOG.md per l'elenco completo delle modifiche in ogni release.

← Libreria Universale per ESP32 | Indice | Prossimo: - Guida framework ESP-IDF C e esempi. →

Novità in v2.0.0 Requisiti Installazione della Libreria Linee Guida Passo dopo Passo Soluzioni Risoluzione dei Problemi: Sfarfallio Esempi Base per la Libreria AC Dimmer