rbdimmerESP32 - Bibliothèque de régulation lumineuse AC professionnelle pour ESP32

v2.0.0 Modifications majeures : La structure interne des sources a été modifiée en modules src/internal/. Les exemples ont été restructurés en répertoires par esquisse (Arduino IDE 2.x). Kconfig.txt a été renommé en Kconfig. L'API publique est inchangée — aucune modification du code utilisateur requise.

Une bibliothèque de contrôle de régulation lumineuse AC professionnelle et haute performance pour les microcontrôleurs ESP32. Conçue pour la précision de synchronisation, l'efficacité matérielle, l'exploitation multi-phase et multi-canal avec support de divers types de charges, y compris les ampoules à incandescence, les régulateurs LED et les applications de contrôle moteur.

Caractéristiques principales

Optimisation du matériel

• Hardware Timer Integration: Uses ESP32's high-resolution timers for microsecond precision
• Architecture basée sur les interruptions : Surcharge CPU minimale avec gestion des interruptions matérielles
• Support multi-phase : Jusqu'à 4 phases AC indépendantes avec détection de passage à zéro individuelle
• Détection automatique de fréquence : Prend en charge les secteurs 50 Hz et 60 Hz avec auto-détection
• Placement ISR IRAM_ATTR : Tous les chemins critiques de synchronisation en IRAM pour une latence déterministe
• Distribution ESP_TIMER_ISR : Les rappels de minuteur sont distribués à partir du contexte ISR pour un jitter minimal
• Portail de bruit de passage à zéro : Le filtre d'antirebond validé par le matériel élimine les fausses déclenchements causés par les pics de commutation TRIAC

Commande avancée

• Plusieurs courbes de luminosité : Courbes linéaires, compensées RMS et logarithmiques pour différentes charges
• Transitions fluides : Transitions de luminosité non-bloquantes utilisant les tâches FreeRTOS
• Fonctionnement multi-canal : Contrôle jusqu'à 8 canaux de régulation indépendants simultanément
• Synchronisation en temps réel : Fonctionnement à verrouillage de phase avec la fréquence du secteur

Caractéristiques professionnelles

• Gestion d'erreurs complète : Codes d'erreur détaillés et informations de diagnostic
• Conception thread-safe : Compatibilité complète avec FreeRTOS et gestion appropriée des ressources
• Documentation complète : Documentation Doxygen complète avec exemples
• Support multi-plateforme : Fonctionne avec Arduino IDE et ESP-IDF

Architecture modulaire

v2.0.0 remplace l'implémentation monolithique à fichier unique par six modules internes :

Note : L'API du header public (rbdimmerESP32.h) est inchangée — le code utilisateur n'a pas besoin de modification.

Démarrage rapide

Installation Arduino IDE

1. Téléchargez la bibliothèque à partir de GitHub
2. Dans Arduino IDE : Sketch → Include Library → Add .ZIP Library
3. Sélectionnez le fichier ZIP téléchargé
4. Incluez dans votre esquisse :

#include 

Exemple d'utilisation de 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);
}

Configuration matérielle requise

Cartes supportées

• ESP32 DevKit : Toutes les variantes (ESP32-WROOM-32, ESP32-WROVER, etc.)
• ESP32-S2 : Variante monocore ESP32 avec OTG USB
• ESP32-S3 : Dual-core avec capacités IA améliorées et USB
• ESP32-C3 : Basé sur RISC-V, consommation ultra-faible
• ESP32-C6 : Support Wi-Fi 6 avec 802.11ax
• ESP32-H2 : Dédié aux applications Thread/Zigbee
• ESP32-P4 : Variante haute performance avec traitement amélioré
• ESP32-C2 : Optimisé pour les coûts avec connectivité essentielle
• Cartes tierces compatibles : Wemos D1 Mini ESP32, NodeMCU-32S, etc.

Matrice de compatibilité du framework

Matériel de régulation lumineuse

Cette bibliothèque est conçue pour fonctionner avec les modules de régulation lumineuse prééquipés qui incluent : - Circuit de détection de passage à zéro - Pilote TRIAC ou relais à semi-conducteurs - Isolement optique pour la sécurité - Dissipation thermique appropriée

⚠️ Avertissement de sécurité : La tension du secteur AC est dangereuse. Utilisez uniquement des modules de régulation certifiés avec isolement approprié.

