Référence d'API rbdimmerESP32

Note: Library GitHub: https://github.com/robotdyn-dimmer/rbdimmerESP32

Mise à jour pour v2.0.0 -- l'API publique est inchangée, mais l'architecture interne est entièrement modulaire.

Aperçu

La bibliothèque rbdimmerESP32 fournit une API complète pour contrôler les variateurs AC avec des microcontrôleurs ESP32. L'API est conçue en tenant compte de la sécurité, des performances et de la facilité d'utilisation, offrant une intégration de minuterie matérielle et un fonctionnement piloté par interruption.

Principes de conception clés

Thread-Safe : Toutes les fonctions sont sûres à appeler à partir de plusieurs tâches FreeRTOS
Optimisée pour le matériel : Utilise les minuteries matérielles ESP32 pour une précision à la microseconde
Gestion des ressources : Nettoyage automatique et gestion des erreurs
Extensible : Support pour plusieurs phases et canaux
Modulaire (v2.0.0) : L'architecture interne est entièrement modulaire -- le moteur de courbe, le backend de minuterie et le détecteur de passage à zéro sont des composants indépendants

Types de données

Types opaques

`rbdimmer_channel_t`

typedef struct rbdimmer_channel_s rbdimmer_channel_t;

Poignée opaque représentant un canal de variateur. Toutes les opérations sur le canal utilisent cette poignée.

Notes d'utilisation : - Créé par rbdimmer_create_channel() - Doit être correctement détruit avec rbdimmer_delete_channel() - Ne peut pas être copié ou sérialisé

Structures de configuration

`rbdimmer_config_t`

typedef struct {
    uint8_t gpio_pin;                 // Output signal pin
    uint8_t phase;                    // Phase number (for multi-phase systems)
    uint8_t initial_level;            // Initial level percentage (0-100)
    rbdimmer_curve_t curve_type;      // Level curve type
} rbdimmer_config_t;

Structure de configuration pour créer des canaux de variateur.

Fields: - gpio_pin: GPIO pin connected to the dimmer's gate control (0-39) - phase: Phase identifier (0-3) - must be registered first - initial_level: Starting brightness level (0-100%) - curve_type: Brightness curve algorithm

Exemple :

rbdimmer_config_t config = {
    .gpio_pin = 4,
    .phase = 0,
    .initial_level = 50,
    .curve_type = RBDIMMER_CURVE_RMS
};

Énumérations

`rbdimmer_curve_t`

typedef enum {
    RBDIMMER_CURVE_LINEAR,        // Linear curve (no RMS consideration)
    RBDIMMER_CURVE_RMS,           // RMS-compensated curve
    RBDIMMER_CURVE_LOGARITHMIC,   // Logarithmic curve (for LEDs)
    RBDIMMER_CURVE_CUSTOM         // Custom curve (reserved)
} rbdimmer_curve_t;

Définit le type de courbe de luminosité pour le calcul de puissance.

Types de courbes : - LINEAR : Conversion directe de pourcentage en angle de phase - RMS : Compensée en puissance pour les charges résistives (ampoules à incandescence) - LOGARITHMIC : Linéaire perceptuellement pour les charges LED - CUSTOM : Réservé pour une future implémentation de courbe personnalisée

Limitation de niveau (v2.0.0) : Tous les calculs de courbe appliquent les limites LEVEL_MIN et LEVEL_MAX. Les niveaux >= 100% sont limités à RBDIMMER_LEVEL_MAX (99% par défaut). Les niveaux inférieurs à RBDIMMER_LEVEL_MIN (3% par défaut) retournent un délai = 0, ce qui signifie que le canal est ÉTEINT. Cela évite une conduction TRIAC peu fiable à des angles de conduction proches de zéro ou proches de la conduction complète.

`rbdimmer_err_t`

typedef enum {
    RBDIMMER_OK = 0,                  // Operation completed successfully
    RBDIMMER_ERR_INVALID_ARG,         // Invalid argument
    RBDIMMER_ERR_NO_MEMORY,           // Memory allocation failed
    RBDIMMER_ERR_NOT_FOUND,           // Object not found
    RBDIMMER_ERR_ALREADY_EXIST,       // Object already exists
    RBDIMMER_ERR_TIMER_FAILED,        // Timer initialization failed
    RBDIMMER_ERR_GPIO_FAILED          // GPIO initialization failed
} rbdimmer_err_t;

