← Collegamento hardware | Indice | Avanti: Guida Arduino ed esempi →

Libreria universale per ESP32

Panoramica della libreria

La libreria per dimmer AC è una soluzione efficiente per controllare la luminosità di dispositivi a corrente alternata (AC) tramite un microcontrollore della famiglia ESP32. La libreria sfrutta le capacità hardware dell'ESP32, come il processing degli interrupt GPIO e i timer ad alta precisione, per controllare con esattezza il momento di attivazione del TRIAC in ogni semiciclo della corrente alternata.

Caratteristiche e vantaggi

• Compatibile con i framework Arduino, ESP-IDF ed ESPHome
• Compatibile con sistemi multifase
• Supporto per più canali di dimmerizzazione indipendenti
• Utilizzo minimo delle risorse del processore grazie agli interrupt hardware e ai timer ESP
• Controllo di luminosità ad alta precisione per dispositivi AC
• Diverse curve di regolazione della luminosità (lineare, RMS, logaritmica)
• Rilevamento automatico della frequenza di rete (50/60 Hz e altre)
• Transizioni fluide tra livelli di luminosità
• Supporto per funzioni callback per la sincronizzazione con altri eventi

Requisiti

Microcontrollore della famiglia ESP32

Compatibile con Arduino ESP32 Core (versione 2.0.0 o superiore):

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

Compatibile con ESP-IDF (5.0 o superiore):

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

Compatibile con ESPHome:

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

Framework: guide ed esempi

Documentazione disponibile

• Guida Arduino ed esempi
• Guida ESP-IDF ed esempi
• Guida ESPHome ed esempi

Specifiche funzionali

Selezione della curva di luminosità

La libreria supporta tre tipi di curve per la regolazione della luminosità:

Lineare (AC_DIMMER_CURVE_LINEAR)

• Variazione uniforme dell'angolo di ritardo
• Adatta ad applicazioni semplici
• La luminosità percepita non è lineare

RMS (AC_DIMMER_CURVE_RMS)

• Compensa la caratteristica RMS di un segnale sinusoidale
• Fornisce una variazione di potenza lineare
• Ideale per lampadine a incandescenza e carichi resistivi

Logaritmica (AC_DIMMER_CURVE_LOGARITHMIC)

• Compensa la percezione logaritmica della luminosità da parte dell'occhio umano
• Fornisce una variazione di luminosità visivamente lineare
• Consigliata per illuminazione LED

Transizioni fluide

Per creare transizioni fluide tra livelli di luminosità, utilizzare la funzione ac_dimmer_set_brightness_transition():

Sistemi multicanale

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

Utilizzo delle funzioni callback di interrupt

Le funzioni callback consentono di sincronizzare il codice con gli eventi di passaggio per lo zero. Utile per task che richiedono una sincronizzazione precisa con la rete AC.

Ottimizzazione e debug

Utilizzo ottimale delle risorse

Limitazioni degli ESP-Timer:

• La libreria usa esp_timer, che consente di creare più timer software
• Per ogni canale vengono usati 2 timer: uno per il ritardo e uno per la larghezza del impulso

Ottimizzazione degli interrupt:

• I gestori di interrupt sono mantenuti il più brevi possibile per ridurre il carico
• L'attributo IRAM_ATTR viene usato per collocare il codice del gestore in IRAM
• I calcoli complessi vengono eseguiti al di fuori dei gestori di interrupt

Prestazioni:

• Le tabelle precalcolate per le curve di luminosità riducono il tempo di calcolo
• La cache dei parametri riduce i calcoli ripetuti

Log:

La libreria dispone di un sistema di log avanzato. Per il debug del progetto, abilitare il logging delle operazioni delle funzioni della libreria sulla porta seriale.

Risoluzione dei problemi comuni

La lampada sfarfalla o la luminosità è instabile

Questo può verificarsi a livelli di dimmerizzazione da 0 a 8.

Cause e soluzioni:

• Connessione errata di neutro e fase AC: verificare la connessione della sorgente AC. Neutro a N, fase a AC-L IN
• Problemi con il rilevatore di passaggio per lo zero: verificare la forma d'onda del segnale e la soglia di trigger
• Architettura del microcontrollore ESP32 e Arduino core: compatibilità e priorità non ottimali del modulo ISR e del modulo timer a livello di Arduino Core
• Alto carico CPU: ridurre il numero di calcoli nel ciclo principale
• Conflitti di interrupt: assicurarsi che altre librerie non entrino in conflitto con gli interrupt

Luminosità errata per certi tipi di carico

Causa: al 50% di luminosità, la lampada appare troppo luminosa o troppo fioca

Soluzione: cambiare il tipo di curva di luminosità per il proprio carico

Il rilevatore di passaggio per lo zero non funziona

Il dimmer non risponde alla regolazione:

• Verificare la connessione del pin di passaggio per lo zero
• Assicurarsi che il segnale raggiunga l'ESP32
• Controllare la funzione ac_dimmer_get_frequency() — se restituisce 0, la frequenza di rete non è determinata

Informazioni tecniche

Principi di funzionamento del dimmer AC

Il controllo della potenza nei circuiti AC si basa sul principio della regolazione di fase tramite un TRIAC (tiristors).

Caratteristiche dell'ESP-Timer su ESP32

La libreria utilizza esp_timer per il controllo preciso dei ritardi:

Vantaggi dell'ESP-Timer:

• Risoluzione in microsecondi
• L'implementazione software consente di creare numerosi timer
• Basso overhead

Architettura dell'ESP-Timer:

• Un timer hardware per tutti i timer software
• Coda di timer ordinata per tempo di attivazione
• Le funzioni callback vengono chiamate nel contesto del task del timer

Limitazioni:

• Leggero jitter (±10-50 µs) sotto alto carico di sistema
• La funzione callback non deve bloccare l'esecuzione a lungo

Gestione degli interrupt

Interrupt di passaggio per lo zero:

• Generati al momento del passaggio per lo zero
• Viene usato il tipo di interrupt GPIO_INTR_POSEDGE (solo fronte di salita)
• Il gestore avvia i timer per tutti i canali attivi della fase corrispondente

Timer:

• Il primo timer viene avviato per il tempo di ritardo e attiva l'uscita
• Il secondo timer viene avviato per determinare la durata dell'impulso

Metodi di miglioramento della stabilità:

• I gestori di interrupt sono mantenuti il più brevi possibile e collocati in IRAM
• Le sezioni critiche proteggono i dati condivisi
• Calcoli minimi nei gestori di interrupt

← Collegamento hardware | Indice | Avanti: Guida Arduino ed esempi →