rbdimmerESP32 - Libreria Dimmer AC Professionale per ESP32

v2.0.0 Modifiche Critiche: La disposizione interna del codice è cambiata in moduli src/internal/. Gli esempi sono stati ristrutturati in directory per sketch (Arduino IDE 2.x). Kconfig.txt rinominato in Kconfig. L'API pubblica rimane invariata — nessuna modifica al codice utente necessaria.

Una libreria di controllo dimmer AC professionale e ad alte prestazioni per microcontrollori ESP32. Progettata per la precisione dei tempi, l'efficienza hardware, il funzionamento multifase e multicanale con supporto per vari tipi di carico inclusi lampadine a incandescenza, dimmer LED e applicazioni di controllo motori.

Caratteristiche Principali

Ottimizzazione Hardware

• Hardware Timer Integration: Uses ESP32's high-resolution timers for microsecond precision
• Architettura Basata su Interrupt: Overhead minimo della CPU con gestione hardware degli interrupt
• Supporto Multifase: Fino a 4 fasi AC indipendenti con rilevamento zero-crossing individuale
• Rilevamento Automatico Frequenza: Supporta sia 50Hz che 60Hz con auto-rilevamento
• Posizionamento ISR IRAM_ATTR: Tutti i percorsi critici per il timing in IRAM per latenza deterministica
• Dispatch ESP_TIMER_ISR: Callback timer inviati dal contesto ISR per jitter minimo
• Filtro Rumore Zero-Cross: Filtro debounce validato hardware elimina false trigger dai picchi di commutazione TRIAC

Controllo Avanzato

• Curve di Luminosità Multiple: Lineare, compensata RMS e logaritmica per carichi diversi
• Transizioni Fluide: Transizioni di luminosità non bloccanti utilizzando task FreeRTOS
• Funzionamento Multicanale: Controllare fino a 8 canali dimmer indipendenti simultaneamente
• Sincronizzazione Real-Time: Funzionamento phase-locked con la frequenza della rete

Funzionalità Professionali

• Gestione Errori Completa: Codici di errore dettagliati e informazioni diagnostiche
• Design Thread-Safe: Compatibilità completa FreeRTOS con gestione corretta delle risorse
• Documentazione Estesa: Documentazione Doxygen completa con esempi
• Supporto Cross-Platform: Funziona con Arduino IDE e ESP-IDF

Architettura Modulare

v2.0.0 sostituisce l'implementazione monolitica a file singolo con sei moduli interni:

Nota: L'API dell'header pubblico (rbdimmerESP32.h) è invariata — il codice utente non necessita di modifiche.

Quick Start

Installazione Arduino IDE

1. Scaricare la libreria da GitHub
2. In Arduino IDE: Sketch → Include Library → Add .ZIP Library
3. Selezionare il file ZIP scaricato
4. Includere nello sketch:

#include 

Esempio di Utilizzo di Base

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

Requisiti Hardware

Schede Supportate

• ESP32 DevKit: Tutte le varianti (ESP32-WROOM-32, ESP32-WROVER, ecc.)
• ESP32-S2: Variante single-core ESP32 con USB OTG
• ESP32-S3: Dual-core con capacità AI migliorate e USB
• ESP32-C3: Basato su RISC-V, consumo ultra-basso
• ESP32-C6: Supporto Wi-Fi 6 con 802.11ax
• ESP32-H2: Dedicato per applicazioni Thread/Zigbee
• ESP32-P4: Variante ad alte prestazioni con elaborazione migliorata
• ESP32-C2: Ottimizzato per costi con connettività essenziale
• Schede Compatibili di Terze Parti: Wemos D1 Mini ESP32, NodeMCU-32S, ecc.

Matrice Compatibilità Framework

Hardware Dimmer

Questa libreria è progettata per funzionare con moduli dimmer pre-costruiti che includono: - Circuito di rilevamento zero-crossing - Driver TRIAC o relè allo stato solido - Isolamento ottico per la sicurezza - Dissipazione termica appropriata

⚠️ Avvertenza di Sicurezza: La tensione della rete AC è pericolosa. Utilizzare solo moduli dimmer certificati con isolamento appropriato.

Esempio di Collegamento

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)

Documentazione

Guide Specifiche per Piattaforma

• Arduino Guide: Arduino Framework Setup and Examples
• ESP-IDF Guide: ESP-IDF Framework Setup and Examples
• Complete Library Overview: Comprehensive Documentation