Codes d'erreur retournés par les fonctions de la bibliothèque.

`timer_state_t`

typedef enum {
    TIMER_STATE_IDLE,        // Waiting for zero-crossing
    TIMER_STATE_DELAY,       // Waiting for delay to finish
    TIMER_STATE_PULSE_ON,    // Pulse is active, waiting to turn off
} timer_state_t;

Énumération d'état de minuterie interne (utilisée en interne par la bibliothèque).

Constantes

Limites du système

#define RBDIMMER_MAX_PHASES 4                 // Maximum number of phases
#define RBDIMMER_MAX_CHANNELS 8               // Maximum number of channels

Constantes de temporisation

#define RBDIMMER_DEFAULT_PULSE_WIDTH_US 50    // Default pulse width in microseconds
#define RBDIMMER_MIN_DELAY_US 100             // Minimum delay for safe triac operation (was 50 in v1)

Porte de bruit de passage à zéro (v2.0.0)

#define RBDIMMER_ZC_DEBOUNCE_US 3000          // Noise gate window in microseconds

Après le déclenchement d'une interruption de passage à zéro, les interruptions ultérieures dans cette fenêtre sont ignorées. Cela élimine les faux déclenchements causés par le bruit électrique près du point de passage à zéro. La valeur par défaut de 3000 us fonctionne bien à la fois pour les réseaux 50 Hz et 60 Hz (la demi-période est de 8333 us à 60 Hz et 10000 us à 50 Hz, donc 3 ms est bien en dessous de l'une ou l'autre).

Constantes de limite de niveau (v2.0.0)

#define RBDIMMER_LEVEL_MIN 3                  // Levels below this -> OFF (delay = 0)
#define RBDIMMER_LEVEL_MAX 99                 // Levels above this -> capped to this value

Ces constantes définissent la plage de fonctionnement effective pour tous les calculs de courbe :

RBDIMMER_LEVEL_MIN (3%) : Demander un niveau inférieur à ce seuil produit un délai de 0, ce qui signifie que le TRIAC ne s'active jamais et le canal est complètement ÉTEINT. Cela évite une conduction partielle peu fiable avec des rapports cycliques très faibles.
RBDIMMER_LEVEL_MAX (99%) : Demander un niveau de 100% ou supérieur est limité à cette valeur. Cela garantit qu'un délai minimal est toujours appliqué, empêchant l'impulsion TRIAC de chevaucher le point de passage à zéro.

Configurabilité : Dans les projets ESP-IDF, ces constantes peuvent être remplacées via Kconfig (menuconfig). Dans les projets Arduino, elles agissent comme des valeurs par défaut au moment de la compilation et peuvent être redéfinies avant d'inclure l'en-tête de la bibliothèque.

Constantes de fréquence

#define RBDIMMER_DEFAULT_FREQUENCY 0          // Auto-detect frequency
#define RBDIMMER_FREQUENCY_MIN 45             // Minimum allowed frequency
#define RBDIMMER_FREQUENCY_MAX 65             // Maximum allowed frequency
#define RBDIMMER_MEASURE_CYCLES 10            // Number of cycles for measurement

Fonctions d'initialisation

`rbdimmer_init()`

rbdimmer_err_t rbdimmer_init(void);

Initialise la bibliothèque rbdimmerESP32. Doit être appelée avant toute autre fonction de la bibliothèque.

Retour : - RBDIMMER_OK : Initialisation réussie - RBDIMMER_ERR_NO_MEMORY : Allocation mémoire échouée

Exemple :

void setup() {
    rbdimmer_err_t err = rbdimmer_init();
    if (err != RBDIMMER_OK) {
        Serial.println("Failed to initialize rbdimmer library");
        return;
    }
    Serial.println("rbdimmer initialized successfully");
}

Notes : - Initialise les structures de données internes - Prépare les tables de consultation pour les courbes de luminosité - Doit être appelée depuis la tâche principale / fonction de configuration

