rbdimmerESP32 - Professionelle AC-Dimmerbibliothek für ESP32

v2.0.0 Breaking Changes: Internes Quellenlayout wurde in src/internal/-Module geändert. Beispiele wurden in separate Sketch-Verzeichnisse umstrukturiert (Arduino IDE 2.x). Kconfig.txt wurde in Kconfig umbenannt. Öffentliche API unverändert — keine Änderungen am Benutzercode erforderlich.

Eine professionelle, leistungsstarke AC-Dimmersteuerbibliothek für ESP32-Mikrocontroller. Entwickelt für Präzisions-Timing, Hardwareeffizienz, Multi-Phase- und Multi-Channel-Betrieb mit Unterstützung für verschiedene Lasttypen, einschließlich Glühbirnen, LED-Dimmer und Motorsteuerungsanwendungen.

Wichtigste Funktionen

Hardwareoptimierung

Hardware Timer Integration: Uses ESP32's high-resolution timers for microsecond precision
Interrupt-getriebene Architektur: Minimaler CPU-Overhead mit Hardware-Interrupt-Handling
Multi-Phase-Unterstützung: Bis zu 4 unabhängige AC-Phasen mit individueller Zero-Cross-Erkennung
Automatische Frequenzerkennung: Unterstützt sowohl 50Hz als auch 60Hz Netzfrequenz mit Auto-Erkennung
IRAM_ATTR ISR-Platzierung: Alle zeitkritischen Pfade in IRAM für deterministische Latenz
ESP_TIMER_ISR-Versand: Timer-Callbacks vom ISR-Kontext aus versandt für minimales Jitter
Zero-Cross-Rausch-Gate: Hardware-validierter Entprell-Filter eliminiert falsche Auslöser durch TRIAC-Schaltimpulse

Erweiterte Steuerung

Multiple Helligkeitskurven: Linear, RMS-kompensiert und logarithmisch für verschiedene Lasten
Sanfte Übergänge: Nicht-blockierende Helligkeitsübergänge mit FreeRTOS-Aufgaben
Multi-Channel-Betrieb: Steuern Sie bis zu 8 unabhängige Dimmerkanäle gleichzeitig
Echtzeit-Synchronisation: Phasengebundener Betrieb mit Netzfrequenz

Professionelle Funktionen

Umfassendes Fehlerbehandlung: Detaillierte Fehlercodes und Diagnoseinformationen
Thread-sicheres Design: Vollständige FreeRTOS-Kompatibilität mit ordnungsgemäßer Ressourcenverwaltung
Umfangreiche Dokumentation: Komplette Doxygen-Dokumentation mit Beispielen
Plattformübergreifende Unterstützung: Funktioniert mit Arduino IDE und ESP-IDF

Modulare Architektur

v2.0.0 ersetzt die monolithische Einzeldatei-Implementierung durch sechs interne Module:

Modul	Verantwortung
`rbdimmer_zerocross`	ZC-GPIO-ISR, Frequenzmessung, Rausch-Gate
`rbdimmer_channel`	Channel-Status, ZC-Phase-Versand, Zwei-Pass-ISR
`rbdimmer_timer`	esp_timer create/start/stop Wrapper
`rbdimmer_curves`	Level → Verzögerungs-Konvertierung (LINEAR, RMS, LOG)
`rbdimmer_transition`	FreeRTOS-Aufgaben-basierter sanfter Fade
`rbdimmer_types`	Gemeinsame Strukturen und Enums
`rbdimmer_hal`	GPIO/Timer HAL Shims für Arduino/ESP-IDF Portabilität

Hinweis: Die öffentliche Header-Datei (rbdimmerESP32.h) API ist unverändert — Benutzercode erfordert keine Änderung.

Schnelleinstieg

Arduino IDE Installation

Bibliothek herunterladen von GitHub
In Arduino IDE: Sketch → Bibliothek einbinden → .ZIP Bibliothek hinzufügen
Wählen Sie die heruntergeladene ZIP-Datei aus
Fügen Sie in Ihren Sketch ein:

cpp

#include

Grundlegendes Verwendungsbeispiel

cpp

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

Hardwareanforderungen

Unterstützte Boards

ESP32 DevKit: Alle Varianten (ESP32-WROOM-32, ESP32-WROVER, etc.)
ESP32-S2: Single-Core ESP32 Variante mit USB OTG
ESP32-S3: Dual-Core mit erweiterten KI-Fähigkeiten und USB
ESP32-C3: RISC-V basiert, ultra-niedriger Stromverbrauch
ESP32-C6: Wi-Fi 6 Unterstützung mit 802.11ax
ESP32-H2: Dediziert für Thread/Zigbee-Anwendungen
ESP32-P4: Hochleistungs-Variante mit erweiterter Verarbeitung
ESP32-C2: Kostengünstig mit wesentlicher Konnektivität
Kompatible Third-Party-Boards: Wemos D1 Mini ESP32, NodeMCU-32S, etc.

