Skip to Content

Changelog

All notable changes to the rbdimmerESP32 library will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[2.0.0] - 2026-03-23

Overview

Complete architectural rewrite. The monolithic single-file implementation has been replaced with a fully modular internal architecture. All timing-critical paths now use IRAM_ATTR placement and ESP_TIMER_ISR dispatch. Hardware validation on a 4-channel board revealed and resolved three independent flickering issues that were not reproducible in simulation.

Breaking Changes

  • Internal source layout changed from single rbdimmerESP32.cpp to src/internal/ modules. Direct inclusion of internal headers is no longer supported.
  • Examples restructured from flat .ino/.c files to per-sketch directories (required for Arduino IDE 2.x library manager).
  • Kconfig.txt removed — ESP-IDF component config now uses the standard Kconfig filename. Projects that referenced Kconfig.txt must update.
  • Public header (rbdimmerESP32.h) API is unchanged — user code does not need to be modified.

Added

  • Modular Architecture — implementation split into seven internal modules:
  • rbdimmer_zerocross — ZC GPIO ISR, frequency measurement, noise gate
  • rbdimmer_channel — Channel state, ZC phase dispatch, two-pass ISR
  • rbdimmer_timer — esp_timer create/start/stop wrappers
  • rbdimmer_curves — Level → delay conversion (LINEAR, RMS, LOG)
  • rbdimmer_transition — FreeRTOS task-based smooth fade
  • rbdimmer_types — Shared structs and enums
  • rbdimmer_hal — GPIO/timer HAL shims for Arduino/ESP-IDF portability
  • Kconfig parameters for ESP-IDF tuning:
  • CONFIG_RBDIMMER_ZC_DEBOUNCE_US (default 3000 µs) — noise gate window
  • CONFIG_RBDIMMER_MIN_DELAY_US (default 100 µs) — minimum ZC→TRIAC delay
  • CONFIG_RBDIMMER_LEVEL_MIN (default 3%) — levels below → OFF
  • CONFIG_RBDIMMER_LEVEL_MAX (default 99%) — levels above → capped
  • CI Build Matrix (.github/workflows/build.yml):
  • Arduino: arduino/compile-sketches@v1, Core 3.x, 4 examples × 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/ — minimal ESP-IDF project for compile-time API surface verification

Fixed

  • General flickering at all brightness levels — TRIAC switching spike re-triggered ZC ISR mid half-cycle. Added noise gate: any ZC edge within ZC_DEBOUNCE_US (3000 µs) of previous valid edge is discarded.
  • Flickering at 100% brightness — at 50 µs delay the AC voltage (~5V) was below TRIAC latching threshold; plus esp_timer ISR dispatch from level-3 GPIO ISR made sub-100 µs delays unpredictable. MIN_DELAY_US raised from 50 → 100 µs; levels ≥ 100% mapped to LEVEL_MAX (99%).
  • Multi-channel synchronization — per-channel phase offsets caused by sequential GPIO reset + timer arm in single loop. Two-pass ISR: Pass 1 sets all GPIOs LOW, Pass 2 arms all delay timers.
  • Flickering at levels below 3% — AC voltage too low for reliable TRIAC latching near end of half-cycle. Levels below LEVEL_MIN (3%) return delay = 0 (channel OFF).

Changed

  • All ISR handlers now use IRAM_ATTR placement
  • Timer dispatch changed to ESP_TIMER_ISR for minimum jitter
  • Minimum supported ESP-IDF version: 5.3 (was 4.4)
  • Arduino ESP32 Core minimum: 3.x (was 2.0.0)

[1.0.0] - 2024-01-01

Added

  • Initial release
  • Single-file implementation
  • Support for ESP32, ESP32-S2, ESP32-S3, ESP32-C3
  • Three brightness curves: LINEAR, RMS, LOGARITHMIC
  • Multi-channel and multi-phase support
  • Smooth transitions via FreeRTOS tasks
  • Arduino IDE and ESP-IDF support
[2.0.0] - 2026-03-23 [1.0.0] - 2024-01-01