`rbdimmer_deinit()`

rbdimmer_err_t rbdimmer_deinit(void);

Désinitialise la bibliothèque et libère toutes les ressources.

Retour : - RBDIMMER_OK : Désinitialisation réussie

Exemple :

void cleanup() {
    rbdimmer_deinit();
    Serial.println("Library deinitialized");
}

Notes : - Supprime automatiquement tous les canaux - Supprime tous les gestionnaires d'interruption - Libère les ressources GPIO - Appelez avant le redémarrage du système ou la mise en veille profonde

Gestion du passage à zéro

`rbdimmer_register_zero_cross()`

rbdimmer_err_t rbdimmer_register_zero_cross(uint8_t pin, uint8_t phase, uint16_t frequency);

Enregistre un détecteur de passage à zéro pour la synchronisation AC.

Paramètres : - pin : Broche GPIO connectée au détecteur de passage à zéro (0-39) - phase : Identificateur de phase (0-3) - frequency : Fréquence réseau prévue en Hz (0 pour détection automatique, 50, 60)

Retour : - RBDIMMER_OK : Enregistrement réussi - RBDIMMER_ERR_INVALID_ARG : Numéro de broche ou de phase invalide - RBDIMMER_ERR_ALREADY_EXIST : Phase déjà enregistrée - RBDIMMER_ERR_NO_MEMORY : Nombre maximum de phases atteint - RBDIMMER_ERR_GPIO_FAILED : Configuration GPIO échouée

Exemple :

// Auto-detect frequency on phase 0
rbdimmer_err_t err = rbdimmer_register_zero_cross(2, 0, 0);
if (err == RBDIMMER_OK) {
    Serial.println("Zero-cross detector registered on pin 2");
}
// Fixed 60Hz frequency on phase 1
rbdimmer_register_zero_cross(3, 1, 60);

Notes : - Doit être appelée avant de créer des canaux sur la même phase - La broche sera configurée comme entrée avec interruption sur front montant - La fréquence 0 active la détection automatique (recommandée) - Chaque phase nécessite un détecteur de passage à zéro séparé

Porte de bruit (v2.0.0) : Après chaque passage à zéro détecté, l'ISR ignore les interruptions ultérieures sur la même phase pendant RBDIMMER_ZC_DEBOUNCE_US microsecondes (3000 par défaut). Cela supprime les faux déclenchements causés par le bruit, la résonance ou les signaux de passage à zéro à montée lente. La fenêtre de rebond est appliquée par phase, donc les systèmes multi-phases sont traités indépendamment.

Gestion des canaux

`rbdimmer_create_channel()`

rbdimmer_err_t rbdimmer_create_channel(rbdimmer_config_t* config, rbdimmer_channel_t** channel);

Crée un nouveau canal de variateur avec une configuration spécifiée.

Paramètres : - config : Pointeur vers la structure de configuration - channel : Pointeur pour stocker la poignée du canal créé

Retour : - RBDIMMER_OK : Canal créé avec succès - RBDIMMER_ERR_INVALID_ARG : Configuration invalide ou pointeurs NULL - RBDIMMER_ERR_NOT_FOUND : Phase référencée non enregistrée - RBDIMMER_ERR_NO_MEMORY : Allocation mémoire échouée ou nombre maximum de canaux atteint - RBDIMMER_ERR_GPIO_FAILED : Configuration GPIO échouée - RBDIMMER_ERR_TIMER_FAILED : Création de minuterie échouée

Exemple :

rbdimmer_channel_t* my_channel;
rbdimmer_config_t config = {
    .gpio_pin = 4,
    .phase = 0,
    .initial_level = 0,
    .curve_type = RBDIMMER_CURVE_RMS
};
rbdimmer_err_t err = rbdimmer_create_channel(&config, &my_channel);
if (err == RBDIMMER_OK) {
    Serial.println("Channel created successfully");
}

Notes : - La broche GPIO sera configurée comme sortie - Le canal démarre en état actif - Deux minuteries matérielles sont allouées par canal - Le niveau initial est appliqué immédiatement

`rbdimmer_delete_channel()`