Framework-Kompatibilität Matrix

ESP32 Chip	Arduino Core	ESP-IDF	ESPHome
ESP32	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-S2	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-S3	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-C3	✅ 3.x	✅ 5.3+	✅ 2023.x+
ESP32-C6	✅ 3.x	✅ 5.3+	⏳ Demnächst
ESP32-H2	✅ 3.x	✅ 5.3+	✅ 2024.x+
ESP32-P4	⏳ Demnächst	✅ 5.3+	⏳ Demnächst
ESP32-C2	✅ 3.x	✅ 5.3+	⚠️ Begrenzt

Dimmer-Hardware

Diese Bibliothek ist für die Verwendung mit vorgefertigten Dimmermodulen ausgelegt, die folgende Funktionen enthalten: - Zero-Cross-Erkennungsschaltung - TRIAC oder Solid-State-Relais-Treiber - Optische Isolation für Sicherheit - Angemessene Wärmeableitung

⚠️ Sicherheitswarnung: AC-Netzspannung ist gefährlich. Verwenden Sie nur zertifizierte Dimmermodule mit ordnungsgemäßer Isolation.

Verdrahtungsbeispiel

plaintext

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)

Dokumentation

Dokument	Beschreibung
API-Referenz	Vollständige API-Dokumentation
Hardware-Anleitung	Verdrahtungsdiagramme und Sicherheit
Fehlerbehebung	Häufige Probleme und Lösungen
Beispiele	Alle Beispiel-Sketches erklärt
Änderungsprotokoll	Versionshistorie

Plattformspezifische Leitfäden

Arduino-Anleitung: Arduino Framework Setup und Beispiele
ESP-IDF-Anleitung: ESP-IDF Framework Setup und Beispiele
Vollständiger Bibliotheksüberblick: Umfassende Dokumentation

Erweiterte Funktionen

Multiple Helligkeitskurven

Wählen Sie die optimale Kurve für Ihren Lasttyp und die gewünschte visuelle Reaktion:

cpp

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

Detaillierte Kurvenmerkmale:

Linear (RBDIMMER_CURVE_LINEAR) - Einheitliche Änderung der Phasenverzögerung - Direkte Konvertierung von Prozentsatz zu Verzögerung - Geeignet für Motorsteuerung und einfache Anwendungen - ⚠️ Hinweis: Wahrgenommene Helligkeit ist nicht visuell linear
RMS (RBDIMMER_CURVE_RMS) - Kompensiert RMS-Charakteristiken des sinusförmigen AC - Bietet lineare Leistungsänderung: Leistung ∝ Level² - Ideal für Glühbirnen und ohmsche Lasten - Basierend auf: angle = arccos(√(level/100))
Logarithmisch (RBDIMMER_CURVE_LOGARITHMIC) - Kompensiert logarithmische Helligkeitswahrnehmung - Bietet visuell lineare Helligkeitsänderungen - Empfohlen für LED-Beleuchtung und Displays - Basierend auf: log₁₀(1 + 9×(level/100))

Leistungsoptimierung

Hardware-Timer-Nutzung

ESP-Timer Integration: Uses ESP32's high-resolution software timers
Mikrosekunden-Präzision: ±1-10μs Timing-Genauigkeit unter normaler Last
Ressourceneffizient: 2 Timer pro Kanal (Verzögerung + Pulsbreite)
IRAM-Platzierung: Kritischer ISR-Code in IRAM für Geschwindigkeit

Interrupt-Optimierung

cpp

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

Speicheroptimierung

Vorberechnete Tabellen: Helligkeitskurven werden bei Initialisierung berechnet
Effizientes Caching: Parameter zwischengespeichert, um wiederholte Berechnungen zu reduzieren
Minimale RAM-Nutzung: ~200 Bytes pro Kanal + ~1KB globaler Overhead
Flash-Optimierung: ~32KB gesamter Flash-Footprint

Debug- und Logging-System

Aktivieren Sie umfassendes Logging für Entwicklung und Fehlerbehebung:

cpp

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

Multi-Channel-Steuerung

cpp

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

Echtzeit-Callbacks

cpp

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

Kconfig-Parameter

Vier einstellbare Parameter für ESP-IDF-Builds (Arduino verwendet Compile-Zeit-Standardwerte):