Exemple de câblage

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)

Documentation

Guides spécifiques à la plateforme

• Guide Arduino : Configuration du framework Arduino et exemples
• Guide ESP-IDF : Configuration du framework ESP-IDF et exemples
• Aperçu complet de la bibliothèque : Documentation complète

Fonctionnalités avancées

Plusieurs courbes de luminosité

Choisissez la courbe optimale pour votre type de charge et la réponse visuelle souhaitée :

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

Caractéristiques détaillées des courbes :

1. Linéaire (RBDIMMER_CURVE_LINEAR) - Changement uniforme du délai d'angle de phase - Conversion directe pourcentage à délai - Adapté au contrôle moteur et aux applications simples - ⚠️ Note : La luminosité perçue n'est pas visuellement linéaire

2. RMS (RBDIMMER_CURVE_RMS) - Compense les caractéristiques RMS de l'AC sinusoïdal - Fournit un changement de puissance linéaire : Power ∝ Level² - Idéal pour les ampoules à incandescence et les charges résistives - Basé sur : angle = arccos(√(level/100))

3. Logarithmique (RBDIMMER_CURVE_LOGARITHMIC) - Compense la perception logarithmique de la luminosité - Fournit des changements de luminosité visuellement linéaires - Recommandé pour l'éclairage LED et les affichages - Basé sur : log₁₀(1 + 9×(level/100))

Optimisation des performances

Utilisation des minuteurs matériels