rbdimmer_err_t rbdimmer_delete_channel(rbdimmer_channel_t* channel);

Supprime un canal de variateur et libère toutes les ressources associées.

Paramètres : - channel : Poignée du canal à supprimer

Retour : - RBDIMMER_OK : Canal supprimé avec succès - RBDIMMER_ERR_INVALID_ARG : Poignée de canal NULL - RBDIMMER_ERR_NOT_FOUND : Canal non trouvé dans le gestionnaire

Exemple :

rbdimmer_err_t err = rbdimmer_delete_channel(my_channel);
if (err == RBDIMMER_OK) {
    my_channel = NULL; // Prevent accidental reuse
    Serial.println("Channel deleted successfully");
}

Notes : - Arrête toutes les minuteries en cours d'exécution - Définit la sortie GPIO sur LOW - Libère la mémoire allouée - La poignée du canal devient invalide après suppression

Contrôle du niveau

`rbdimmer_set_level()`

rbdimmer_err_t rbdimmer_set_level(rbdimmer_channel_t* channel, uint8_t level_percent);

Définit immédiatement le niveau de luminosité d'un canal de variateur.

Paramètres : - channel : Poignée du canal cible - level_percent : Niveau de luminosité (0-100%)

Retour : - RBDIMMER_OK : Niveau défini avec succès - RBDIMMER_ERR_INVALID_ARG : Poignée de canal NULL

Exemple :

// Set to 50% brightness
rbdimmer_set_level(my_channel, 50);
// Turn off
rbdimmer_set_level(my_channel, 0);
// Full brightness (clamped to LEVEL_MAX = 99%)
rbdimmer_set_level(my_channel, 100);

Notes : - Les modifications de niveau prennent effet au prochain passage à zéro - Les valeurs >= 100 sont limitées à RBDIMMER_LEVEL_MAX (99%) - Les valeurs inférieures à RBDIMMER_LEVEL_MIN (3%) entraînent l'extinction du canal (délai = 0) - Niveau 0 = complètement éteint - Thread-safe - peut être appelée depuis n'importe quelle tâche

`rbdimmer_set_level_transition()`

rbdimmer_err_t rbdimmer_set_level_transition(rbdimmer_channel_t* channel, uint8_t level_percent, uint32_t transition_ms);

Définit le niveau de luminosité avec une transition en douceur au fil du temps.

Paramètres : - channel : Poignée du canal cible - level_percent : Niveau de luminosité cible (0-100%) - transition_ms : Durée de transition en millisecondes

Retour : - RBDIMMER_OK : Transition démarrée avec succès - RBDIMMER_ERR_INVALID_ARG : Poignée de canal NULL - RBDIMMER_ERR_NO_MEMORY : Échec de création de la tâche de transition

Exemple :

// Fade to 75% over 3 seconds
rbdimmer_set_level_transition(my_channel, 75, 3000);
// Quick fade to off over 500ms
rbdimmer_set_level_transition(my_channel, 0, 500);

Notes : - Crée une tâche FreeRTOS pour des transitions en douceur - Non-bloquant - retour immédiatement - La durée de transition minimale est de 50 ms - Les transitions plus courtes que 50 ms utilisent un paramétrage immédiat - Plusieurs transitions peuvent s'exécuter simultanément sur différents canaux - Le niveau cible est soumis à la même limitation LEVEL_MIN / LEVEL_MAX que rbdimmer_set_level()

Fonctions de configuration

`rbdimmer_set_curve()`

rbdimmer_err_t rbdimmer_set_curve(rbdimmer_channel_t* channel, rbdimmer_curve_t curve_type);

Définit le type de courbe de luminosité pour un canal.

Paramètres : - channel : Poignée du canal cible - curve_type : Type de courbe désiré

Retour : - RBDIMMER_OK : Courbe définie avec succès - RBDIMMER_ERR_INVALID_ARG : Poignée de canal NULL

Exemple :

// For incandescent bulbs
rbdimmer_set_curve(my_channel, RBDIMMER_CURVE_RMS);
// For LED strips
rbdimmer_set_curve(my_channel, RBDIMMER_CURVE_LOGARITHMIC);
// For motor control
rbdimmer_set_curve(my_channel, RBDIMMER_CURVE_LINEAR);