Funzionalità Avanzate

Curve di Luminosità Multiple

Scegliere la curva ottimale per il tipo di carico e la risposta visiva desiderata:

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

Caratteristiche Dettagliate della Curva:

1. Lineare (RBDIMMER_CURVE_LINEAR) - Cambio uniforme nel ritardo dell'angolo di fase - Conversione diretta percentuale a ritardo - Adatto per il controllo motori e applicazioni semplici - ⚠️ Nota: La luminosità percepita non è visivamente lineare

2. RMS (RBDIMMER_CURVE_RMS) - Compensa le caratteristiche RMS dell'AC sinusoidale - Fornisce cambio di potenza lineare: Power ∝ Level² - Ideale per lampadine a incandescenza e carichi resistivi - Basato su: angle = arccos(√(level/100))

3. Logaritmica (RBDIMMER_CURVE_LOGARITHMIC) - Compensa la percezione logaritmica della luminosità - Fornisce cambiamenti di luminosità visivamente lineari - Consigliato per illuminazione LED e display - Basato su: log₁₀(1 + 9×(level/100))

Ottimizzazione delle Prestazioni

Utilizzo Timer Hardware

• ESP-Timer Integration: Uses ESP32's high-resolution software timers
• Precisione nel Microsecondo: Accuratezza del timing ±1-10μs con carico normale
• Efficiente in Risorse: 2 timer per canale (delay + pulse width)
• Posizionamento IRAM: Codice ISR critico posizionato in IRAM per velocità

Ottimizzazione Interrupt

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

Ottimizzazione Memoria

• Tabelle Pre-calcolate: Curve di luminosità calcolate all'inizializzazione
• Caching Efficiente: Parametri memorizzati nella cache per ridurre i calcoli ripetuti
• Uso RAM Minimo: ~200 byte per canale + ~1KB overhead globale
• Ottimizzazione Flash: ~32KB footprint flash totale

Sistema Debug e Logging

Abilita il logging completo per sviluppo e risoluzione dei problemi:

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

Controllo Multicanale

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

Callback Real-Time

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

Parametri Kconfig

Quattro parametri regolabili per build ESP-IDF (Arduino utilizza valori predefiniti in fase di compilazione):

Casi d'Uso

Automazione Domestica

• Controllo illuminazione intelligente con dimming fluido
• Integrazione con piattaforme IoT (Home Assistant, OpenHAB)
• Controllo vocale e app per smartphone
• Monitoraggio e ottimizzazione energetica

Applicazioni Commerciali

• Illuminazione scenica e teatrale
• Atmosfera ristorazione e ospitalità
• Illuminazione display retail
• Controllo processo industriale

Progetti Educativi

• Dimostrazioni di elettronica di potenza
• Esperimenti di controllo fase AC
• Apprendimento sistemi real-time
• Educazione programmazione embedded

Progetti Maker

• Controllori lampada personalizzati
• Effetti luci Halloween/Natale
• Illuminazione sincronizzata con musica
• Controllo ventilatore basato su temperatura

Problemi Comuni e Soluzioni Rapide

Sfarfallio Generale o Luminosità Instabile

Possibili Cause: - Connessioni Neutro/Linea AC errate - Problemi di segnale rilevatore zero-crossing - Picchi di commutazione TRIAC che retriggerano il rilevamento ZC - Carico CPU elevato o conflitti interrupt

Correzioni Rapide: - Il filtro rumore zero-cross v2.0.0 (ZC_DEBOUNCE_US = 3000µs) filtra automaticamente i retrrigger di picchi TRIAC - Provare curva diversa per il tipo di carico:

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

Sfarfallio al 100% di Luminosità

Causa: Ritardo minimo troppo corto, o livello che supera l'intervallo sicuro.

Correzione in v2.0.0: MIN_DELAY_US aumentato da 50 a 100µs. I livelli al 100% o superiori sono mappati a LEVEL_MAX (99%), prevenendo glitch a tutto-on.

Sfasamento Sincronizzazione Multicanale

Causa: Canali armati in momenti leggermente diversi all'interno di un singolo evento ZC.

Correzione in v2.0.0: ISR two-pass — Pass 1 resetta tutti i GPIO, Pass 2 arma tutti i timer. Questo garantisce che tutti i canali inizino dallo stesso baseline su ogni zero-crossing.