• ESP-Timer Integration: Uses ESP32's high-resolution software timers
• Précision à la microseconde : Précision de synchronisation ±1-10μs en charge normale
• Efficacité des ressources : 2 minuteurs par canal (délai + largeur d'impulsion)
• Placement IRAM : Code ISR critique placé en IRAM pour la vitesse

Optimisation des interruptions

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

Optimisation de la mémoire

• Tables précalculées : Courbes de luminosité calculées à l'initialisation
• Mise en cache efficace : Paramètres mis en cache pour réduire les calculs répétés
• Utilisation RAM minimale : ~200 octets par canal + ~1KB surcharge globale
• Optimisation Flash : ~32KB d'empreinte flash totale

Système de débogage et de journalisation

Activez la journalisation complète pour le développement et le dépannage :

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

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

Rappels en temps réel

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

Paramètres Kconfig

Quatre paramètres accordables pour les compilations ESP-IDF (Arduino utilise les valeurs par défaut au moment de la compilation) :

Cas d'utilisation

Domotique

• Contrôle intelligent de l'éclairage avec variation progressive
• Intégration avec des plates-formes IoT (Home Assistant, OpenHAB)
• Commande vocale et applications mobiles
• Surveillance et optimisation énergétiques

Applications commerciales

• Éclairage scénique et théâtral
• Ambiance restaurant et hospitalité
• Illumination d'affichage commercial
• Contrôle de processus industriel

Projets éducatifs

• Démonstrations d'électronique de puissance
• Expériences de commande de phase AC
• Apprentissage des systèmes temps réel
• Éducation à la programmation embarquée

Projets créatifs

• Contrôleurs de lampe personnalisés
• Effets lumineux Halloween/Noël
• Éclairage synchronisé à la musique
• Contrôle de ventilateur basé sur la température

Problèmes courants et solutions rapides

Scintillement général ou luminosité instable

Causes possibles : - Connexions AC Neutre/Phase incorrectes - Problèmes de signal du détecteur de passage à zéro - Les pics de commutation TRIAC déclenchent à nouveau la détection ZC - Charge CPU élevée ou conflits d'interruptions

Solutions rapides : - Le portail de bruit de passage à zéro v2.0.0 (ZC_DEBOUNCE_US = 3000µs) filtre automatiquement les redéclenchements de pics TRIAC - Essayez une courbe différente pour votre type de charge :

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

Scintillement à 100 % de luminosité

Cause : Délai minimum trop court ou niveau dépassant la plage sûre.

Correction dans v2.0.0 : MIN_DELAY_US augmenté de 50 à 100µs. Les niveaux à 100% ou au-dessus sont mappés à LEVEL_MAX (99%), prévenant les problèmes de plein allumage.

Dérive de synchronisation multi-canal

Cause : Les canaux s'arment à des moments légèrement différents pendant un seul événement ZC.

Correction dans v2.0.0 : ISR à deux passages — Le passage 1 réinitialise tous les GPIO, le passage 2 arme tous les minuteurs. Cela garantit que tous les canaux commencent à partir de la même ligne de base à chaque passage à zéro.

Scintillement en dessous de 3 % de luminosité

Cause : Le TRIAC ne peut pas se verrouiller de manière fiable à des angles de conduction très faibles.

Correction dans v2.0.0 : Les niveaux en dessous de LEVEL_MIN (3%) sont traités comme OFF, éliminant le scintillement erratique en bas de la plage de variation.

Problèmes de luminosité spécifiques à la charge

À 50 %, la lampe semble trop brillante/faible :

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

Aucune réponse du régulateur

Vérifiez la détection de passage à zéro :

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 de compilation CI

CI automatisée garantit que chaque commit se compile correctement sur toutes les plates-formes supportées :

• Arduino : arduino/compile-sketches@v1, Core 3.x, 4 exemples × 5 puces (ESP32, S2, S3, C3, C6)
• ESP-IDF : espressif/esp-idf-ci-action@v1, IDF v5.3/v5.4/v5.5 × 5 puces = 15 tâches
• test_app/ : Projet ESP-IDF minimal pour vérification de surface API au moment de la compilation

Plates-formes supportées

Framework Arduino

• Arduino IDE 2.x
• Intégration transparente avec les bibliothèques Arduino

Framework ESP-IDF

• ESP-IDF 5.3+ avec support CMake
• Fonctionnalités de développement professionnel

Outils de développement

• Visual Studio Code avec extension ESP-IDF
• CLion avec plugin ESP-IDF
• Eclipse CDT avec outils ESP-IDF
• Support de développement en ligne de commande

Caractéristiques de performance

Avantages de l'architecture ESP-Timer

• Implémentation logicielle : Permet de nombreux minuteurs simultanés
• Exécution basée sur file d'attente : Ordonnés par temps de déclenchement pour l'efficacité
• Surcharge faible : Un minuteur matériel unique sert tous les minuteurs logiciels
• Distribution ISR : Les rappels de minuteur sont distribués directement à partir du contexte ISR pour un jitter minimal

Limitations de performance

• Jitter du minuteur : ±10-50μs possible sous charge système élevée
• Contraintes de rappel : Ne doit pas bloquer l'exécution pendant de longues périodes
• Mise à l'échelle de la mémoire : Chaque canal nécessite ~200 octets RAM
• Limitations GPIO : Les broches disponibles varient selon la variante ESP32

Comparaison des bibliothèques

Contribution

Nous accueillons les contributions de la communauté ! Veuillez lire notre Guide de contribution pour :

• Directives de style de code
• Procédures de test
• Processus de demande d'extraction
• Modèles de signalement de problèmes
• Configuration de l'environnement de développement

Exemples

Support et communauté

Ressources officielles

• Site Web : https://rbdimmer.com
• Documentation : https://www.rbdimmer.com/docs/universal-library-for-esp32
• Catalogue matériel : https://www.rbdimmer.com/dimmers-pricing
• Galerie de projets : https://www.rbdimmer.com/blog/integration-guides-8

Support communautaire

• Forum : https://forum.rbdimmer.com
• Problèmes GitHub : Signaler les bugs et demander des fonctionnalités
• Discussions GitHub : Discussions communautaires et Q&A

Support professionnel

Pour les applications commerciales, support entreprise et développement personnalisé : - Email : [email protected] - Consultation technique : Disponible pour les projets complexes - Développement personnalisé : Solutions adaptées aux exigences spécifiques

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

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.

Informations de version

• Version actuelle : 2.0.0
• Date de sortie : 2026-03-23
• ESP-IDF minimum : 5.3+
• Noyau Arduino ESP32 : 3.x
• Arduino IDE : 2.x

Documentation dans d'autres langues

La documentation complète est disponible en 5 langues sur le site RBDimmer :

• English
• Русский (Russian)
• Deutsch (German)
• Español (Spanish)
• Italiano (Italian)

Projets connexes

• Modules matériels : Catalogue de matériel RBDimmer
• Exemples d'applications : Galerie de projets
• Documentation technique : Base de connaissances

Fait avec ❤️ par l'équipe RBDimmer

Contrôle de régulation lumineuse AC professionnelle pour la communauté créative