Notes : - La modification prend effet au prochain passage à zéro - Les différentes courbes optimisent pour différents types de charge - Peut être modifiée pendant l'opération sans redémarrage - Toutes les courbes appliquent les limites LEVEL_MIN / LEVEL_MAX

`rbdimmer_set_active()`

rbdimmer_err_t rbdimmer_set_active(rbdimmer_channel_t* channel, bool active);

Active ou désactive un canal de variateur.

Paramètres : - channel : Poignée du canal cible - active : true pour activer, false pour désactiver

Retour : - RBDIMMER_OK : État modifié avec succès - RBDIMMER_ERR_INVALID_ARG : Poignée de canal NULL

Exemple :

// Enable channel
rbdimmer_set_active(my_channel, true);
// Disable channel (output goes to 0)
rbdimmer_set_active(my_channel, false);

Notes : - Les canaux désactivés ne consomment pas de temps CPU - La sortie est immédiatement mise à LOW en cas de désactivation - La configuration du canal est conservée en cas de désactivation - La réactivation reprend l'opération précédente

Récupération d'informations

`rbdimmer_get_level()`

uint8_t rbdimmer_get_level(rbdimmer_channel_t* channel);

Obtient le niveau de luminosité actuel d'un canal.

Paramètres : - channel : Poignée du canal à interroger

Retour : - Niveau de luminosité actuel (0-100%), ou 0 si le canal est NULL

Exemple :

uint8_t current_level = rbdimmer_get_level(my_channel);
Serial.printf("Current brightness: %d%%\n", current_level);

`rbdimmer_get_frequency()`

uint16_t rbdimmer_get_frequency(uint8_t phase);

Obtient la fréquence réseau mesurée pour une phase spécifique.

Paramètres : - phase : Numéro de phase à interroger (0-3)

Retour : - Fréquence mesurée en Hz, ou 0 si non mesurée ou phase non trouvée

Exemple :

uint16_t freq = rbdimmer_get_frequency(0);
if (freq > 0) {
    Serial.printf("Mains frequency: %d Hz\n", freq);
} else {
    Serial.println("Frequency not measured yet");
}

Notes : - Retourne 0 pendant la période de mesure initiale - La détection de fréquence prend environ 20 cycles AC - Utile pour la surveillance de la qualité de l'électricité

`rbdimmer_is_active()`

bool rbdimmer_is_active(rbdimmer_channel_t* channel);

Vérifie si un canal est actuellement actif.

Paramètres : - channel : Poignée du canal à interroger

Retour : - true si le canal est actif, false s'il est inactif ou NULL

Exemple :

if (rbdimmer_is_active(my_channel)) {
    Serial.println("Channel is active");
} else {
    Serial.println("Channel is inactive");
}

`rbdimmer_get_curve()`

rbdimmer_curve_t rbdimmer_get_curve(rbdimmer_channel_t* channel);

Obtient le type de courbe actuel d'un canal.

Paramètres : - channel : Poignée du canal à interroger

Retour : - Type de courbe actuel, ou RBDIMMER_CURVE_LINEAR si le canal est NULL

Exemple :

rbdimmer_curve_t curve = rbdimmer_get_curve(my_channel);
switch(curve) {
    case RBDIMMER_CURVE_LINEAR:
        Serial.println("Using linear curve");
        break;
    case RBDIMMER_CURVE_RMS:
        Serial.println("Using RMS curve");
        break;
    case RBDIMMER_CURVE_LOGARITHMIC:
        Serial.println("Using logarithmic curve");
        break;
}

`rbdimmer_get_delay()`

uint32_t rbdimmer_get_delay(rbdimmer_channel_t* channel);

Obtient le paramètre de délai actuel en microsecondes.

Paramètres : - channel : Poignée du canal à interroger

Retour : - Délai actuel en microsecondes, ou 0 si le canal est NULL

Exemple :

uint32_t delay_us = rbdimmer_get_delay(my_channel);
Serial.printf("Current delay: %d microseconds\n", delay_us);

