Wrong Library: RBDdimmer Instead of rbdimmerESP32 on ESP32

TL;DR: For ESP32 you need rbdimmerESP32 — not the old RBDdimmer. The old library was written for Arduino AVR: no IRAM_ATTR, no core pinning, no race condition protection. On ESP32 it causes Guru Meditation Error, random reboots, or erratic setPower() behavior. Conversely, for Arduino Uno/Mega use RBDdimmer — rbdimmerESP32 won't compile there.

Problem Description

You grab a tutorial that uses #include <RBDdimmer.h>, upload it to an ESP32 — and get one of the following:

• Guru Meditation Error when WiFi is active (crash in ISR handler)
• Random reboots with no apparent cause
• setPower() doesn't give the expected brightness — chaotic load behavior
• Compiler warnings about IRAM_ATTR and deprecated APIs

Or the reverse — rbdimmerESP32 on Arduino Uno:

• error: 'xTaskCreatePinnedToCore' was not declared in this scope

Typical forum messages:

• Guru Meditation Error: Core 1 panic'ed (Cache disabled but cached memory region accessed)
• error: 'xTaskCreatePinnedToCore' was not declared in this scope
• warning: 'IRAM_ATTR' attribute ignored
• "setPower(50) — lamp goes dark then jumps to full brightness"

Root Cause

The rbdimmer ecosystem has two separate libraries for different platforms:

They are not interchangeable. Key technical differences:

• RBDdimmer doesn't use IRAM_ATTR → ISR runs from flash → when WiFi is active flash cache gets disabled → crash. Details: troubleshooting/esp32-iram-attr.md
• RBDdimmer doesn't pin the task to a specific core → on dual-core ESP32 it competes with the WiFi task → timing jitter → unstable brightness
• rbdimmerESP32 uses xTaskCreatePinnedToCore from FreeRTOS → won't compile on Arduino AVR (no FreeRTOS)

Solutions

🟢 For beginners: DimmerLink — one library for all platforms

Don't want to worry about which library to use? DimmerLink is controlled via I2C — the same code works on Arduino, ESP32, ESP8266, and RPi.

DimmerLink has its own zero-cross controller and TRIAC timing. Your microcontroller only sets the brightness level over I2C. No ISR, no IRAM_ATTR, no per-platform library selection.

Code:

// DimmerLink — works on Arduino, ESP32, ESP8266, Raspberry Pi
// Docs: https://www.rbdimmer.com/docs/dimmerlink-I2CCommunication
#include <Wire.h>
#define DIMMER_ADDR 0x50
#define REG_LEVEL   0x10
void setLevel(uint8_t level) {  // level: 0–100%
    Wire.beginTransmission(DIMMER_ADDR);
    Wire.write(REG_LEVEL);
    Wire.write(level);
    Wire.endTransmission();
}
void setup() {
    Wire.begin();      // default SDA/SCL for your board
    setLevel(50);      // 50% brightness
}
void loop() {}

Result: No library-selection headaches — identical code on any platform.

🔵 For advanced users: correct library for your platform

Want direct ISR connection? Use the right library.

Install rbdimmerESP32 (for ESP32)

In Arduino IDE:

• Sketch → Include Library → Manage Libraries
• Search for: rbdimmerESP32
• Install: by RobotDyn

In PlatformIO (platformio.ini):

lib_deps =
    https://github.com/robotdyn-dimmer/rbdimmerESP32

Migrating code from RBDdimmer to rbdimmerESP32

// ─────────────── BEFORE (RBDdimmer — not for ESP32) ───────────────────
#include <RBDdimmer.h>
dimmerLamp dimmer(DIM_PIN, ZC_PIN);
void setup() {
    // NORMAL_MODE, ON — RBDdimmer constants, don't exist in rbdimmerESP32
    dimmer.begin(NORMAL_MODE, ON);
    dimmer.setPower(50);
}
// ──────────────── AFTER (rbdimmerESP32 — correct for ESP32) ───────────
#include "rbdimmerESP32.h"
rbdimmer dimmer;
void setup() {
    // Pin order: ZC_PIN, DIM_PIN (reversed compared to RBDdimmer!)
    dimmer.begin(ZC_PIN, DIM_PIN, 50);  // third parameter — mains frequency
    dimmer.setPower(50);
}

⚠️ Pin order in begin() changed: in RBDdimmer the constructor took (DIM, ZC), in rbdimmerESP32 the begin() method takes (ZC, DIM, freq). Swap them and the load won't regulate.

Quick test after migration (sweep 10→90→10%):

// Visual test: smooth sweep 10% → 90% → 10%
// If the load responds — library and pins are correct
#include "rbdimmerESP32.h"
#define ZC_PIN  18  // any GPIO on ESP32
#define DIM_PIN 19  // any GPIO on ESP32
rbdimmer dimmer;
void setup() {
    Serial.begin(115200);
    dimmer.begin(ZC_PIN, DIM_PIN, 50);  // 50 Hz mains
    delay(500);
}
void loop() {
    for (int p = 10; p <= 90; p += 10) {
        dimmer.setPower(p);
        Serial.println(p);
        delay(500);
    }
    for (int p = 90; p >= 10; p -= 10) {
        dimmer.setPower(p);
        Serial.println(p);
        delay(500);
    }
}

⚠️ Common pitfalls

• "Found a tutorial using RBDdimmer on ESP32 — it says it works": Tutorials from 2019–2022 often use the old library on ESP32. After rbdimmerESP32 was released, those examples became outdated. Look for examples using rbdimmerESP32.

• "ESP8266 + RBDdimmer + WiFi — unstable": ESP8266 is single-core; the WiFi SDK periodically takes over the CPU. Symptoms are similar to single-core ESP32: timing jitter with active WiFi. For reliable ESP8266 projects with WiFi — use DimmerLink over I2C.

• "Tried rbdimmerESP32 on Uno — won't compile": rbdimmerESP32 requires FreeRTOS (xTaskCreatePinnedToCore), which doesn't exist on AVR. For Uno/Nano/Mega use RBDdimmer.

• "Installed both libraries — header conflict": Arduino IDE may mix up files. Remove the one you don't need via Sketch → Include Library → Manage Libraries.

• "Pin order looks the same — why isn't it working?": dimmerLamp dimmer(DIM, ZC) vs dimmer.begin(ZC, DIM, freq) — ZC and DIM are swapped. Check this first.

• "setPower() compiles and does something — but unstable": RBDdimmer may run on ESP32 without an explicit crash — but without IRAM_ATTR and core pinning, timing is unreliable. That's not "working" — that's "occasionally coincides". Switch to rbdimmerESP32.

Quick Check

Library Compatibility Table

Related Issues

• ESP32 + TRIAC: Guru Meditation Error → troubleshooting/esp32-iram-attr.md
• ESP32-S2/C3 single-core → troubleshooting/esp32-single-core-dimmer.md
• Zero-cross not detected → troubleshooting/zero-cross-detection-errors.md

Still have questions?

Ask on forum.rbdimmer.com or open a GitHub Issue.