Parameter	Standard	Beschreibung
`CONFIG_RBDIMMER_ZC_DEBOUNCE_US`	3000 µs	Rausch-Gate-Fenster nach gültigem ZC-Edge
`CONFIG_RBDIMMER_MIN_DELAY_US`	100 µs	Minimale ZC→TRIAC-Verzögerung
`CONFIG_RBDIMMER_LEVEL_MIN`	3 %	Level unter diesem Wert → AUS
`CONFIG_RBDIMMER_LEVEL_MAX`	99 %	Level über diesem Wert → begrenzt

Anwendungsfälle

Hausautomation

Intelligente Beleuchtungssteuerung mit sanftem Dimmen
Integration mit IoT-Plattformen (Home Assistant, OpenHAB)
Sprachsteuerung und Smartphone-Apps
Energieüberwachung und -optimierung

Kommerzielle Anwendungen

Bühnen- und Theaterbeleuchtung
Restaurant- und Gastgewerbe-Ambiente
Einzelhandelsauslage-Beleuchtung
Industrielle Prozesssteuerung

Bildungsprojekte

Leistungselektronik-Demonstrationen
AC-Phasensteuerungs-Experimente
Echtzeitsystem-Lernen
Embedded-Programmierbildung

Maker-Projekte

Benutzerdefinierte Lampenregler
Halloween/Weihnachtsbeleuchtungseffekte
Musiksynchronisierte Beleuchtung
Temperaturgesteuerte Lüftersteuerung

Häufige Probleme und schnelle Lösungen

Allgemeines Flimmern oder instabile Helligkeit

Mögliche Ursachen: - Falsche AC Neutral/Leitung Verbindungen - Zero-Cross-Detektor-Signalprobleme - TRIAC-Schaltimpulse lösen ZC-Erkennung erneut aus - Hohe CPU-Last oder Interrupt-Konflikte

Schnelle Lösungen: - Das v2.0.0 Zero-Cross-Rausch-Gate (ZC_DEBOUNCE_US = 3000µs) filtert TRIAC-Spike-Reauslöser automatisch - Versuchen Sie eine andere Kurve für Ihren Lasttyp:

cpp

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

Flimmern bei 100% Helligkeit

Ursache: Minimale Verzögerung zu kurz oder Level überschreitet sicheren Bereich.

Behebung in v2.0.0: MIN_DELAY_US von 50 auf 100µs erhöht. Level bei oder über 100% werden auf LEVEL_MAX (99%) abgebildet, wodurch Vollein-Fehler verhindert werden.

Multi-Channel-Synchronisierungsdrift

Ursache: Kanäle werden in einem ZC-Event zu leicht unterschiedlichen Zeiten bewaffnet.

Behebung in v2.0.0: Zwei-Pass-ISR — Pass 1 setzt alle GPIOs zurück, Pass 2 bewaffnet alle Timer. Dies garantiert, dass alle Kanäle bei jedem Zero-Cross vom gleichen Basiszustand beginnen.

Flimmern unter 3% Helligkeit

Ursache: TRIAC kann bei sehr niedrigen Leitungswinkeln nicht zuverlässig halten.

Behebung in v2.0.0: Level unter LEVEL_MIN (3%) werden als AUS behandelt, was erratisches Flimmern am unteren Ende des Dimmbereichs eliminiert.

Lastspezifische Helligkeitsprobleme

Bei 50% Einstellung scheint die Lampe zu hell/dunkel zu sein:

cpp

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

Kein Dimmer-Ansprechen

Überprüfen Sie die Zero-Cross-Erkennung:

cpp

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

CI Build-Matrix

Automatisierte CI stellt sicher, dass jeder Commit über alle unterstützten Plattformen sauber erstellt wird:

Arduino: arduino/compile-sketches@v1, Core 3.x, 4 Beispiele × 5 Chips (ESP32, S2, S3, C3, C6)
ESP-IDF: espressif/esp-idf-ci-action@v1, IDF v5.3/v5.4/v5.5 × 5 Chips = 15 Jobs
test_app/: Minimales ESP-IDF-Projekt zur Compile-Zeit-API-Oberflächenverifikation

Unterstützte Plattformen

Arduino Framework

Arduino IDE 2.x
Nahtlose Integration mit Arduino-Bibliotheken

ESP-IDF Framework

ESP-IDF 5.3+ mit CMake-Unterstützung
Professionelle Entwicklungsfunktionen

Entwicklungswerkzeuge

Visual Studio Code mit ESP-IDF-Erweiterung
CLion mit ESP-IDF-Plugin
Eclipse CDT mit ESP-IDF-Tools
Befehlszeilen-Entwicklungsunterstützung