Notes : - Utile pour le débogage et l'optimisation - Le délai varie selon le niveau de luminosité et le type de courbe - Mesuré à partir du passage à zéro jusqu'à l'activation du TRIAC - Retourne 0 quand le niveau est inférieur à RBDIMMER_LEVEL_MIN (canal ÉTEINT) - La valeur non-zéro minimale est RBDIMMER_MIN_DELAY_US (100 us)

Fonctions de rappel

`rbdimmer_set_callback()`

rbdimmer_err_t rbdimmer_set_callback(uint8_t phase, void (*callback)(void*), void* user_data);

Définit une fonction de rappel à appeler lors d'événements de passage à zéro.

Paramètres : - phase : Numéro de phase (0-3) - callback : Fonction à appeler lors du passage à zéro (NULL pour désactiver) - user_data : Pointeur de données utilisateur transmis à la fonction de rappel

Retour : - RBDIMMER_OK : Rappel défini avec succès - RBDIMMER_ERR_NOT_FOUND : Phase non enregistrée

Signature de la fonction de rappel :

void zero_cross_callback(void* user_data);

Exemple :

typedef struct {
    uint32_t cross_count;
    unsigned long last_time;
} callback_data_t;
callback_data_t cb_data = {0, 0};
void my_zero_cross_callback(void* user_data) {
    callback_data_t* data = (callback_data_t*)user_data;
    data->cross_count++;
    data->last_time = millis();
    // Note: Keep ISR code minimal and fast!
    if (data->cross_count % 100 == 0) {
        // Schedule a task to print statistics
        // Don't use Serial.print() directly in ISR!
    }
}
// Register the callback
rbdimmer_set_callback(0, my_zero_cross_callback, &cb_data);

Notes importantes : - La fonction de rappel s'exécute en contexte d'interruption (ISR) - Gardez le code de rappel minimal et rapide - Aucune opération bloquante (délais, impressions, etc.) - Utilisez les files d'attente FreeRTOS pour la communication avec les tâches - La fonction de rappel est appelée à chaque passage à zéro (100-120 fois par seconde) - En v2.0.0, la fonction de rappel se déclenche uniquement pour les passages à zéro valides qui passent la porte de bruit (rebond). Les faux déclenchements dans RBDIMMER_ZC_DEBOUNCE_US microsecondes du passage à zéro précédent ne déclenchent pas la fonction de rappel.

Fonctions utilitaires

`rbdimmer_update_all()`

rbdimmer_err_t rbdimmer_update_all(void);

Force une mise à jour immédiate de tous les canaux actifs.

Retour : - RBDIMMER_OK : Tous les canaux mis à jour avec succès

Exemple :

// After changing multiple channel parameters
rbdimmer_update_all();

Notes : - Généralement non nécessaire - les canaux se mettent à jour automatiquement - Utile après les modifications de configuration en masse - Recalcule le timing pour tous les canaux actifs

Gestion des erreurs

Descriptions des codes d'erreur

Code d'erreur	Description	Causes courantes
`RBDIMMER_OK`	Succès	Opération complétée normalement
`RBDIMMER_ERR_INVALID_ARG`	Argument invalide	Pointeurs NULL, valeurs hors de portée
`RBDIMMER_ERR_NO_MEMORY`	Allocation mémoire échouée	Mémoire heap insuffisante
`RBDIMMER_ERR_NOT_FOUND`	Objet non trouvé	Phase non enregistrée, canal non trouvé
`RBDIMMER_ERR_ALREADY_EXIST`	L'objet existe déjà	Phase déjà enregistrée
`RBDIMMER_ERR_TIMER_FAILED`	Opération de minuterie échouée	Minuterie matérielle non disponible
`RBDIMMER_ERR_GPIO_FAILED`	Opération GPIO échouée	Broche invalide, broche déjà en utilisation

Meilleures pratiques de gestion des erreurs

