MycilaDimmer

License: MIT Continuous Integration PlatformIO Registry

A comprehensive ESP32/Arduino library for controlling AC power devices including TRIACs, SSRs, and voltage regulators through multiple dimming methods.

Table of Contents

Overview

MycilaDimmer provides a unified interface for controlling AC power devices through different hardware implementations. The library uses a polymorphic architecture that allows you to switch between different dimming methods without changing your application code.

Key Benefits:

Features

Hardware Support

Supported Platforms

Supported Hardware

Installation

PlatformIO

[env:myproject]
lib_deps =
    mathieucarbou/MycilaDimmer

Arduino IDE

  1. Go to Sketch → Include Library → Manage Libraries
  2. Search for “MycilaDimmer”
  3. Install the library by Mathieu Carbou

Quick Start

#include <MycilaDimmer.h>

// Create a PWM dimmer instance
Mycila::PWMDimmer dimmer;

void setup() {
  Serial.begin(115200);

  // Configure the dimmer
  dimmer.setPin(GPIO_NUM_26);
  dimmer.begin();

  // Set 50% power
  dimmer.setDutyCycle(0.5);
}

void loop() {
  // Gradually increase power
  for (float power = 0.0; power <= 1.0; power += 0.1) {
    dimmer.setDutyCycle(power);
    delay(1000);
  }
}

Dimmer Types

Zero-Cross Dimmer

Perfect for TRIAC and Random SSR control with flicker-free progressive dimming. Achieves smooth, continuous power control through precise phase angle control when paired with quality zero-cross detection circuits.

#include <MycilaDimmer.h>

Mycila::ZeroCrossDimmer dimmer;

void setup() {
  dimmer.setPin(GPIO_NUM_26);
  dimmer.setSemiPeriod(10000); // 50Hz AC (10ms semi-period)
  dimmer.begin();

  // Register with external zero-cross detector
  pulseAnalyzer.onZeroCross(Mycila::ZeroCrossDimmer::onZeroCross);
}

Features:

The Zero-Cross Detector mounted on DIN Rail mount from Daniel is is very good and reliable. I sometimes buy it in bulk from PCBWay. If you want one, you can have a look at the YaSolR Pro page for the stock status.

PWM Dimmer

Standard PWM output for SSRs and other PWM-controlled devices.

#include <MycilaDimmer.h>

Mycila::PWMDimmer dimmer;

void setup() {
  dimmer.setPin(GPIO_NUM_26);
  dimmer.setFrequency(1000);  // 1kHz PWM
  dimmer.setResolution(12);   // 12-bit resolution
  dimmer.begin();
}

Features:

For example, this dimmer can be used with a 3.3V to 0-5V/0-10V signal converter

DFRobot DAC Dimmer

Flicker-free progressive dimming using precision I2C DAC modules. Perfect for voltage regulator controlled devices (LSA, LCTC, etc) with 0-10V input, providing ultra-smooth dimming without any visible flickering thanks to high-resolution DAC output.

#include <MycilaDimmer.h>

Mycila::DFRobotDimmer dimmer;

void setup() {
  dimmer.setSKU(Mycila::DFRobotDimmer::SKU::DFR1071_GP8211S);
  dimmer.setDeviceAddress(0x59);
  dimmer.setOutput(Mycila::DFRobotDimmer::Output::RANGE_0_10V);
  dimmer.begin();
}

Supported Models:

Here is a comparison table of the different DFRobot DAC modules.

API Reference

Core Methods

// Power Control
void on();                          // Full power
void off();                         // Turn off
bool setDutyCycle(float dutyCycle); // Set power (0.0-1.0)

// Status
bool isEnabled();                   // Is configured
bool isOnline();                    // Ready for operation
bool isOn();                        // Currently active
float getDutyCycle();               // Current power setting

// Calibration
void setDutyCycleMin(float min);    // Remap 0% point
void setDutyCycleMax(float max);    // Remap 100% point
void setDutyCycleLimit(float limit); // Safety limit

// Measurements
float getPhaseAngle();              // Phase angle (0-180°)
uint16_t getFiringDelay();          // Delay in microseconds
float getFiringRatio();             // On-time ratio

Advanced Features

// Duty Cycle Remapping (Hardware Calibration)
dimmer.setDutyCycleMin(0.1);  // 0% now maps to 10%
dimmer.setDutyCycleMax(0.9);  // 100% now maps to 90%

// Safety Limiting
dimmer.setDutyCycleLimit(0.8); // Never exceed 80% power

// Telemetry (with MYCILA_JSON_SUPPORT)
#ifdef MYCILA_JSON_SUPPORT
JsonDocument doc;
dimmer.toJson(doc.to<JsonObject>());
serializeJson(doc, Serial);
#endif

Configuration

Build Flags

For Zero-Cross Dimmer (IRAM safety):

build_flags =
  -D CONFIG_ARDUINO_ISR_IRAM=1
  -D CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM=1
  -D CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM=1
  -D CONFIG_GPTIMER_ISR_IRAM_SAFE=1
  -D CONFIG_GPIO_CTRL_FUNC_IN_IRAM=1

lib_deps =
  mathieucarbou/MycilaPulseAnalyzer

For JSON Support:

build_flags =
  -D MYCILA_JSON_SUPPORT

lib_deps =
  bblanchon/ArduinoJson

Examples

The library includes comprehensive examples:

Build Configuration

PlatformIO Configuration

[platformio]
lib_dir = .
src_dir = examples/ZeroCross  ; or DAC, PWM, etc.

[env]
framework = arduino
board = esp32dev
build_flags =
  -D CONFIG_ARDUHAL_LOG_COLORS
  -D CORE_DEBUG_LEVEL=ARDUHAL_LOG_LEVEL_DEBUG
  -Wall -Wextra
  ; Zero-Cross specific flags
  -D CONFIG_ARDUINO_ISR_IRAM=1
  -D CONFIG_GPTIMER_ISR_HANDLER_IN_IRAM=1
  -D CONFIG_GPTIMER_CTRL_FUNC_IN_IRAM=1
  -D CONFIG_GPTIMER_ISR_IRAM_SAFE=1
  -D CONFIG_GPIO_CTRL_FUNC_IN_IRAM=1
lib_deps =
  bblanchon/ArduinoJson
  mathieucarbou/MycilaPulseAnalyzer

Dependencies

Troubleshooting

Common Issues

Zero-Cross Dimmer Not Working

PWM Output Not Visible

DFRobot Module Not Responding

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Setup

git clone https://github.com/mathieucarbou/MycilaDimmer.git
cd MycilaDimmer
pio run

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author: Mathieu Carbou
Used in: YaSolR Solar Router