Sfarfallio al di Sotto del 3% di Luminosità

Causa: TRIAC non può affidabilmente latching ad angoli di conduzione molto bassi.

Correzione in v2.0.0: Livelli al di sotto di LEVEL_MIN (3%) sono trattati come OFF, eliminando sfarfallio erratico nella parte inferiore dell'intervallo di dimming.

Problemi di Luminosità Specifici del Carico

All'impostazione 50%, la lampada appare troppo luminosa/scura:

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

Nessuna Risposta Dimmer

Controllare il rilevamento zero-crossing:

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

Matrice Build CI

CI automatizzato assicura che ogni commit si compili correttamente su tutte le piattaforme supportate:

• Arduino: arduino/compile-sketches@v1, Core 3.x, 4 esempi × 5 chip (ESP32, S2, S3, C3, C6)
• ESP-IDF: espressif/esp-idf-ci-action@v1, IDF v5.3/v5.4/v5.5 × 5 chip = 15 job
• test_app/: Progetto ESP-IDF minimo per verifica superficie API in fase di compilazione

Piattaforme Supportate

Framework Arduino

• Arduino IDE 2.x
• Integrazione senza soluzione di continuità con le librerie Arduino

Framework ESP-IDF

• ESP-IDF 5.3+ con supporto CMake
• Funzionalità di sviluppo professionale

Strumenti di Sviluppo

• Visual Studio Code con estensione ESP-IDF
• CLion con plugin ESP-IDF
• Eclipse CDT con strumenti ESP-IDF
• Supporto sviluppo da riga di comando

Caratteristiche delle Prestazioni

Vantaggi Architettura ESP-Timer

• Implementazione Software: Consente numerosi timer concorrenti
• Esecuzione Basata su Code: Ordinata per tempo di trigger per efficienza
• Overhead Basso: Un singolo timer hardware serve tutti i timer software
• Dispatch ISR: Callback timer inviati direttamente dal contesto ISR per jitter minimo

Limitazioni Prestazioni

• Jitter Timer: ±10-50μs possibile sotto carico elevato del sistema
• Vincoli Callback: Non dovrebbe bloccare l'esecuzione per periodi estesi
• Scaling Memoria: Ogni canale richiede ~200 byte RAM
• Limitazioni GPIO: I pin disponibili variano per variante ESP32

Confronto Librerie

Contribuire

Accogliamo i contributi dalla comunità! Si prega di leggere la nostra Guida ai Contributi per:

• Linee guida di stile del codice
• Procedure di test
• Processo di pull request
• Modelli di segnalazione di problemi
• Setup dell'ambiente di sviluppo

Esempi

Supporto e Comunità

Risorse Ufficiali

• Sito Web: https://rbdimmer.com
• Documentazione: https://www.rbdimmer.com/docs/universal-library-for-esp32
• Catalogo Hardware: https://www.rbdimmer.com/dimmers-pricing
• Galleria Progetti: https://www.rbdimmer.com/blog/integration-guides-8

Supporto Comunità

• Forum: https://forum.rbdimmer.com
• GitHub Issues: Segnalare bug e richiedere funzionalità
• GitHub Discussions: Discussioni della comunità e Q&A

Supporto Professionale

Per applicazioni commerciali, supporto aziendale e sviluppo personalizzato: - Email: [email protected] - Consulenza Tecnica: Disponibile per progetti complessi - Sviluppo Personalizzato: Soluzioni personalizzate per requisiti specifici

Licenza

Questo progetto è concesso in licenza secondo la Licenza MIT - vedere il file LICENSE per i dettagli.

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.

Informazioni Versione

• Versione Attuale: 2.0.0
• Data di Rilascio: 2026-03-23
• ESP-IDF Minimo: 5.3+
• Arduino ESP32 Core: 3.x
• Arduino IDE: 2.x

Documentazione in Altre Lingue

La documentazione completa è disponibile in 5 lingue sul sito web di RBDimmer:

• English
• Русский (Russian)
• Français (French)
• Deutsch (German)
• Español (Spanish)

Progetti Correlati

• Moduli Hardware: Catalogo Hardware RBDimmer
• Esempi Applicazioni: Galleria Progetti
• Documentazione Tecnica: Knowledge Base

Realizzato con ❤️ dal Team RBDimmer

Controllo dimmer AC professionale per la comunità maker