rbdimmer_err_t err;
rbdimmer_channel_t* channel;
// Always check return values
err = rbdimmer_init();
if (err != RBDIMMER_OK) {
    Serial.printf("Initialization failed: %d\n", err);
    return;
}
// Handle specific error conditions
err = rbdimmer_register_zero_cross(2, 0, 0);
switch (err) {
    case RBDIMMER_OK:
        Serial.println("Zero-cross registered successfully");
        break;
    case RBDIMMER_ERR_ALREADY_EXIST:
        Serial.println("Phase already registered - continuing");
        break;
    case RBDIMMER_ERR_GPIO_FAILED:
        Serial.println("GPIO configuration failed - check wiring");
        return;
    default:
        Serial.printf("Unexpected error: %d\n", err);
        return;
}

Exemples de code

Configuration de base complète

#include 
rbdimmer_channel_t* dimmer;
void setup() {
    Serial.begin(115200);
    // Initialize library
    if (rbdimmer_init() != RBDIMMER_OK) {
        Serial.println("Library initialization failed");
        return;
    }
    // Register zero-cross detector
    if (rbdimmer_register_zero_cross(2, 0, 0) != RBDIMMER_OK) {
        Serial.println("Zero-cross registration failed");
        return;
    }
    // Create dimmer channel
    rbdimmer_config_t config = {
        .gpio_pin = 4,
        .phase = 0,
        .initial_level = 0,
        .curve_type = RBDIMMER_CURVE_RMS
    };
    if (rbdimmer_create_channel(&config, &dimmer) != RBDIMMER_OK) {
        Serial.println("Channel creation failed");
        return;
    }
    Serial.println("Setup complete");
}
void loop() {
    // Fade up over 2 seconds
    rbdimmer_set_level_transition(dimmer, 100, 2000);
    delay(3000);
    // Fade down over 1 second
    rbdimmer_set_level_transition(dimmer, 0, 1000);
    delay(2000);
}

Contrôle multi-canaux

#include 
#define NUM_CHANNELS 3
rbdimmer_channel_t* channels[NUM_CHANNELS];
uint8_t dimmer_pins[] = {4, 5, 6};
void setup() {
    Serial.begin(115200);
    rbdimmer_init();
    rbdimmer_register_zero_cross(2, 0, 0);
    // Create multiple channels
    for (int i = 0; i < NUM_CHANNELS; i++) {
        rbdimmer_config_t config = {
            .gpio_pin = dimmer_pins[i],
            .phase = 0,
            .initial_level = 0,
            .curve_type = RBDIMMER_CURVE_RMS
        };
        rbdimmer_create_channel(&config, &channels[i]);
    }
    Serial.println("Multi-channel setup complete");
}
void loop() {
    // Sequential fade effect
    for (int i = 0; i < NUM_CHANNELS; i++) {
        rbdimmer_set_level_transition(channels[i], 100, 1000);
        delay(500);
    }
    delay(2000);
    // All off together
    for (int i = 0; i < NUM_CHANNELS; i++) {
        rbdimmer_set_level_transition(channels[i], 0, 1000);
    }
    delay(2000);
}

Utilisation avancée des fonctions de rappel

#include 
typedef struct {
    uint32_t zero_cross_count;
    uint16_t frequency;
    bool frequency_stable;
} system_stats_t;
system_stats_t stats = {0, 0, false};
rbdimmer_channel_t* dimmer;
void zero_cross_isr(void* user_data) {
    system_stats_t* s = (system_stats_t*)user_data;
    s->zero_cross_count++;
    // Check frequency every 100 crossings (avoid frequent updates)
    if (s->zero_cross_count % 100 == 0) {
        s->frequency = rbdimmer_get_frequency(0);
        s->frequency_stable = (s->frequency == 50 || s->frequency == 60);
    }
}
void setup() {
    Serial.begin(115200);
    rbdimmer_init();
    rbdimmer_register_zero_cross(2, 0, 0);
    // Set up callback for monitoring
    rbdimmer_set_callback(0, zero_cross_isr, &stats);
    rbdimmer_config_t config = {
        .gpio_pin = 4,
        .phase = 0,
        .initial_level = 50,
        .curve_type = RBDIMMER_CURVE_RMS
    };
    rbdimmer_create_channel(&config, &dimmer);
}
void loop() {
    // Print statistics every 5 seconds
    static unsigned long last_print = 0;
    if (millis() - last_print > 5000) {
        Serial.printf("Zero crossings: %d\n", stats.zero_cross_count);
        Serial.printf("Frequency: %d Hz\n", stats.frequency);
        Serial.printf("Frequency stable: %s\n", stats.frequency_stable ? "Yes" : "No");
        Serial.printf("Current level: %d%%\n", rbdimmer_get_level(dimmer));
        Serial.println("---");
        last_print = millis();
    }
    delay(100);
}