Leistungsmerkmale

Funktion	Spezifikation	Anmerkungen
Timing-Präzision	±1-10 Mikrosekunden	Hängt von der Systemlast ab
Max. Kanäle	8 gleichzeitig	2 Timer pro Kanal
Max. Phasen	4 unabhängig	GPIO- und speicherbegrenzt
Frequenzbereich	45-65 Hz Auto-Erkennung	50/60Hz primär unterstützt
Antwortzeit	< 20ms (ein AC-Zyklus)	Nächster Zero-Cross
CPU-Overhead	< 1% (Interrupt-getrieben)	IRAM-optimierter ISR
Speichernutzung	~8KB RAM, ~32KB Flash	Skaliert mit Kanälen
Timer-Auflösung	1 Mikrosekunde	ESP-Timer basiert
Jitter-Toleranz	±10-50μs unter Last	FreeRTOS-abhängig

ESP-Timer-Architektur Vorteile

Software-Implementierung: Ermöglicht zahlreiche gleichzeitige Timer
Warteschlangen-basierte Ausführung: Nach Auslösezeit sortiert für Effizienz
Geringer Overhead: Einzelner Hardware-Timer bedient alle Software-Timer
ISR-Versand: Timer-Callbacks direkt vom ISR-Kontext versandt für minimales Jitter

Leistungsbeschränkungen

Timer-Jitter: ±10-50μs möglich unter hoher Systemlast
Callback-Beschränkungen: Sollten die Ausführung nicht für längere Zeit blockieren
Speicherskalierung: Jeder Kanal benötigt ~200 Bytes RAM
GPIO-Einschränkungen: Verfügbare Pins variieren je nach ESP32-Variante

Bibliotheksvergleich

Funktion	rbdimmerESP32	Andere Bibliotheken
Hardware-Timer	✅ Native ESP32-Timer	❌ Software-Verzögerungen
Multi-Phase	✅ Bis zu 4 Phasen	❌ Nur einzige Phase
Frequenzerkennung	✅ Automatisch	❌ Manuelle Konfiguration
Kurventypen	✅ 3 integriert + benutzerdefiniert	❌ Nur Linear
Thread-Sicherheit	✅ FreeRTOS-kompatibel	❌ Grundlegende Implementierung
Fehlerbehandlung	✅ Umfassend	❌ Begrenzt
Dokumentation	✅ Professionelle Dokumentation	❌ Grundlegende Beispiele

Beitragen

Wir freuen uns auf Beiträge der Gemeinschaft! Bitte lesen Sie unseren Beitragsleitfaden für:

Code-Style-Richtlinien
Testverfahren
Pull-Request-Prozess
Issue-Reporting-Vorlagen
Entwicklungsumgebung-Setup

Beispiele

Beispiel	Plattform	Beschreibung	Komplexität
BasicDimmer	Arduino	Einfaches Ein/Aus-Dimmen	Anfänger
BasicTransition	Arduino	Sanfte Helligkeitsübergänge	Anfänger
MultiDimmer	Arduino	Multi-Channel-Steuerung	Mittelstufe
ZCCallBack	Arduino	Zero-Cross-Callbacks	Fortgeschritten
BasicDimmer.c	ESP-IDF	C-basierte Dimmersteuerung	Mittelstufe
MultiDimmer.c	ESP-IDF	Multi-Channel mit C	Fortgeschritten
ZCCallBack.c	ESP-IDF	Erweiterte Interrupt-Behandlung	Experte
ESPHome Basic	ESPHome	YAML-Konfiguration Setup	Anfänger
ESPHome Advanced	ESPHome	Multi-Channel YAML-Konfiguration	Mittelstufe

Unterstützung & Gemeinschaft

Offizielle Ressourcen

Website: https://rbdimmer.com
Dokumentation: https://www.rbdimmer.com/docs/universal-library-for-esp32
Hardware-Katalog: https://www.rbdimmer.com/dimmers-pricing
Projektgalerie: https://www.rbdimmer.com/blog/integration-guides-8

Community-Unterstützung

Forum: https://forum.rbdimmer.com
GitHub-Probleme: Berichten Sie Fehler und fordern Sie Funktionen an
GitHub-Diskussionen: Community-Diskussionen und Fragen/Antworten

Professionelle Unterstützung

Für kommerzielle Anwendungen, Enterprise-Unterstützung und benutzerdefinierte Entwicklung: - E-Mail: [email protected] - Technische Beratung: Verfügbar für komplexe Projekte - Benutzerdefinierte Entwicklung: Maßgeschneiderte Lösungen für spezifische Anforderungen

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die LICENSE -Datei für Details.