Considérations de performance

Utilisation de la mémoire

Chaque canal utilise environ 200 octets de RAM
Surcharge de la bibliothèque globale : ~1 KB RAM
Utilisation de la mémoire flash : ~32 KB

Précision du timing

Détection du passage à zéro : +/-10 microsecondes (après filtrage de la porte de bruit)
Activation du TRIAC : +/-1 microseconde
Mesure de fréquence : +/-0.1 Hz

Surcharge CPU

Gestion d'interruption : <50 microsecondes par passage à zéro
Traitement en arrière-plan : <1% d'utilisation CPU
Tâches de transition : Impact minimal sur les autres opérations

Limitations

Maximum 8 canaux par ESP32
Maximum 4 phases indépendantes
Largeur d'impulsion minimale : 50 microsecondes
Délai de tir minimal : 100 microsecondes (RBDIMMER_MIN_DELAY_US)
Plage de variateur efficace : 3%-99% (RBDIMMER_LEVEL_MIN à RBDIMMER_LEVEL_MAX)
Temps de transition maximal : Limité par la mémoire disponible pour les tâches

Cette référence d'API couvre toutes les fonctions publiques et les types de données dans rbdimmerESP32 v2.0.0

Produits

En Vedette

Commencer

Intégrations

Guides et Articles

ACRouter

Vitrine de Projets

Commencer

Intégrations

Variateurs AC

DimmerLink

ACRouter

GitHub

Référence d'API rbdimmerESP32

Aperçu

Principes de conception clés

Types de données

Types opaques

rbdimmer_channel_t

Structures de configuration

rbdimmer_config_t

Énumérations

rbdimmer_curve_t

rbdimmer_err_t

timer_state_t

Constantes

Limites du système

Constantes de temporisation

Porte de bruit de passage à zéro (v2.0.0)

Constantes de limite de niveau (v2.0.0)

Constantes de fréquence

Fonctions d'initialisation

rbdimmer_init()

rbdimmer_deinit()

Gestion du passage à zéro

rbdimmer_register_zero_cross()

Gestion des canaux

rbdimmer_create_channel()

rbdimmer_delete_channel()

Contrôle du niveau

rbdimmer_set_level()

rbdimmer_set_level_transition()

Fonctions de configuration

rbdimmer_set_curve()

rbdimmer_set_active()

Récupération d'informations

rbdimmer_get_level()

rbdimmer_get_frequency()

rbdimmer_is_active()

rbdimmer_get_curve()

rbdimmer_get_delay()

Fonctions de rappel

rbdimmer_set_callback()

Fonctions utilitaires

rbdimmer_update_all()

Gestion des erreurs

Descriptions des codes d'erreur

Meilleures pratiques de gestion des erreurs

Exemples de code

Configuration de base complète

Contrôle multi-canaux

Utilisation avancée des fonctions de rappel

Considérations de performance

Utilisation de la mémoire

Précision du timing

Surcharge CPU

Limitations

`rbdimmer_channel_t`

`rbdimmer_config_t`

`rbdimmer_curve_t`

`rbdimmer_err_t`

`timer_state_t`

`rbdimmer_init()`

`rbdimmer_deinit()`

`rbdimmer_register_zero_cross()`

`rbdimmer_create_channel()`

`rbdimmer_delete_channel()`

`rbdimmer_set_level()`

`rbdimmer_set_level_transition()`

`rbdimmer_set_curve()`

`rbdimmer_set_active()`

`rbdimmer_get_level()`

`rbdimmer_get_frequency()`

`rbdimmer_is_active()`

`rbdimmer_get_curve()`

`rbdimmer_get_delay()`

`rbdimmer_set_callback()`

`rbdimmer_update_all()`